データコンバータクラスの利用方法

IM_Entry関数の第2引数で、'formatter'を利用して、特定のコンテキストのフィールドに対して、データベースの読み書き前後にフィルタを設定することができます。このときに使うクラスをデータコンバータクラスと呼びます。自分で作成もできますが、以下のものが最初から組み込まれています。自分で作成する場合はDataConverter_template.phpを参照してください

データベースアクセス処理の拡張クラスを定義する

データベース側の処理に割り込むには「データベースクラスを自作する」で説明する手法（「データアクセスクラスのサブクラスを利用する方法」と定義します）とここで説明する手法（「拡張処理クラスを定義する方法」とします）の2通りがあります。「データアクセスクラスのサブクラスを利用する方法」だと、すべてのコンテキストに対する処理を記述しなければなりません。言い換えれば、複数あるコンテキストの１つだけに対して処理を加えたい場合、そのコンテキストのときだけプログラムが実行されるようにする必要があります。コンテキストが増減したときのメンテナンスタスクが増えます。「拡張処理クラスを定義する方法」だと、特定のコンテキストにだけ利用されるクラスを指定するので、「コンテキストごとに分岐させる」処理は不要です。必要な処理だけを記述する「拡張処理クラスを定義する方法」を使う方がプログラムの作成は容易でしょう。

IM_Entry関数の第一引数、つまりコンテキストの中に「extending-class」でクラス名を指定します。ここで指定したクラス名は任意のものでかまいませんが、そのクラスをPHPが認識できる場所に記述しておく必要があります。クラスは以下のようなインタフェースをインプリメントする必要があります。つまり、CRUDに対応する4種類のデータアクセス処理の前後にメソッドを含めることができるのです。

interface Extending_Interface_BeforeRead {
    public function doBeforeReadFromDB();
}
interface Extending_Interface_AfterRead {
    public function doAfterReadFromDB($result);
}
interface Extending_Interface_AfterRead_WithNavigation {
    public function doAfterReadFromDB( $result);
    public function countQueryResult();
    public function getTotalCount();
}
interface Extending_Interface_BeforeUpdate {
    public function doBeforeUpdateDB();
}
interface Extending_Interface_AfterUpdate {
    public function doAfterUpdateToDB($result);
}
interface Extending_Interface_BeforeCreate {
    public function doBeforeCreateToDB();
}
interface Extending_Interface_AfterCreate{
    public function doAfterCreateToDB($result);
}
interface Extending_Interface_BeforeDelete {
    public function doBeforeDeleteFromDB();
}
interface Extending_Interface_AfterDelete {
    public function doAfterDeleteFromDB($result);
}
interface Extending_Interface_BeforeCopy {
    public function doBeforeCopyInDB();
}
interface Extending_Interface_AfterCopy{
    public function doAfterCopyInDB($result);
}

以下は、データベースからレコードを取得した後に呼び出されるクラスの定義例です。MyProgramというクラス名は任意ですが、2つのメソッドはインタフェースに決められたものを定義します。doAfterGetFromDBはデータベースからデータを取得した後に呼び出されます。引数$resultにはデータベースからの取得した結果が、連想配列の配列の形式で入っています。1レコードがフィールド名をキーとした連想配列になっており、レコードの数だけその配列があります。たとえば集計処理などを行い、同様に連想配列の配列にして結果を返します。このとき、ナビゲーションを使ってページ送りの処理をしているのなら、「レコードの個数」をcountQueryResultメソッドで返す必要があります。ナビゲーションがない場合にはこのメソッドの実装は不要です。また、ナビゲーションを使う場合でも、レコード総数がdoAfterGetFromDBの処理の後でも変わらないのであれば、countQueryResultメソッドは不要です。PHPではoptionのメソッドの定義をインタフェースできないので、定義上はコメントでこのメソッドを記載しています。

class MyProgram implements Extending_Interface_AfterRead {
    function doAfterReadFromDB($result) {
        foreach( $result as $record ) {
            foreach( $record as $field => $value ) {
                :
            }
        }
        return $result;
    }
}

