レコードの取扱いに特化したクラス"FileMaker_Record" (3)

前回よりFileMakerレコード情報の取扱いに特化したクラス「FileMaker_Record」について紹介している。1回目と2回目ではおもにレコード情報を取得する機能について紹介した。第3回目では、おもに編集の結果をデータベースに保存するメソッドについて紹介しよう。

今回紹介する機能

取得できる情報	メソッド名	返り値の型
該当レコードを削除する	delete()	object FileMaker_Result
該当レコードより、関連(ポータル)レコードを作成する	newRelatedRecord()	object FileMaker_Record
setField(), setFieldFromTimestamp()で設定した編集値をFileMakerデータベースに保存する	commit()	booleanまたはobject FileMaker_Error
指定したフィールドに編集値をセットする	setField()	void
指定したフィールドにUNIXタイムスタンプ形式の編集値をセットする	setFieldFromTimestamp()	void
バリデートを設定する	validate()	booleanまたはobject FileMaker_Error

これら編集結果を保存する機能のいくつかは、FileMaker_Command_NewクラスやFileMaker_Command_Editクラスで使用できるものと一緒だ。

deleteメソッド (FileMaker/Record.php 239-247行目より)

/**
 * Delete this record from the server.
 *
 * @return FileMaker_Result The response object.
 */
function delete()
{
    return $this->_impl->delete();
}

レコードを完全に削除し、結果をFileMaker_Resultオブジェクトで返す。

newRelatedRecordメソッド (FileMaker/Record.php 186-196行目より)

/**
 * Create a new record in the related set (portal) named by $relatedSet.
 *
 * @param string $relatedSet The name of the portal to create a new record in.
 *
 * @return FileMaker_Record The blank record.
 */
function &newRelatedRecord($relatedSet)
{
    return $this->_impl->newRelatedRecord($this, $relatedSet);
}

• string $relatedSet: 子レコードを作成したいポータル(テーブルオカレンス)名を指定

該当レコードを親とし、指定したポータル(テーブルオカレンス)に子レコードを作成する。結果は空レコードのFileMaker_Recordオブジェクトが返る。当然ながらあらかじめリレーションシップ設定で「このリレーションシップを使用して、このテーブルでのレコードの作成を許可」にチェックを入れておく必要があるので注意しよう。

commitメソッド (FileMaker/Record.php 229-237行目より)

/**
 * Save any changes to this record back to the server.
 *
 * @return boolean True, or a FileMaker_Error on failure.
 */
function commit()
{
    return $this->_impl->commit();
}

後述のsetField()やsetFieldFromTimestamp()でセットした編集値を、FileMakerデータベースに保存する。成功した場合はtrueが、失敗した場合はFileMaker_Errorオブジェクトが返る。

通常レコードの修正にはレコードIDや修正IDが必要だが、FileMaker_ResultオブジェクトからFileMaker_Recordを取りだしている場合はこれらの情報が最初から格納されているので、とくに設定する必要はない。内部実装を確認する限りでは、親レコードがない場合でレコードIDが指定されていなければレコードが作成される様子。

commitメソッドの実装部分 (FileMaker/Implementation/RecordImpl.php 150-174行目より)

 function commit()
 {  
 if ($this->_fm->getProperty('prevalidate')) {
 $V9f7d0ee8 = $this->validate();
if (FileMaker::isError($V9f7d0ee8)) {
 return $V9f7d0ee8;
}
}   
 if (is_null($this->_parent)) {
 if ($this->_recordId) {
 return $this->_commitEdit();
} else {
 return $this->_commitAdd();
}
} else {    
 if (!$this->_parent->getRecordId()) {
 return new FileMaker_Error($this->_fm, 'You must commit the parent record first before you can commit its children.');
}
if ($this->_recordId) {
 return $this->_commitEditChild();
} else {
 return $this->_commitAddChild();
}
}
}

setFieldメソッド (FileMaker/Record.php 122-133行目より)

/**
 * Set the value of $field.
 *
 * @param string $field The field to change.
 * @param string $value The new value.
 * @param integer $repetition The repetition number to set,
 *                            defaults to the first repetition.
 */
function setField($field, $value, $repetition = 0)
{
    return $this->_impl->setField($field, $value, $repetition);
}

• string $field: フィールド名を指定
• string $value: 登録したい値を指定
• integer $repetition: 繰り返しフィールドの場合、繰り返し番号を指定。繰り返し数を指定。デフォルト値は0

setFieldFromTimestampメソッド (FileMaker/Record.php 135-152行目より)

/**
 * Set the new value for a date, time, or timestamp field from a
 * unix timestamp value. If the field is not a date or time field,
 * then an error is returned. Otherwise returns true.
 *
 * If we haven't already loaded layout data for the target of this
 * command, calling this method will cause it to be loaded so that
 * the type of the field can be checked.
 *
 * @param string $field The field to set.
 * @param string $timestamp The timestamp value.
 * @param integer $repetition The repetition number to set,
 *                            defaults to the first repetition.
 */
function setFieldFromTimestamp($field, $timestamp, $repetition = 0)
{
    return $this->_impl->setFieldFromTimestamp($field, $timestamp, $repetition);
}

• string $field: フィールド名を指定
• string $value: 登録したい値を指定
• integer $repetition: 繰り返しフィールドの場合、繰り返し番号を指定。繰り返し数を指定。デフォルト値は0

レコードを変更したい場合はsetField(), setFieldFromTimestamp()を使う。感覚的にはFileMakerスクリプトステップの「フィールド設定」に近い。返り値はなし(void)。

これらはFileMaker_Command_NewクラスやFileMaker_Command_Editクラスの同名メソッドとまったくおなじ動作をする。こまかい使い方・動作についてはバックナンバーを参照されたい。

validateメソッド (FileMaker/Record.php 208-227行目より)

/**
 * Validates either a single field or the whole record against the
 * validation rules that are enforceable on the PHP side - type
 * rules, ranges, four-digit dates, etc. Rules such as unique or
 * existing, or validation by calculation field, cannot be
 * pre-validated.
 *
 * If the optional $fieldName argument is passed, only that field
 * will be validated. Otherwise the record will be validated just
 * as if commit() were called with prevalidation turned on in the
 * API properties. validate() returns TRUE if validation passes,
 * or a FileMaker_Error_Validation object containing details about
 * what failed to validate.
 *
 * @return boolean|FileMaker_Error_Validation Result of field validation on $value.
 */
function validate($fieldName = null)
{
    return $this->_impl->validate($fieldName);
}

• string $fieldName: バリデートをおこないたいフィールド名を指定。省略した場合はクエリ全体に対してバリデートが実行される

validate実行後、validate成功時にtrue, 失敗時にFileMaker_Error_Validationオブジェクトが返る。これもほかのクラスに用意されているvalidate()と同様の動作をする。validate()で事前検証が可能なタイプのフィールドや、使い方については「API for PHPを使うなら覚えておきたいvalidateの使い方」にまとめているので、こちらも参照してほしい。

FileMaker API for PHPのクラスをメソッドを紹介した。次回以降は、FX.phpを使った場合とFileMaker API for PHPを使った場合のコード・機能・パフォーマンス結果を比較・紹介していこうと思う。