API Documentation for Piece Framework

phpDocumentor で Piece の API ドキュメントを生成してみました。
http://www.opendogs.org/doc/piece/
以下のパッケージ/バージョンを文書化しています。

  • Piece_Flow 1.8.0 (stable)
  • Piece_Right 1.4.0 (stable)
  • Piece_Unity 0.10.0 (beta)
  • Stagehand_FSM 1.8.0 (stable)
  • Stagehand_TestRunner 0.4.0 (beta)


phpdoc には private なプロパティ/メソッドが載っていないので、Piece を使った開発でよく使うであろうものを挙げておきます。

Piece_Flow_Action の private なプロパティ
プロパティ
$_flow Piece_Flow のインスタンス
$_payload Piece_Unity_Context のインスタンス (Piece_Unity を使う場合)
$_event 現在のイベント名
Piece_Right_Validator_Common の private なメソッド
メソッド 説明 引数 返り値
_initialize() バリデータを初期化するメソッド
この中で _addRule() を呼び出す
  • void
void
_addRule() バリデーションルールを追加する
  • string $rule
    (ルール名)
  • mixed $default
    (デフォルト値, optional)
  • string $message
    (エラーメッセージ, optional)
void
Piece_Unity_Plugin_Common の private なプロパティ
プロパティ
$_context Piece_Unity_Context のインスタンス
Piece_Unity_Plugin_Common の private なメソッド
メソッド 説明 引数 返り値
_initialize() プラグインを初期化するメソッド
この中で _addExtensionPoint() および
_addConfigurationPoint() を呼び出す
  • void
void
_addExtensionPoint() 拡張ポイントを追加する
  • string $extensionPoint
    (拡張ポイント名)
  • mixed $default
    (デフォルト値, optional)
void
_addConfigurationPoint() 設定ポイントを追加する
  • string $configurationPoint
    (設定ポイント名)
  • mixed $default
    (デフォルト値, optional)
void

Examples of Intercepor

Intercepor プラグインを作ってみました。
package.xml はもちろんのこと、 DocBlock コメントも皆無ですが...


設定ポイントの解説は id:perezvon さんの http://d.hatena.ne.jp/perezvon/20070126/1169800012 を真似させていただきました。

Piece_Unity_Plugin_Interceptor_Mobile

携帯端末の判定、レンダラ設定の上書き、出力エンコーディング変換を行うための Interceptor 集 (ダウンロード)
Interceptor_MobileUserAgent で User-Agent の判定を行い、Piece_Unity_Context の attribute に以下の値を設定します。

  • MobileUserAgent_detector (Net_UserAgent_Mobile_xxx のインスタンス)
  • MobileUserAgent_isMobile (携帯端末か否か)
  • MobileUserAgent_supportsCookie (Cookie に対応する端末か否か)

Interceptor_MobileRenderer と Interceptor_MobileOutputFilter では MobileUserAgent_isMobile の値を調べるので、Interceptor_MobileUserAgent はこれらより先に読み込まれなければいけません。

Piece_Unity_Plugin_Interceptor_MobileUserAgent の設定ポイント
キー 説明 デフォルト値
forcedUserAgent $_SERVER['HTTP_USER_AGENT'] を上書きする文字列 (開発用) null
lazyDetection Net_UserAgent_Mobile を用いずに大雑把な判定をするか否か false
Piece_Unity_Plugin_Interceptor_MobileRenderer の設定ポイント

Piece_Unity_Plugin_Renderer_xxx の設定を上書きするので、設定ポイントは View プラグインの renderer 設定ポイントで指定されたレンダラに依存します。


例えば携帯端末用のテンプレートを別にしたい場合は以下のように設定します。
携帯端末用のテンプレートは PC 用のテンプレートと同じエンコーディング (UTF-8 を推奨) で作成し、meta 要素の Content-Type には "text/html; charset=Shift_JIS" と、Interceptor_MobileOutputFilter の headerCharset と同じエンコーディングを指定します。
(エディタによってはファイルのエンコーディングと meta 要素とで異るエンコーディングが指定されている旨の警告が出ることがあります)

- name: InterceptorChain
  point:
    - name: interceptors
      type: extension
      value:
        - Interceptor_NullByteAttackPreventation
        - Interceptor_SessionStart
        - Interceptor_MobileUserAgent
        - Interceptor_MobileRenderer
        - Interceptor_MobileOutputFilter
        - Interceptor_Authentication

- name: Renderer_Flexy
  point:
    - name: templateDir
      type: configuration
      value: ../webapp/templates/FlowName
    - name: compileDir
      type: configuration
      value: ../webapp/compiled-templates/FlowName
    - name: useLayout
      type: configuration
      value: true
    - name: layoutView
      type: configuration
      value: Layout
    - name: layoutDirectory
      type: configuration
      value: ../webapp/templates/Layout
    - name: layoutCompileDirectory
      type: configuration
      value: ../webapp/compiled-templates/Layout

- name: Interceptor_MobileRenderer
  point:
    - name: templateDir
      type: configuration
      value: ../webapp/templates/FlowName_Mobile
    - name: compileDir
      type: configuration
      value: ../webapp/compiled-templates/FlowName_Mobile
    - name: layoutView
      type: configuration
      value: Layout_Mobile


Cookie をサポートしていない携帯端末で同一フロー内リダイレクトする際には、renderer が Renderer_Redirection でない限りは上書きされないので、アクションクラスの _prepare() メソッドに以下のような記述をします。

if (!$this->_payload->getAttribute('MobileUserAgent_supportsCookie')) {
    $config = &$this->_payload->getConfiguration();
    $config->setConfiguration('Renderer_Redirection', 'addSessionID', true);
}
Piece_Unity_Plugin_Interceptor_MobileOutputFilter の設定ポイント
キー 説明 デフォルト値
headerCharset Content-Type HTTP ヘッダに挿入される値 Shift_JIS
outputCharset 出力 (変換先) エンコーディング SJIS-win

変換元エンコーディング (mbstring.internal_encoding) は php.ini 等で別途適切な値に設定されている必要があります。

Piece_Unity_Plugin_Interceptor_GarbageCollection

一時ファイルのガーベッジコレクションを行うための Interceptor (ダウンロード)

設定ポイント
キー 説明 デフォルト値
targetDirectories ガーベッジコレクション対象ディレクト array()
probability ガーベッジコレクション実行確率の分子 1
divisor ガーベッジコレクション実行確率の分母 1000
lifeTime 一時ファイルの有効期限 (秒) 3600
recursionDepth 再帰深度 0
removeEmptySubDirectory 空のサブディレクトリを削除するか否か false
byAccessTime 有効期限をファイルの最終アクセス時刻で判定するか否か
デフォルトではファイルの更新時刻で判定する
false

OmniGraffle -> YAML?

僕はステートチャートの作成に OmniGraffle を使っています。
で、ふと思いついたのですが。
OmniGraffle のファイルフォーマットって XML (Apple Property List) じゃないですか。
で、内容を流し読みしてみたところ、矢印の両端 (および途中の) 結合ポイントと状態 (図形) の結合ポイントが ID で関連付けられているみたいじゃないですか。
ということはだ、OmniGraffle でステートチャートを書いて、適当なフィルタにかければフロー定義ファイルはおろか、プロジェクトのスケルトンまで生成できるという薔薇色の未来がそこにあるんではなかろうか?
と、妄想してみたわけですが、誰かやってみませんか?