countQueryResultメソッドを記述する場合の例を以下に示します。countQueryResultはdoAfterGetFromDBよりも後に呼び出されます。countQueryResultによって返されるのは、実際のレコード数ではなく、検索条件に合ったレコード数です。つまり、1万個のレコードのうち40個を表示している場合には、1万という数値を返す必要があります。doAfterGetFromDBで集計処理などをすると、1万レコードを取得して、それが20個などになると思います。その場合は20個を返さないといけません。この場合、自分でメンバ変数（dataCount）を定義して、そこに値を残しておくのが分かりやすい方法でしょう。

class MyProgram implements Extending_Interface_AfterRead_WithNavigation {
    var $dataCount;
    
    function doAfterReadFromDB($result) {
            :
        $thisthis->dataCount = count( $result );
        $return result;
    }
    
    function countQueryResult() {
        $return $this->dataCount;
    }
}

それぞれのメソッドの$dataSourceNameはコンテキスト名の文字列が入っています。2つのコンテキストでクラスを共有するような場合には分岐のための手がかりになります。doAfterNewToDBの2つ目の引数$resultは、新たに作成したレコードのキーフィールドの値が設定されています。この値はdoAfterNewToDBメソッドでの返り値にしなければなりません。doAfterDeleteFromDBとdoAfterSetToDBメソッドの2つ目の引数はデータベース処理が失敗したかどうかをbooleanで示され、trueなら処理が成功です。これらのメソッドでもやはり引数で得られた値を返さないといけません。

開発者が作成するクラスで「DB_UseSharedObjects」クラスの子クラスにした場合は、他のオブジェクトへの参照が得られます。メソッドが呼び出された段階で、メンバ変数はオブジェクトを参照した状態になります。

doAfter*メソッドの中では、原則として引数から処理対象のレコードが得られます。以下、処理結果のレコードを参照したり更新するメソッドを用意していますが、updateRecordメソッドは通常は不要と思われます。メール処理のためにフィールドを追加するようなときには、setUpdatedRecordメソッドを使います。

DB_Class->updatedRecord()

データベース処理後、処理した結果のレコードの配列が得られる。読み出しなら、読み出したレコード群、更新なら更新したレコード、新規レコードなら作成したレコードが得られる。

DB_Class->setUpdatedRecord($f, $v, $n)

処理した結果のレコードの特定のフィールドを修正する。$fがフィールド、$vがその値、$nは0から始まる番号でレコードを指定するが、$nを省略すると最初のレコードを参照する。返り値はなし。

データベースクラスを自作する

データベースクラスを独自に作成する場合には、以下のようなPHPのクラスが基本となります。もちろん、データベースクラスを1から作れるのですが、たぶん、そういうニーズはまずないと思います。データベースをPDOで使うならINTER-MediatorのDB_PDO.php、FileMaer Serverを使うならDB_FileMaker_FX.phpを拡張したクラスを定義します。基底クラスの方のファイルも読み込みが必要です。以下の例は、INTER-Mediatorフォルダと同じフォルダに、このデータベースクラスのファイルがあるというわけです。自分が作るクラスでも、最初にDBをつけないといけません。IM_Entry関数の引数などでの設定は、この場合DB_をのぞいた「MyOriginalDB」を指定します。

require_once( "INTER-Mediator/DB_PDO.php" );
class DB_MyOriginalDB extends DB_PDO.php {
    public function readFromDB() {
        /* ここにプログラムを追加できる */
        $result = super::readFromDB();
        /* ここにプログラムを追加できる */
        $this->mainTableCount = count( $result ); //レコード数
        return $result;
    }

    public function countQueryResult()  {
        return super::countQueryResult();
    }

    public function getTotalCount()  {
        return super::getTotalCount();
    }

    public function updateDB() {
        /* ここにプログラムを追加できる */
        $result = super::updateDB();
        /* ここにプログラムを追加できる */
        return $result;
    }
    
    public function createInDB($bypassAuth) {
        /* ここにプログラムを追加できる */
        $lastKeyValue = super::createInDB($bypassAuth);
        /* ここにプログラムを追加できる */
        return $lastKeyValue;
    }
    
    public function deleteFromDB() {
        /* ここにプログラムを追加できる */
         $result = super::deleteFromDB();
        /* ここにプログラムを追加できる */
        return $result;
    }
    public function copyInDB()  {
         $result = super::copyInDB();
        return $result;
    }
}

