FileMaker API for PHP を初めて触る人のために

# 初めての FileMaker API for PHP
FileMaker API を用いようとする動機は様々だと思います。Webアプリケーションを本格的に作成したり、そこまでいかなくても簡単な Webベースのシステムを作ったりといったところでしょうか。

いずれにしてもデータベースの操作における CRUD のうち、メインになるのは R（Read）だと思います。ここでは全ての基礎となる Read の方法に絞って説明をします。


# Read のための下準備（PHP のコード）
まずは[昨日の記事](http://qiita.com/corselia/items/b30927d9fb2d27264b3e)のとおりに FileMaker API for PHP のライブラリをインストール（コピー）します。そのコピーしたディレクトリのルートにある`FileMaker.php`を`require`しましょう。

```php:fmapi_first_trial.php
<?php
require_once("./lib/FileMaker.php"); # lib/ に展開した場合
```

次に、FileMaker Server のアドレスと、ログイン情報を以下のように定義します。

```php:fmapi_first_trial.php
$DB_HOST = "FileMaker Server のアドレス";
$DB_USER = "ユーザ名";
$DB_PASS = "ユーザ名に対するパスワード";
```

そして用いるデータベースの名前（レイアウトの名前ではないです）をさらに定義しましょう。

```php:fmapi_first_trial.php
$DB_NAME = "データベースの名前";
```

ここまでで下準備は完了です。

# `FileMaker`クラスのインスタンスを作成し、レイアウトを確定する
上記に設定した定数を用いて、`FileMaker`クラスのインスタンスを作成しましょう。定数（引数）の順番に注意です。

```php:fmapi_first_trial.php
$fm_instance = new FileMaker($DB_NAME, $DB_HOST, $DB_USER, $DB_PASS);
```

このインスタンスに対して、対象とする「レイアウト」を指定し、その返り値を`$find_proc`に入れましょう。

```php:fmapi_first_trial.php
$find_proc = $fm_instance->newFindCommand("レイアウト名");
```

# 検索条件を書いていこう
いよいよレコードの検索部分を書いていきます。上記で生成した`$find_proc`に対し、`addFindCriterion`というメソッドを実行します。

第一引数が「対象フィールド」、第二引数が「検索条件」です。ここで「検索条件」は FileMaker における検索条件の書式と同じものを用います。以下がサンプルコードです。

```php:fmapi_first_trial.php
$find_proc->addFindCriterion("対象フィールド", "==apple");
```

# 検索を実行する
これで検索条件がセットされました。まだ検索自体は行われていませんので、`execute()`メソッドを用いて検索を行います。

```php:fmapi_first_trial.php
$find_result = $find_proc->execute();
```

無事、検索が実行され、その結果が`$find_result`に入りました。

# エラー処理
検索結果を早く見たいところですが、一般的に何らかの「実行」後にはエラー処理（チェック）を忘れてはいけません。FileMaker API for PHP でのエラー処理は定型化していますので、以下のように書きましょう。

```php:fmapi_first_trial.php
if (FileMaker::isError($find_result)) {
    # エラーの場合
    echo "FileMaker Error Code: " . $find_result->getCode(). "\n";
    echo "FileMaker Error Message: " . $find_result->getMessage() . "\n";
} else {
    # 正常に実行された場合
    $result_records = $find_result->getRecords();
}
```

これでエラーの場合はエラーコードとエラーメッセージが表示されます。正常に実行された場合は`$find_result`の`getRecords()`メソッドを実行しています。`$find_result`のままだとデータが広大で扱いにくいため、`$find_result`の中からレコードに関するデータだけを抽出するために`getRecords()`メソッドを使って絞り込み、`$result_records`に格納しています。

# 得られたレコードを扱う
上記で得られた`$result_records`は配列です。検索の結果、複数のレコードが引っかかるからです[^1]。したがって、`$result_records`に対して何らかの操作をする場合は`foreach`をするのが定石でしょう。

なお、`$result_records[index]`に対して使える主なメソッドとしては以下のようなものがあります。

- `$result_records[index]->getField(フィールド名)`
    - 対象となるレコードの「フィールド名」に指定されたフィールドの値を取得する
- `$result_record[index]->getRecordId()`
    - 対象となるレコードの「レコードID」を取得する

他にもいろいろなメソッドがありますので調べてみてください。

# 具体例
ここで具体的な例を見てみましょう。

## 利用するデータベース
まずは具体例に利用するデータベースが必要です。以下のように`Staff`というデータベースの`StaffData`レイアウト内の`staff_data`というテーブルを用います[^2]。

![fm_Qiita_02.png](https://qiita-image-store.s3.amazonaws.com/0/72181/fdefe835-1538-1f7e-41ff-08d165504f1f.png)

![fm_Qiita_03.png](https://qiita-image-store.s3.amazonaws.com/0/72181/2fb3cf37-c1d7-92e7-5344-31b579ed7df0.png)

以下の5つのカラムが定義されているのが分かります。

- `id`
- `name`
- `gender`
- `work`
- `point`

このテーブルに対して 7 つのデータが投入されています。

## コードを書く
これまでに書いた内容をまとめて、以下のような検索条件で検索をしてみましょう。

> `gender`が`female`であるレコード

以下がコードになります。

```php:find_record_for_gender_female_fmapi.php
<?php
require_once("./lib/FileMaker.php"); # lib/ に展開した場合

$DB_HOST = "FileMaker Server のアドレス";
$DB_USER = "ユーザ名";
$DB_PASS = "ユーザ名に対するパスワード";
$DB_NAME = "Staff";
$fm_instance = new FileMaker($DB_NAME, $DB_HOST, $DB_USER, $DB_PASS);

$find_proc = $fm_instance->newFindCommand("StaffData");
$find_proc->addFindCriterion("gender", "==female");
$find_result = $find_proc->execute();

if (FileMaker::isError($find_result)) {
    # エラーの場合
    echo "FileMaker Error Code: " . $find_result->getCode(). "\n";
    echo "FileMaker Error Message: " . $find_result->getMessage() . "\n";
} else {
    # 正常に実行された場合
    $result_records = $find_result->getRecords();
}

# 検索結果の表示
echo count($result_records) . " 件ヒットしました！" . "\n\n";
echo "ヒットした方のお名前は以下のとおりです" . "\n";
foreach ($result_records as $result_record) {
    echo $result_record->getField("name") . "\n";
}
```

```bash:結果
3 件ヒットしました！

ヒットした方のお名前は以下のとおりです
higashino
ishikawa
kawano
```

# まとめ
極めて簡単でしたが FileMaker API for PHP を使う方法を記してみました。[マイナビのサイト](http://news.mynavi.jp/column/fmxphp/)などを見るとより多くのメソッドや応用例が載っていますので、上記を参考にして自由にレコードを操作してみてください。

[^1]: もちろんレコードが一つだけ引っかかる場合もありますが
[^2]: いろいろ問題がある設計ですが、あくまでサンプルとして分かりやすさを重視しています