前回まで、FileMaker API for PHPでのデータベース接続手順から、レコード登録方法・バリデートの使い方について取りあげてきた。今回はレコードの検索処理について取りあげよう。FX.phpと比較すると機能が豊富な分、押さえるべきクラス/メソッドもおおい。これらを2回にわけて紹介する。

検索に使用するおもなクラスとは

FileMaker API for PHPでは検索のために、おもに4つのクラスが用意されている。

• FileMaker_Command_Find
• FileMaker_Command_FindALL
• FileMaker_Command_FindAny
• FileMaker_Command_FindRequest

それぞれの概要は次のとおり。

FileMaker_Command_Find

もっとも汎用的な検索クラス。FileMaker::newFindCommand()を使用してオブジェクトを生成する。任意のテーブルから検索条件をもとに、指定したソート順でレコードを表示する。FX.phpのFMFind()に相当。

FileMaker_Command_FindALL

FileMaker::newFindAllCommand()を使用してオブジェクトを生成する。任意のテーブルから指定したソート順でレコード全件を表示する。FX.phpのFMFindAll()に相当。

FileMaker_Command_FindAny

FileMaker::newFindAnyCommand()を使用してオブジェクトを生成する。任意のテーブルからランダムに1件、レコードを表示する。FX.phpのFMFindAny()に相当。

FileMaker_Command_FindRequest

複数の検索条件を指定するために使用するクラス。うまく使えば、FX.phpでは実装に難のあった複合検索も簡単に実装できるようになる。API for PHPを使うならばかならず使いこなせるようになっておきたい機能のひとつだ。

FileMaker_Command_FindRequestはさきに挙げた3つのクラスとはやや用途が異なり、使い方にクセがある。このクラスについては、追って次回紹介する。今回は「FileMaker_Command_Find」「FileMaker_Command_FindALL」「FileMaker_Command_FindAny」の3つについて紹介しよう。

検索実行までの流れ～関連メソッドを紹介

今回紹介する3つのクラスは、表示するレコードの範囲が違うだけで書き方や動作はほとんど一緒だ。ここではおもに、FileMaker_Command_Findクラスを使用してコードを記述する。ほか2つのクラスの場合は、FileMaker::newFindCommand()を適宜置きかえてほしい。

まずは検索条件を入力してレコードを検索する場合だ。使用するFileMakerレイアウトは「API for PHPでのDB接続手順、レコード表示まで(1)」で用いた「fmapi_list」だ。

fmapi_find_test.php

<?php

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

$data = new FileMaker('fmapi_test', 'http://localhost:80', 'admin', 'admin');

$findCommand = $data->newFindCommand('fmapi_list');
$findCommand->setRange(0, 10);

$findCommand->addFindCriterion('ft_updateTimeStamp', '9/1/2009...9/10/2009');

$findCommand->addSortRule('ft_updateTimeStamp', 1, FILEMAKER_SORT_DESCEND);

$result = $findCommand->execute();

if (FileMaker::isError($result))
{
    // エラー処理..
    echo 'FileMaker Error Code: ' . $result->getCode();
    echo '<p>'. $result->getMessage() . '</p>';
}
else
{
    // 正常処理..
    $records = $result->getRecords();
    ?>
    <table border="1">
        <tr>
            <th>ft_serial</th>
            <th>ft_registTimeStamp</th>
            <th>ft_updateTimeStamp</th>
        </tr>
    <?php
    foreach ($records as $record)
    {
        echo '<tr>';
        echo '<td>' . $record->getField('ft_serial') . '</td>';
        echo '<td>' . $record->getField('ft_registTimeStamp') . '</td>';
        echo '<td>' . $record->getField('ft_updateTimeStamp'). '</td>';
        echo '</tr>';
    }
    ?>
    </table>
    <?php
}

?>

それぞれ1つづつの検索条件、ソート条件を指定。レコード先頭から最大取得レコード数10件としている。これをWebブラウザで表示する。

ソースコード中で使用されているメソッドは次のとおり。

setRangeメソッド (Find.php 98-104行目より)

    /**
     * Request only part of the result set.
     *
     * @param integer $skip The number of records to skip past.
     * @param integer $max The maximum number of records to return.
     */
    function setRange($skip = 0, $max = null)

• integer $skip: 先頭からかぞえて除外するレコード数を指定。省略した場合は0が格納される
• integer $max: 一度に取得するレコード数上限を指定。省略した場合はnullが格納される

検索後に取得するレコードの範囲を指定する。FX.phpでは$skipがFMSkipRecords()、$maxがSetDBData()の第三引数に相当する。

addFindCriterionメソッド (Find.php 49-55行目より)

    /**
     * Add a find criterion.
     *
     * @param string $fieldname The field being tested.
     * @param string $testvalue The value to test against.
     */
    function addFindCriterion($fieldname, $testvalue)

• string $fieldname: フィールド名を指定
• string $testvalue: 検索内容を指定

フィールドと検索内容を対にして検索条件を指定する。FX.phpのAddDBParam()に相当する。

addSortRuleメソッド (Find.php 68-75行目より)

    /**
     * Add a sorting rule to the find command.
     *
     * @param string $fieldname The field to sort by.
     * @param integer $precedence 1-9, should we sort by this field first, last, etc.
     * @param mixed $order FILEMAKER_SORT_ASCEND, FILEMAKER_SORT_DESCEND, or a custom value list.
     */
    function addSortRule($fieldname, $precedence, $order = null)

• string $fieldname: ソートをおこないたいフィールド名を指定
• integer $precedence: ソートの優先順位を1から9の範囲で指定する
• mixed $order: ソート順を指定する。ソート順は「昇順」「降順」「値一覧に基づく順位」の中から指定する

ソート条件を指定する。FX.phpのAddSortParam()に相当する。AddSortParamとは引数の順番が異なるため注意されたい。

これら取りあげたメソッドはほか2つのクラスでも使用可能だ。このほかにも、有用なメソッドがいくつか用意されている。

FileMaker_Command_Findより継承

• clearFindCriteria: addFindCriterion()で指定した検索条件をすべて削除
• clearSortRules: addSortRule()で指定したソート条件をすべて削除
• getRange: 現在のレンジ設定を配列で取得
• getRelatedSetsFilters: 現在のRelatedSetsFilters情報を配列で取得
• setLogicalOperator: 論利検索の方式をFILEMAKER_FIND_ANDまたはFILEMAKER_FIND_ORで指定する。初期値はFILEMAKER_FIND_AND。FX.phpのSetLogicalOR()やAddDBParam('-lop', ...)に相当
• setRelatedSetsFilters: ポータル行に表示されるレコード取得についての設定

FileMaker_Commandより継承

• execute: 検索を実行
• setScript, setPreCommandScript, setPreSortScript, setRecordClass, setResultLayout, validate: API for PHPでのレコード登録方法、関連するメソッドの紹介(2)を参照
• setRecordId: レコードIDで検索をおこなう場合に使用。FX.phpのSetRecordID()に相当

ポータルのレコード取得設定がおこなえる「setRelatedSetsFilters」もAPI for PHPのみの機能だ。地味なところだが、かゆいところに手がとどく機能だと言えるだろう。次回は、API for PHPならではの機能「FileMaker_Command_FindRequest」を紹介しよう。