自分で作るクラスでは、要はCRUDに対応した4つのメソッドをオーバーライドすることによって、独自の仕組みを組み込むことができます。また、4つのうち、特にプログラムの追加がない場合には、定義する必要はありません。いずれの関数も、コンテキスト名を引数に取ります。そして、現在処理しているコンテキスト名が設定されてこれらのメソッドを呼び出します。

readFromDBメソッドは、データベースからデータを取り出します。取り出し結果は連想配列の配列です。連想配列のキーがフィールド名になっています。そこから、特定のフィールドの値を元に集計をしたり、あるいは必要な値だけに取り除くなどの処理を、親クラスのreadFromDBメソッドを呼び出す後に入れればいいでしょう。リクエスト時と同じフィールド名を返す必要はなく（つまりINTER-Mediatorはそのチェックをしていない）、自由に連想配列の配列を作ります。そして、ページファイルの方で適切なフィールド名を指定すれば、集計結果が表示されます。なお、ページファイルで、一定レコード数ごとのページングをしているときには、mainTableCountメンバ変数にレコード数、つまり返す配列の要素数も指定します。何か問題が発生したのなら、array()を返します。以下のプログラムは売り上げのテーブルから集計を行う例です。

$result = super::readFromDB();
$summary = array();
foreach( $returnValue as $record ) {
    $summary[ $record[ 'itemNo' ]] += $record[ 'qty' ] * $record[ 'unitPrice' ];
    }
return array( $summary );

updateDBとdeleteFromDBメソッドは、いずれも値の更新や削除のときに呼び出されるメソッドです。返り値は論理値で、処理が成功すればtrueで失敗ならfalseです。createInDBは新規レコードの作成です。メソッドの返り値は、新たに作ったレコードのキーフィールドの値である必要があります。問題があれば返り値をfalseにします。

サーバーサイドのプログラムで利用できるAPI

以下、DB_ProxyはDB_Proxyクラスのオブジェクトへの参照を意味します。

DB_Proxy->initialize($datasource, $options, $dbspec, $debug, $target = null)

DB_Proxyクラスを初期化する。返り値はなし。生成したDB_Proxyクラスのオブジェクトに対して適用することで、さまざまな設定が反映されたオブジェクト群を形成する。

DB_Proxy->processingRequest($access, $bypassAuth)

初期化したDB_Proxyクラスのオブジェクトに対して処理を行う。返り値はない。引数$bypassAuthは、認証やアクセス権設定を無視するが、この指定は慎重に行う必要がある。既定値はfalse。引数$accessに、行うデータベース処理を示す文字列を指定する。nullを指定したときや省略したときにはPOST時のパラメーターの"access"キーの値を使用する。$accessに指定できる値と動作は次の通り：'create'（レコードの作成）、'read'（データベースへのクエリー）、'update'（レコードの更新）、'delete'（レコードの削除）、'copy'（レコードの複製）、'challenge'（チャレンジの生成＝原則として何もしない）、'changepassword'（パスワード変更）、'unregister'（Pusherによるクライアント同期の登録解除）、'describe'（スキーマ情報を得る）。他に'select' 'new'が過去の互換性のために利用可能となっている。それ以外の文字列の場合は、特に何もしない。

DB_Proxy->ignoringPost()

initializeメソッドではPOSTされたデータを取り込むが、その結果、処理拡張クラス内で新たにDB_Proxyクラスを生成してコンテキストを別途用意したとき、POSTデータの取り込みをしたくない場合も発生する。そのときにこのメソッドをinitializeメソッドよりも前に呼び出す。

DB_Proxy->getDatabaseResult()

データベースからの検索結果などで、1レコードが連想配列として表現され、その連想配列がレコード数分ある配列が返される。利用可能なprocessingRequestメソッドの最初の引数は、create（作成されたレコード）、read（検索結果）、update（更新後のレコード）、copy（複製後のレコード）、describe（スキーマ情報）。なお、レコード作成時にこの値が空の場合がまれにあるようです。PDOのlastInsertIdメソッドを使って新たに作成したレコードのキーフィールドの値を取得していますが、何らかの原因でそれが取得されず0が返され、作成したレコードの取得ができないのが原因です。解決策として、PHPのインストールをしなおしたら直ったなどが記載されていますが、決定的な方法はないようです。

DB_Proxy->getDatabaseResultCount()

