Zend Framework/自作コンポーネント/Piece_Flow

最終更新: 2008-07-30 (水) 00:41:53

Zend Framework で継続サーバ Piece_Flow を使う †

▲

目次 †

▲

概要 †

Piece_Flow は Piece Framework を構成するプロダクトの１つで、 Web フローエンジン及び継続サーバの機能を提供するライブラリです。この Piece_Flow を Zend Framework に組み込み、 Piece Framework と同様のステートフルなプログラミングができるようにします。

標準の Dispatcher を継承しており、通常は今までと同じ動作をします
Module, Controller, Action が特定の組み合わせの場合に、フローを用いた制御に切り替わります
フロー実行中は、YAML や XML 形式のフロー定義ファイルによって画面遷移を制御することができます
(意図しない画面遷移を禁止できるため、CSRF 対策などの処理を書く必要がなくなります)
フロー実行中は、変数のセッションへの保存、復帰が自動的に行われます
(セッションや hidden フィールドを使った値の受け渡しをする必要がなくなります)

雰囲気を伝えるためのサンプルとして、「へぇボタン」プログラムのフロー定義ファイルとアクションコントローラを示しておきます。

firstState: Counter

viewState:
  - name: Counter
    view: Counter
    activity:
      method: setView
    transition:
      - event: increase
        nextState: Counter
        action:
          method: increase

<?php

class CounterAction extends Revulo_Controller_Action
{
    private $_counter = 1;

    public function increase()
    {
        $this->_counter++;
    }

    public function setView()
    {
        $this->view->counter = $this->_counter;
    }
}

▲

インストール †

アーカイブをダウンロードし、 include_path の通ったディレクトリで展開して下さい。
（sample/library のような各アプリケーションの library ディレクトリや、 ZendFramework-1.5.3/library ディレクトリなどで。）

$ cd ZendFramework-1.5.3/library
$ tar xvfz Revulo_Controller_Dispatcher_Flow-0.9.tar.gz

また、その他にいくつかのライブラリをインストールする必要があります。

Piece_Flow (Version 1.16.0 以降)
Stagehand_FSM (Version 1.10.0 以降)
PEAR::Cache_Lite
Spyc

これらのうち Spyc 以外のライブラリは、以下のように pear コマンドを使うことでまとめてインストールできます。

# pear channel-discover pear.piece-framework.com
# pear install piece/Piece_Flow

後は Spyc のページからアーカイブをダウンロードしてインストールして下さい。

▲

使い方 †

基本的には、Piece Framework でのプログラミングとほぼ同じです。ですので、まずは付属のサンプルや Piece Framework のサンプルを触ってみて、それをベースに書き直していくのが良いと思いますが、必要な作業を以下に列挙しておきます。

Revulo_Controller_Dispatcher_Flow クラスを Dispatcher として登録
フロー定義ファイルを作成
Module, Controller, Action 名とフローとをマッピング
Revulo_Controller_Action クラスを継承したアクションコントローラに、実際の処理を記述
ビュースクリプトの中にフローの情報を埋め込み

Dispatcher の登録は、以下のように Zend_Controller_Front::setDispatcher() メソッドを用いて行います。

$config     = new Zend_Config_Ini('../application/config/flow.ini', 'flow');
$dispatcher = new Revulo_Controller_Dispatcher_Flow($config);

$front = Zend_Controller_Front::getInstance();
$front->setDispatcher($dispatcher);

ビュースクリプトには次のような情報を埋め込み、ボタンやリンクがクリックされた際にフローのチケットやイベント名が渡されるようにしてやります。

<form action="">
  <input type="hidden" name="{$flowExecutionTicketKey}" value="{$flowExecutionTicket}" />
  <input type="submit" name="{$eventNameKey}_increase" value="Increase" />
</form>

また、約束事がいくつかあるので書いておきます。

セッションをスタートする前に以下の作業を行っておいて下さい
- Revulo/Controller/Dispatcher/Flow.php を読み込む
- Zend_Controller_Front::setControllerDirectory() メソッドでアクションコントローラのディレクトリを指定する

ファイル名やクラス名は次のようにして下さい
- アクションコントローラのファイル名： (フロー定義ファイル名)Action.php
- アクションコントローラのクラス名： (フロー定義ファイル名)Action
- ビュースクリプトを置くディレクトリ： views/scripts/(小文字化したフロー名)

▲

設定 †

▲

Dispatcher のオプション †

設定可能なオプションは以下の通りです。連想配列の形でコンストラクタにパラメータを渡して下さい。

flowMappings: 各フローに対応する Module, Controller, Action 名などの設定 (詳しくは後述)

configDirectory: フロー定義ファイルを置くディレクトリ
(デフォルト値: config/flows)

configExtension: フロー定義ファイルの拡張子
(デフォルト値: .flow)

cacheDirectory: フロー定義ファイルのキャッシュに使われるディレクトリ
(デフォルト値: cache/flows)

bindActionsWithFlowExecution: アクション継続の機能を有効にする
(デフォルト値: true)

enableSingleFlowMode: シングルフローモードにする *1
(デフォルト値: false)

enableGC: 次の画面に移るまでに一定時間以上かかった場合、例外を投げてフローを停止する
(デフォルト値: false)

gcExpirationTime: フロー実行が期限切れとみなされるまでの秒数
(デフォルト値: 1440)

configDirectory, cacheDirectory には、デフォルトモジュールのディレクトリからの相対パスを指定して下さい。

