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

FileMakerデータベースの構造情報を取得するクラス「FileMaker」「FileMaker_Layout」「FileMaker_Field」「FileMaker_RelatedSet」を。そしてレコードに関連する情報を取得するクラスとして、結果セットの取り扱いに特化した「FileMaker_Result」を紹介してきた。最後に紹介するクラスは「FileMaker_Record」だ。

FileMaker_Recordとは

FileMaker_Resultオブジェクト(結果セット)をもとに、getRecords()、getFirstRecord()、 getLastRecord()を使用してFileMaker_Recordオブジェクトを取得する。このFileMaker_Recordオブジェクトに、実際にFileMakerに格納されているレコード内容が格納されている。このオブジェクトの取り扱いに特化したのが、FileMaker_Recordクラスだ。用意されている機能を大別すると、レコード情報を取得する機能と編集結果を保存する機能の2種類に分類することができる。

同クラスに用意されている機能をまとめた表を示す。

レコード情報を取得

取得できる情報	メソッド名	返り値の型
フィールドに入力されている値	getField()	string
フィールドに入力されている値(UNIXタイムスタンプ形式)	getFieldAsTimestamp()	integer
フィールドに入力されている値(HTMLエンティティを変換しない)	getFieldUnencoded()	string
レコード情報にふくまれている全フィールド名	getFields()	array
レイアウト情報	getLayout()	object FileMaker_Layout
修正ID	getModificationId()	integer
親レコード情報	getParent()	object FileMaker_Recor
レコードID	getRecordId()	integer
関連レコード情報	getRelatedSet()	array, object FileMaker_Record

編集結果を保存する

機能の概要	メソッド名	返り値の型
該当レコードを削除する	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

まずはレコード情報を取得する機能から順に紹介していこう。今回はgetField() /getFieldAsTimestamp() / getFieldUnencoded()の3メソッドを紹介する。

フィールドに入力されている値を取得 - getField() / getFieldAsTimestamp() / getFieldUnencoded()

それぞれフィールドに入力されている値を取得する。

getFieldメソッド (FileMaker/Record.php 77-89行目より)

/**
 * Get the HTML-encoded value of $field.
 *
 * @param string $field The field name to fetch.
 * @param integer $repetition The repetition number to get,
 *                            defaults to the first repetition.
 *
 * @return string The field value.
 */
function getField($field, $repetition = 0)
{
    return $this->_impl->getField($field, $repetition);
}

• string $field: 取得したいフィールド名を指定
• integer $repetition: 繰り返しフィールドの場合、繰り返し数を指定。初期値は0

指定したフィールドに入力されている値を返す。値はhtmlspecialchars()でエンティティ変換される。

getFieldメソッド - 処理部分 (FileMaker/Implementation/RecordImpl.php 25-36行目より)

 function getField($V06e3d36f, $V6d786dc7 = 0)
 {
 if (!isset($this->_fields[$V06e3d36f])) {
 $this->_fm->log('Field "' . $V06e3d36f . '" not found.', FILEMAKER_LOG_INFO);
return "";
}
if (!isset($this->_fields[$V06e3d36f][$V6d786dc7])) {
 $this->_fm->log('Repetition "' . (int)$V6d786dc7 . '" does not exist for "' . $V06e3d36f . '".', FILEMAKER_LOG_INFO);
return "";
}
return htmlspecialchars($this->_fields[$V06e3d36f][$V6d786dc7]);
}

エンティティ変換に不安がある場合は

• 直接RecordImpl.phpの35行目「return htmlspecialchars(...)」部分を変更する
• getField()を使わず、htmlspecialchars(trim(getFieldUnencoded('...')), ENT_QUOTES, 'UTF-8');と置きかえる

といった方法を取ろう。

getFieldAsTimeStampメソッド (FileMaker/Record.php 105-120行目より)

/**
 * Return the value of the specified field (and repetition) as a
 * unix timestamp. If the field is a date field, the timestamp is
 * for the field date at midnight. It the field is a time field,
 * the timestamp is for that time on January 1, 1970. Timestamp
 * (date & time) fields map directly to the unix timestamp. If the
 * specified field is not a date or time field, or if the
 * timestamp generated would be out of range, then we return a
 * FileMaker_Error object instead.
 *
 * @return integer The timestamp value.
 */
function getFieldAsTimestamp($field, $repetition = 0)
{
    return $this->_impl->getFieldAsTimestamp($field, $repetition);
}

• string $field: 取得したいフィールド名を指定
• integer $repetition: 繰り返しフィールドの場合、繰り返し数を指定。初期値は0