processingRequestメソッドの最初の引数がreadの場合、検索結果に含まれるレコード数を返す。コンテキストのrecordsキーが上限値となるが、実際に検索されたレコード数はそれより少ない場合もある。

DB_Proxy->getDatabaseTotalCount()

processingRequestメソッドの最初の引数がreadの場合、検索条件に合致したレコード数を返す。

DB_Proxy->getDatabaseNewRecordKey()

processingRequestメソッドの最初の引数がcreateあるいはcopyの場合、新たに作成されたレコードの主キーの値を返す。

DB_Proxy->finishCommunication($notFinish)

出力するためのさまざまな準備を行う。

DB_Proxy->exportOutputDataAsJSON()

JSON形式のテキストで各種データを出力する。

DB_Logger->setDebugMessage($str, $level)

引数$strに指定した文字列を、引数$levelに指定したレベルでのデバッグメッセージとして記録する。レベルは1ないしは2のみをサポートし、引数$levelを省略すると1になる。

DB_Logger->setErrorMessage($str)

引数$strに指定した文字列を、エラーメッセージとして記録する。

DB_Logger->getDebugMessages()

記録されたデバッグメッセージを要素として含む配列を返す。

DB_Logger->getErrorMessages()

記録されたエラーメッセージを要素として含む配列を返す。

DB_Settings->setDataSourceName($dataSourceName)

引数に指定した文字列をnameキーの値として持つコンテキストを選択する。

DB_Settings->getDataSourceName()

現在、選択されているコンテキストのnameキーに対する値。

DB_Settings->getDataSourceTargetArray()

現在、選択されているコンテキストの定義内容を連想配列で返す。

DB_Settings->getDataSourceDefinition($dataSourceName)

引数に指定した文字列をnameキーの値として持つコンテキスト定義の連想配列を返す。

DB_Settings->getEntityForRetrieve()

クエリー処理に利用するエンティティ名を返す。つまり、viewキーの値が指定されていればその値、指定されていない場合にはnameキーの値が返される。

DB_Settings->getEntityForUpdate()

更新処理に利用するエンティティ名を返す。つまり、tableキーの値が指定されていればその値、指定されていない場合にはnameキーの値が返される。

DB_Settings->setStart($st)

検索結果の最初のいくつ目から結果として取り出すかを、引数の数値で指定する。クライアントのINTERMediator.startFromの値が自動的に設定される。

DB_Settings->getStart()

検索結果の最初のいくつ目から結果として取り出すかが得られる。

DB_Settings->setRecordCount($sk)

検索結果の中から、最大でいくつのレコードを取り出すかを引数の数値で指定する。コンテキストのrecordsキーの値や、クライアントINTERMediator.pageSizeの値など、すでに決まっている値が指定される。

DB_Settings->getRecordCount()

検索結果の中から、最大でいくつのレコードを取り出すかが得られる。

DB_Settings->getAggregationSelect()
DB_Settings->setAggregationSelect($value)

選択されているコンテキストに指定したaggregation-selectキーの設定と取得

DB_Settings->getAggregationFrom()
DB_Settings->setAggregationFrom($value)

選択されているコンテキストに指定したaggregation-fromキーの設定と取得

DB_Settings->getAggregationGroupBy()
DB_Settings->setAggregationGroupBy($value)

選択されているコンテキストに指定したaggregation-group-byキーの設定と取得

DB_Settings->setDataSource($src)

引数には定義ファイルのIM_Entry関数の第1引数の値を指定して、コンテキスト定義の配列をオブジェクトに記録する。

DB_Settings->getDataSource()

定義ファイルのIM_Entry関数の第1引数の値が返される。

DB_Settings->setOptions($src)

引数には定義ファイルのIM_Entry関数の第2引数の値を指定して、オプション指定の配列をオブジェクトに記録する。

DB_Settings->getOptions()

定義ファイルのIM_Entry関数の第2引数の値が返される。

DB_Settings->setDbSpec($src)

引数には定義ファイルのIM_Entry関数の第3引数の値を指定して、データベース設定の配列をオブジェクトに記録する。

DB_Settings->getDbSpec()

定義ファイルのIM_Entry関数の第3引数の値が返される。

DB_Settings->setFieldsRequired($fieldsRequired)

フィールドの配列として、引数の配列を設定する。このメソッドは、配列そのものを設定するが、addValueWithField、addTargetFieldメソッドにより、フィールド一覧を管理する配列へ要素が追加される。