フロー実行が期限切れになった場合、 PIECE_FLOW_ERROR_FLOW_EXECUTION_EXPIRED というエラーコードの Revulo_Controller_Dispatcher_Exception が throw されます。この例外は、例えば以下のようなコードで捕捉できます。

try {
    ......
} catch (Revulo_Controller_Dispatcher_Exception $e) {
    if ($e->getCode() == PIECE_FLOW_ERROR_FLOW_EXECUTION_EXPIRED) {
        ......
    }
}

▲

フローと URL とのマッピング †

モジュール、コントローラ、アクション名とフローとのマッピングを、 flowMappings オプションを用いて行って下さい。例えば、http://…/counter/index という URL にアクセスした時に Counter というフローが開始されるようにするためには、以下のように設定します。 (Zend_Config_Ini 形式で記述する場合)

flowMappings.Counter.controller = counter
flowMappings.Counter.action     = index

設定可能なプロパティは以下の通りです。

module: そのフローに対応するモジュール
(デフォルト値: default)

controller: そのフローに対応するコントローラ
(デフォルト値: index)

action: そのフローに対応するアクション
(デフォルト値: index)

file: そのフローに対応するフロー定義ファイル名
(デフォルト値: フロー名 + configExtension)

isExclusive: フローを排他モードに設定する
(デフォルト値: false)

▲

フロー定義ファイル †

フロー定義ファイルは、 Piece_IDE のフローデザイナーを用いて GUI で編集するか、サンプルに含まれているファイルを参考に手で書いて下さい。書き方については、 Piece_Flow ユーザーズマニュアルを参照して下さい。

▲

サンプル †

動作確認用に簡単なサンプルを用意しました。アーカイブをダウンロードし、適当なディレクトリで p オプションを付けて展開して下さい。

$ cd sample
$ tar xvfzp Revulo_Sample_Counter-0.8.tar.gz

あとは http://…/sample/html/ のような URL にアクセスすれば試すことができます。

▲

ダウンロード †

コンポーネント本体
- Revulo_Controller_Dispatcher_Flow-0.9.tar.gz (Piece_Flow 1.16.0 以降用)
- Revulo_Controller_Dispatcher_Flow-0.8.tar.gz

動作確認用サンプル
- Revulo_Sample_Counter-0.8.tar.gz
- Revulo_Sample_Registration-0.8.tar.gz (動作には Piece_Right 用コンポーネントも必要です)
- Revulo_Sample_Questionnaire-0.8.tar.gz *2 (動作には Piece_Right 用コンポーネントも必要です)

▲

更新履歴 †

Version 0.9 (2008/07/29)
- Piece_Flow 1.16.0, Stagehand_FSM 1.10.0 でエラーハンドリングが変更されたのに対応

Version 0.8 (2007/12/02)
- Zend Framewowk 1.0.3 で Zend_Loader が変更されたことにより動作しなくなっていたのを修正
- Piece_Flow 内で exception レベルのエラーが発生した場合に、例外を投げるよう実装
- Piece_Flow_Continuation クラスでなく Piece_Flow_Continuation_Server, Piece_Flow_Continuation_Service クラスを用いるように変更
- Piece_Unity の仕様に合わせて、flowDefinitions から flowMappings にオプション名を変更
- 設定可能なオプションを追加
  - configExtension
  - enableGC
  - gcExpirationTime
- フロー定義ファイルのデフォルトの拡張子を .flow に変更

Version 0.7.1 (2007/09/03)
- フロー定義ファイルとキャッシュは、デフォルトモジュールのディレクトリの下に配置するように変更
- autoload する際に全てのコントローラディレクトリを include_path に含めるように修正

Version 0.7 (2007/09/02)
- モジュールへの対応を強化するために、configDirectory, cacheDirectory の設定方法を見直し
  - モジュールのディレクトリを起点とする相対パスで指定するように変更
  - 指定がなければ、デフォルト値を用いて自動設定するように変更
- 必要な時だけ Zend_Config クラスを読み込むように変更

Version 0.6 (2007/08/25)
- MVC でモジュールを使用した場合に動かなかったのを修正
- アクションコントローラのディレクトリを自動設定するように変更
- フローの module, controller, action の指定がない場合はデフォルト値を用いるように変更
- preDispatch() メソッドが初回に実行されていなかったのを修正
- オブジェクトをセッションから復元するための autoload 用のコードを組み込み
- フロー制御を用いない通常の場合には Piece_Flow ライブラリを読み込まないように変更

Version 0.4 (2007/06/02)
- 動作環境を Zend Framework 1.0.0 RC1, Piece_Flow 1.9.0 以降に変更
- アクションコントローラの preDispatch(), postDispatch() メソッドが実行されていなかったのを修正

Version 0.3 (2007/05/13)
- アクションコントローラの init() メソッドが最初しか実行されなかったのを修正
- アクションコントローラの View Integration 機構に対応
- 不要なデータをセッションに保存しないように修正

Version 0.2 (2007/02/26)
- Zend_Controller_Action クラスのメソッドを使えるように変更

Version 0.1 (2007/02/25)
- とりあえず動くようになったと思うので公開

*1 シングルフローモードの説明は

Piece Frameworkの概要に載っています。
*2 Zend_View_Helper が複数のチェックボックスに未対応なので、その部分の処理はかなり無理矢理です。

AjaxTree

Top (135)

Debian (9)
Ethna (11)
PHP (4)
PukiWiki (34)
SVG (1)
VMware (31)
Zend Framework (7)
- 自作コンポーネント (6)
  - HTML_Emoji
  - Phtmlc
  - Piece_Flow
  - Piece_Right
  - Simplate
  - Speedy
tDiary (13)
玄箱 (16)