指定したフィールドに入力されている値をUNIXタイムスタンプ形式で返す。有効なフィールドタイプは「日付」「時刻」「タイムスタンプ」の3種類のみで、これ以外のタイプや不正なタイムスタンプ値の場合はFileMaker_Errorオブジェクトが返る。その際のエラーメッセージは次のとおり。

フィールドのタイプ	エラー内容	getMessage()で取得できるログメッセージ
日付	「/」が2つではない	Failed to parse "<フィールド名>" as a FileMaker date value.
日付	mktime()に失敗	Failed to convert "<フィールド名>" to a UNIX timestamp.
時刻	「:」が2つではない	Failed to parse "<フィールド名>" as a FileMaker time value.
時刻	mktime()に失敗	Failed to convert "<フィールド名>" to a UNIX timestamp.
タイムスタンプ	strtotime()に失敗	Failed to convert "<フィールド名>" to a UNIX timestamp.
日付/時刻/タイムスタンプ以外	3タイプ以外のフィールドを指定した場合にエラー	Only time, date, and timestamp fields can be converted to UNIX timestamps.

getFieldUnencodedメソッド (FileMaker/Record.php 91-103行目より)

/**
 * Get the unencoded value of $field.
 *
 * @param string $field The field name to fetch.
 * @param integer $repetition The repetition number to get,
 *                            defaults to the first repetition.
 *
 * @return string The unencoded field value.
 */
function getFieldUnencoded($field, $repetition = 0)
{
    return $this->_impl->getFieldUnencoded($field, $repetition);
}

• string $field: 取得したいフィールド名を指定
• integer $repetition: 繰り返しフィールドの場合、繰り返し数を指定。初期値は0

指定したフィールドに入力されている値を返す。エンティティ変換をおこなってしまうと不都合が起きる場合は、getField()の代わりにこちらを使用する。

それではこの3メソッドの動作を確認してみよう。あらたに「fmapi_record_test」レイアウトを作成し、いくつかのフィールドを配置した。配置したフィールドとテスト用に作成したレコードは次のとおり。

実際にこの2レコードを取得し、それぞれ3つのメソッドがどのような動作をするか確認する。

<?php

include_once('../FileMaker.php');

$data = new FileMaker('fmapi_test', 'http://localhost:80', 'admin', 'admin');
// 検索条件を作成
$findCommand = $data->newFindCommand('fmapi_record_test');
$findCommand->setRange(0, 2);
$findCommand->addFindCriterion('ft_serial', '1...2');
$result = $findCommand->execute();

// FileMaker_Resultオブジェクトエラー判定
if (FileMaker::isError($result))
{
    // エラー処理..
    echo 'FileMaker Error Code: ' . $result->getCode();
    echo '<p>'. $result->getMessage() . '</p>';
}
else
{
    // 正常処理
    ?>
    <table border="1">
        <tr>
            <th>&nbsp;</th>
            <th>getFields()</th>
            <th>getFieldAsTimeStamp()</th>
            <th>date &amp; getFieldAsTimeStamp()</th>
            <th>getFieldUnencoded()</th>
        </tr>
        <?php
        foreach( $result->getRecords() as $record )
        {
            foreach( $result->getFields() as $field )
            {
            ?>
            <tr>
                <td><?php echo $field; ?></td>
                <td valign="top">
                    <?php var_dump($record->getField($field)); ?>
                </td>
                <td valign="top">
                    <?php
                    $return = $record->getFieldAsTimeStamp($field);
                    if (FileMaker::isError($return))
                    {
                        echo $return->getMessage();
                    }
                    else
                    {
                        var_dump($record->getFieldAsTimeStamp($field));
                    }
                    unset($return);
                    ?>
                </td>
                <td valign="top">
                    <?php
                    $return = $record->getFieldAsTimeStamp($field);
                    if (FileMaker::isError($return))
                    {
                        echo $return->getMessage();
                    }
                    else
                    {
                        echo date('Y/m/d H:i:s', $record->getFieldAsTimeStamp($field));
                    }
                    unset($return);
                    ?>
                </td>
                <td valign="top">
                    <?php var_dump($record->getFieldUnencoded($field)); ?>
                </td>
            </tr>
            <?php
            }
        }
        ?>
    </table>
    <?php
}
?>

このファイルではまず「fmapi_record_test」レイアウトにアクセス。ft_serialが1から2の範囲のレコードを取得し、レイアウトに配置されているフィールドを縦方向に展開。それぞれ3メソッドで取得した値をテーブルで表示している。実際にWebブラウザで確認してみよう。

FileMakerに保存されているデータを表示する際に、これら3つのメソッドは必ず使うことになる。それぞれの特性を理解し、使い方をマスターしておこう。