DB_Settings->getFieldsRequired()

フィールドの配列を返す。

DB_Settings->addTargetField($field)

フィールドの配列の要素として、引数に指定した文字列を追加する。

DB_Settings->getFieldOfIndex($ix)

フィールドの配列から、引数に指定した番号の要素を返す。

DB_Settings->setValue($values)

値の配列として、引数の配列を設定する。

DB_Settings->getValue()

値の配列を返す。

DB_Settings->addValue($value)

値の配列の要素として、引数に指定した文字列を追加する。

DB_Settings->addValueWithField($field, $value)

フィールドの配列および値の配列の要素として、引数に指定した文字列をそれぞれ追加する。

DB_Settings->getValuesWithFields()

フィールドの配列にある値をキー、そのキーに対する値を要素にした連想配列を返す。

DB_Settings->getValueOfField($targetField)

引数に指定したフィールド名をフィールドの配列の何番目なのかを判別し、値の配列の同じ番号の要素を返す。つまり、フィールド名に対応した値を返す。

DB_Settings->setForeignFieldAndValue($foreignFieldAndValue)

引数を外部キーの値を保持する配列に指定する。引数は、field、valueをキーとした連想配列の配列である必要がある。

DB_Settings->getForeignFieldAndValue()

外部キーの値を保持する配列を返す。返される値は、field、valueをキーとした連想配列の配列。

DB_Settings->addForeignValue($field, $value)

引数に指定したフィールド名と値を、外部キーの値を保持する配列に追加する。

DB_Settings->getForeignKeysValue($targetField)

外部キーの値を保持する配列から、引数に指定したフィールドに対する値を返す。ない場合はnullが返る。

DB_Settings->addExtraCriteria($field, $operator, $value)

追加的な検索条件を保持する配列に、引数の3つの要素を持つ連想配列として追加する。

DB_Settings->getExtraCriteria()

追加的な検索条件を保持する配列を返す。

DB_Settings->unsetExtraCriteria($index)

追加的な検索条件を保持する配列の中にある引数に指定したインデックスの要素を削除する。

DB_Settings->getCriteriaValue($targetField)

追加的な検索条件を保持する配列から、引数に指定した文字列をfieldキーの値として持つ最初の要素を特定し、その要素のvalueキーの値を返す。

DB_Settings->getCriteriaOperator($targetField)

追加的な検索条件を保持する配列から、引数に指定した文字列をfieldキーの値として持つ最初の要素を特定し、その要素のoperatorキーの値を返す。

DB_Settings->setGlobalInContext($contextName, $operation, $field, $value)

引数に指定したコンテキストに、残りの引数で指定した設定内容を持つglobalキーの連想配列を追加する。もちろん、FileMaker Serverのみで意味のある機能である。

DB_Settings->setPrimaryKeyOnly($primaryKeyOnly)
DB_Settings->getPrimaryKeyOnly()

検索条件の中から、主キー（コンテキストのkeyキー）で指定されたものだけを利用する設定とその状態の取得。なお、主キーのみを利用する検索は、データベースの更新前に楽観的ロックの仕組みを利用して、現在の値を取り出す場合に利用している。

DB_Settings->addExtraSortKey($field, $direction)

追加のソート条件を記録した配列に、引数にしていたフィールドと基準（昇順ないしは降順）を追加する。

DB_Settings->getExtraSortKey()

追加のソート条件を記録した配列を得る。

DB_Settings->addAssociated($name, $field, $value)

レコードのコピーにおいて、関連するコンテキストに対する設定を追加する。

DB_Settings->getAssociated()

レコードのコピーにおいて使用される関連するコンテキストに対する配列を得る。

DB_Settings->setDbSpecServer($str)
DB_Settings->getDbSpecServer()
DB_Settings->setDbSpecPort($str)
DB_Settings->getDbSpecPort()
DB_Settings->setDbSpecUser($str)
DB_Settings->getDbSpecUser()
DB_Settings->setDbSpecPassword($str)
DB_Settings->getDbSpecPassword()
DB_Settings->setDbSpecDataType($str)
DB_Settings->getDbSpecDataType()
DB_Settings->setDbSpecDatabase($str)
DB_Settings->getDbSpecDatabase()
DB_Settings->setDbSpecProtocol($str)
DB_Settings->getDbSpecProtocol()
DB_Settings->setDbSpecDSN($str)
DB_Settings->getDbSpecDSN()
DB_Settings->setDbSpecOption($str)
DB_Settings->getDbSpecOption()

データベース処理に関する設定を行ったり取り出したりするメソッド。

DB_Settings->setCurrentUser($str)
DB_Settings->getCurrentUser()

クライアントから申告されたユーザー名の設定及び取得と行うメソッド。

DB_Settings->setUserAndPasswordForAccess($user, $pass)
DB_Settings->getAccessUser()
DB_Settings->getAccessPassword()

クライアントから申告されたユーザー名とパスワードの設定及び取得と行うメソッド。ネイティブ認証時にチャレンジに対応するレスポンスによって返されたユーザー名とパスワードが設定され、それ以外の時には設定されない。

DB_Settings->setAuthentication($authentication)
DB_Settings->getAuthentication()

IM_Entry関数の第2引数（オプション設定）の、authenticationキーに対する値を記録あるいは取り出す。

DB_Settings->getAuthenticationItem($key)

IM_Entry関数の第2引数（オプション設定）のauthenticationキーに対する値に対し、さらに引数の文字列のキーの値を取り出す。もし、引数に与えたキーに対する値が定義されていない場合で、引数がテーブル名の場合には、規定のテーブル名を返す。あるいは認証継続時間の場合には既定値として8時間が返される。

DB_Settings->getUserTable()

認証に使用するテーブル名を返す。定義ファイル等で未設定の場合には既定値のauthuserが返される。

DB_Settings->getGroupTable()

グループ管理に使用するテーブル名を返す。定義ファイル等で未設定の場合には既定値のauthgroupが返される。

DB_Settings->getCorrTable()

グループ所属記録に使用するテーブル名を返す。定義ファイル等で未設定の場合には既定値のauthcorrが返される。

DB_Settings->getHashTable()

認証でのチャレンジ等を記録するためのテーブル名を返す。定義ファイル等で未設定の場合には既定値のissuedhashが返される。

DB_Settings->getExpiringSeconds()

認証結果を保持する時間を返す。定義ファイル等で未設定の場合には既定値の8時間が返される。

DB_Settings->setRequireAuthentication($requireAuthentication)
DB_Settings->getRequireAuthentication()

ゲッターは、定義ファイルの内容から、認証が必要かどうかを求めた結果を返す。セッターはprocessingRequestメソッド内で判定結果を記録するために利用される。

DB_Settings->setRequireAuthorization($requireAuthorization)
DB_Settings->getRequireAuthorization()

ゲッターは、定義ファイルの内容から、アクセス権の判定が必要かどうかを求めた結果を返す。セッターはprocessingRequestメソッド内で判定結果を記録するために利用される。

DB_Settings->setDBNative($isDBNative)
DB_Settings->isDBNative()

ゲッターは、定義ファイルの内容から、ネイティブ認証を行うかどうかを求めた結果を返す。セッターはprocessingRequestメソッド内で判定結果を記録するために利用される。

DB_Settings->setEmailAsAccount($emailAsAccount)
DB_Settings->getEmailAsAccount()

ゲッターは、定義ファイルの内容から、電子メールを認証時のユーザー名として使用できるかどうかを返す。セッターはprocessingRequestメソッド内で設定を記録するために利用される。

DB_Settings->getLDAPSettings()

params.phpファイルで定義されたLDAPの設定値を持つ配列を返す。要素は順番に、サーバー名、ポート番号、検索ベース、コンテナ名、ユーザー名のキー名。

DB_Settings->setLDAPExpiringSeconds($sec)
DB_Settings->getLDAPExpiringSeconds()

ゲッターは、params.phpファイルの内容から得られたLDAP認証の継続時間を返す。セッターは設定を記録するために利用される。

DB_Settings->setSeparator($sep)
DB_Settings->getSeparator()

ターゲット指定の区切り文字（通常は「@」）を記録したり取得するメソッド。設定しない場合には、＠が返される。

DB_Settings->setSmtpConfiguration($config)
DB_Settings->getSmtpConfiguration()

IM_Entry関数の第2引数（オプション設定）の、smtpキーに対する値を記録あるいは取り出す。