#practical.symfony

この記事はSymfony Advent Calendar 2015 8日目の記事です。前日の記事は@__tai2__さんの「DQLのJOIN WITH構文を使えば、無用な関係を定義せずにテーブルの結合ができる」でした。

ファクトリ（Factories）は、オブジェクトの生成（Creation）に関するデザインパターンで、オブジェクトまたはオブジェクトグラフの組み立て方法についての知識（構成の知識）を集約するものです。Eric Evans氏（@ericevans0）の提唱するドメイン駆動設計（Domain-Driven Design: DDD）のビルディングブロックの1つとしても知られています。

論理的にはファクトリは以下のような構造を持ちます。

クラスまたはメソッドによるファクトリ

クラスまたはメソッドを使ったファクトリはPHP + Symfonyの環境における基本型といえます。その構造は上記の図と同様になります。生成されるオブジェクトのバリアントはファクトリに与える引数の違いから生じます。変数値がランタイム（runtime）にならないと決まらない場合に特に有用ですが、クライアントコードでファクトリクラスを直接使うとクライアントとファクトリが結合する点には注意が必要です。

変数の値は構成の知識ではない

バリアントが少ない場合、異なる変数値の組を持つそれぞれのメソッドを定義すればよいと思うかもしれません。しかし、この場合は構成の知識がそれぞれのメソッドに重複して存在することに留意しなければいけません。例えば、生成対象クラスに可変点が追加された場合を想像してみてください。構成の知識と変数値の組は定義されるタイミングが異なるため、異なる場所に配置される方がより適切であるといえるのです。

DIコンテナを使ったファクトリ

DIコンテナはSymfonyフレームワークを支える基盤です。構成の知識を集約するという観点から見ると、DIコンテナはファクトリの一種といえます。生成されるオブジェクトのバリアントはDIコンテナのサービス定義の違いから生じます。変数値がソースコード記述時（source time）やアプリケーションのデプロイ時（deploy time）に定まるような場合に効果を発揮します。その構造は論理的には先ほどのものと変わりませんが、物理的にはクライアントがファクトリに依存しない点で異なります。

DIコンテナを使ったファクトリでは、変数値はSymfonyアプリケーションのキャッシュクリア時に生成されるDIコンテナクラスのメソッド内に埋め込まれます。DIコンテナの生成（コンパイル）が行われるタイミングのことを私たちはコンパイルタイム（compile time）と呼んでいます。

ドメイン特化言語として表現される可変性

Symfonyの設定ファイルapp/config/config.yml等のコードは、問題ドメインにおける可変性の表現です。そこではソフトウェアの内部的な用語ではなく、そのドメインのクライアントとソフトウェアの間で共通に使われる用語（と構造）が使われます。ドメイン特化言語（Domain-Specific Language: DSL）は解決ドメインにおける実装コンポーネントの可変性を別の形で表現したものといえます。

Note このあたりの話は書籍「ジェネレーティブプログラミング」のp.146「5.9.7 コンフィギュレーションDSL」に詳しく書かれていますので興味のある方は是非ご覧ください。

DIコンテナを使ったファクトリでオブジェクトのバリアントを扱う場合、変数値はサービス定義やパラメーターではなくconfig.ymlで記述されるのが一般的です。なぜなら、config.ymlが配置されるパスapp/config/config.ymlに表されているように変数値はドメイン（フレームワーク）ではなくアプリケーションに属するものだからです。

問題：変数値は事前にわからないためファクトリサービスを定義できない

さて、ここで1つ問題があります。変数値は事前にわからないため、ソースコードを書いているタイミングではファクトリサービスを定義できないのです。

解決：エクステンションやコンパイラーパスを使ってサービス定義を生成する

この問題はメタプログラミングを使ってDIコンテナのサービスを定義することで解決できます。Symfonyにはそのようなプログラミングを行う場所として、エクステンション（Symfony\Component\DependencyInjection\Extension\ExtensionInterface）とコンパイラーパス（Symfony\Component\DependencyInjection\Compiler\CompilerPassInterface）があります。例としてPHPMentorsWorkflowerBundleのコードを見てみましょう。

Workflowerでは1つ以上のワークフロー定義ファイル（BPMNファイル）を持つコンテキストを1つ以上定義することができます。それぞれのコンテキストはBPMNファイルを配置するディレクトリを1つ持ちます。PHPMentors\Workflower\Definition\Bpmn2WorkflowRepositoryオブジェクトはコンテキスト毎のBPMNファイルのパスを保持し、findById()によってワークフローID（ファイル名から拡張子を取り除いたもの）に対応するPHPMentors\Workflower\Workflow\Workflowオブジェクトを返します。このPHPMentors\Workflower\Definition\Bpmn2WorkflowRepositoryのサービス定義を生成するコードは以下のようになります。

PHPMentors\WorkflowerBundle\DependencyInjection\PHPMentorsWorkflowerExtension:

<?php ... namespace PHPMentors\WorkflowerBundle\DependencyInjection; ... class PHPMentorsWorkflowerExtension extends Extension { ... /** * @param array $config * @param ContainerBuilder $container */ private function transformConfigToContainer(array $config, ContainerBuilder $container) { ... foreach ($config['workflow_contexts'] as $workflowContextId => $workflowContext) { $workflowContextIdHash = sha1($workflowContextId); $bpmn2WorkflowRepositoryDefinition = new DefinitionDecorator('phpmentors_workflower.bpmn2_workflow_repository'); $bpmn2WorkflowRepositoryServiceId = 'phpmentors_workflower.bpmn2_workflow_repository.'.$workflowContextIdHash; $container->setDefinition($bpmn2WorkflowRepositoryServiceId, $bpmn2WorkflowRepositoryDefinition); $definitionFiles = Finder::create() ->files() ->in($workflowContext['definition_dir']) ->depth('== 0') ->sortByName() ; foreach ($definitionFiles as $definitionFile) { $workflowId = Bpmn2File::getWorkflowId($definitionFile->getFilename()); $bpmn2FileDefinition = new DefinitionDecorator('phpmentors_workflower.bpmn2_file'); $bpmn2FileDefinition->setArguments(array($definitionFile->getPathname())); $bpmn2FileServiceId = 'phpmentors_workflower.bpmn2_file.'.sha1($workflowContextId.$workflowId); $container->setDefinition($bpmn2FileServiceId, $bpmn2FileDefinition); $bpmn2WorkflowRepositoryDefinition->addMethodCall('add', array(new Reference($bpmn2FileServiceId))); $processDefinition = new DefinitionDecorator('phpmentors_workflower.process'); $processDefinition->setArguments(array(pathinfo($definitionFile->getFilename(), PATHINFO_FILENAME), new Reference($bpmn2WorkflowRepositoryServiceId))); $processServiceId = 'phpmentors_workflower.process.'.sha1($workflowContextId.$workflowId); $container->setDefinition($processServiceId, $processDefinition); } } } ...

エクステンションとコンパイラーパスのどちらを使うべきかはケースバイケースですが、やることは変わりません。いずれの場合においても、DIコンテナのコンパイル時にファクトリが動作するように見えることから、私はこのような解決策をコンパイルタイムファクトリ（Compile Time Factories）と名付け、ソフトウェアパターンとして積極的に活用しています。

おわりに

コンパイルタイムファクトリを使うと、バリアントの定義をアプリケーションに委ねつつ、構成の知識をドメイン（フレームワーク）に集約することができます。また、コンパイルタイムファクトリを使うことで、従来必要とされたファクトリクラスの多くは不要になります。それは単なる機構を超えて、関連するドメインモデルにもいくらかの影響を与えることでしょう。James Coplien氏（@jcoplien）が書籍「マルチパラダイムデザイン」で述べたように、解決ドメインの構造が問題ドメインの構造を変化させるのですから。

参考

Factory Pattern | Object Oriented Design

ジェネレーティブプログラミング (IT Architects’Archive CLASSIC MODER)

Symfony Advent Calendar 2014 (Qiita) 10日目

前(12月9日)

次(12月11日)

PHPMentorsPageflowerBundleは筆者が開発したSymfonyアプリケーション向けのページフローエンジンです。特徴としては、以下のものが挙げられます。

アノテーションによるページフロー定義

対話の管理

アクセス制御されたアクション

対話スコープのプロパティ

対話開始直後に実行されるユーザー定義メソッド

複数のブラウザーウィンドウまたはタブのサポート

PHPMentorsPageflowerBundleを使うと、コントローラーに断片的に埋め込まれたページフローに関するコードを明示的な定義で置き換えることができます。また、対話と対話スコープのプロパティの導入によってコントローラーの状態管理コードを大幅を削減することができます。

では、早速コードを見てみましょう。以下はSymfony2ベースのユーザー登録サンプルのコードです。

Example\UserRegistrationBundle\Controller\UserRegistrationController:

<?php /* * Copyright (c) 2012-2014 KUBO Atsuhiro <[email protected]>, * 2014 YAMANE Nana <[email protected]>, * All rights reserved. * * This file is part of PHPMentors_Training_Example_Symfony. * * This program and the accompanying materials are made available under * the terms of the BSD 2-Clause License which accompanies this * distribution, and is available at http://opensource.org/licenses/BSD-2-Clause */ namespace Example\UserRegistrationBundle\Controller; use PHPMentors\DomainKata\Usecase\UsecaseInterface; use PHPMentors\PageflowerBundle\Annotation\Accept; use PHPMentors\PageflowerBundle\Annotation\EndPage; use PHPMentors\PageflowerBundle\Annotation\Init; use PHPMentors\PageflowerBundle\Annotation\Page; use PHPMentors\PageflowerBundle\Annotation\Pageflow; use PHPMentors\PageflowerBundle\Annotation\StartPage; use PHPMentors\PageflowerBundle\Annotation\Stateful; use PHPMentors\PageflowerBundle\Annotation\Transition; use PHPMentors\PageflowerBundle\Controller\ConversationalControllerInterface; use PHPMentors\PageflowerBundle\Conversation\ConversationContext; use Sensio\Bundle\FrameworkExtraBundle\Configuration\Method; use Sensio\Bundle\FrameworkExtraBundle\Configuration\Route; use Symfony\Bundle\FrameworkBundle\Controller\Controller; use Symfony\Component\HttpFoundation\Request; use Symfony\Component\HttpFoundation\Response; use Example\UserRegistrationBundle\Entity\User; use Example\UserRegistrationBundle\Form\Type\UserRegistrationType; /** * @Route("/users/registration", service="example_user_registration.user_registration_controller") * @Pageflow({ * @StartPage({"input", * @Transition("confirmation"), * }), * @Page({"confirmation", * @Transition("success"), * @Transition("input") * }), * @EndPage("success") * }) */ class UserRegistrationController extends Controller implements ConversationalControllerInterface { const VIEW_INPUT = 'ExampleUserRegistrationBundle:UserRegistration:input.html.twig'; const VIEW_CONFIRMATION = 'ExampleUserRegistrationBundle:UserRegistration:confirmation.html.twig'; const VIEW_SUCCESS = 'ExampleUserRegistrationBundle:UserRegistration:success.html.twig'; /** * {@inheritDoc} */ private $conversationContext; /** * @var User * * @Stateful */ private $user; /** * {@inheritDoc} */ public function setConversationContext(ConversationContext $conversationContext) { $this->conversationContext = $conversationContext; } /** * @Init */ public function initialize() { $this->user = new User(); } /** * @return Response * * @Route("/") * @Method("GET") * @Accept("input") * @Accept("confirmation") */ public function inputGetAction() { if ($this->conversationContext->getConversation()->getCurrentPage()->getPageId() == 'confirmation') { $this->conversationContext->getConversation()->transition('input'); } $form = $this->createForm(new UserRegistrationType(), $this->user, array('action' => $this->generateUrl('example_userregistration_userregistration_inputpost'), 'method' => 'POST')); return $this->render(self::VIEW_INPUT, array( 'form' => $form->createView(), )); } /** * @param Request $request * @return Response * * @Route("/") * @Method("POST") * @Accept("input") * @Accept("confirmation") */ public function inputPostAction(Request $request) { if ($this->conversationContext->getConversation()->getCurrentPage()->getPageId() == 'confirmation') { $this->conversationContext->getConversation()->transition('input'); } $form = $this->createForm(new UserRegistrationType(), $this->user, array('action' => $this->generateUrl('example_userregistration_userregistration_inputpost'), 'method' => 'POST')); $form->handleRequest($request); if ($form->isValid()) { $this->conversationContext->getConversation()->transition('confirmation'); return $this->redirect($this->conversationContext->generateUrl('example_userregistration_userregistration_confirmationget')); } else { return $this->render(self::VIEW_INPUT, array( 'form' => $form->createView(), )); } } /** * @return Response * * @Route("/confirmation") * @Method("GET") * @Accept("confirmation") */ public function confirmationGetAction() { $form = $this->createFormBuilder(null, array('action' => $this->generateUrl('example_userregistration_userregistration_confirmationpost'), 'method' => 'POST')) ->add('prev', 'submit', array('label' => '修正する')) ->add('next', 'submit', array('label' => '登録する')) ->getForm(); return $this->render(self::VIEW_CONFIRMATION, array( 'form' => $form->createView(), 'user' => $this->user, )); } /** * @param Request $request * @return Response * * @Route("/confirmation") * @Method("POST") * @Accept("confirmation") */ public function confirmationPostAction(Request $request) { $form = $this->createFormBuilder(null, array('action' => $this->generateUrl('example_userregistration_userregistration_confirmationpost'), 'method' => 'POST')) ->add('prev', 'submit', array('label' => '修正する')) ->add('next', 'submit', array('label' => '登録する')) ->getForm(); $form->handleRequest($request); if ($form->isValid()) { if ($form->get('prev')->isClicked()) { return $this->redirect($this->conversationContext->generateUrl('example_userregistration_userregistration_inputget')); } if ($form->get('next')->isClicked()) { $this->createUserRegistrationUsecase()->run($this->user); $this->conversationContext->getConversation()->transition('success'); return $this->render(self::VIEW_SUCCESS); } } $this->conversationContext->getConversation()->transition('input'); return $this->render(self::VIEW_CONFIRMATION, array( 'form' => $form->createView(), )); } /** * @return UsecaseInterface */ private function createUserRegistrationUsecase() { return $this->get('example_user_registration.user_registration_usecase'); } }

アノテーションによるページフロー定義

... /** * ... * @Pageflow({ * @StartPage({"input", * @Transition("confirmation"), * }), * @Page({"confirmation", * @Transition("success"), * @Transition("input") * }), * @EndPage("success") * }) */ ...

@Pageflowアノテーションによるページフロー定義では、ページとページ間の関係を記述します。ページは1つの@StartPage、0以上の@Page、1つの@EndPageで構成されます。@StartPageは対話が開始された後に遷移するページ（開始ページ）、@EndPageはそこに遷移すると対話が終了するページ（終了ページ）を示します。ページ間の関係は@Transitionによって記述します。

対話の管理

対話はリクエストされたURLがページフローのコントローラーである場合に自動的に開始される、ページフローのインスタンスです。1つのページフローに対して複数の対話を実行することができます。

対話は固有のID（対話ID）によって識別されます。リダイレクトURLの生成等で対話IDが埋め込まれたURLが必要な場合はController::generateUrl()の代わりにConversationContext::generateUrl()を使うことができます。また、フォームではCONVERSATION_IDフィールドが自動的に提供されます。

開発者はコントローラーの中でConversation::transition()を呼び出すことにより、カレントページを変更します。Conversation::transition()によって終了ページに遷移すると、対話は自動的に破棄されます。

アクセス制御されたアクション

... /** * ... * @Accept("confirmation") */ public function confirmationPostAction(Request $request) { ...

@Acceptアノテーションによって、アクションを実行可能なページをホワイトリスト形式で記述します。カレントページがリストに存在しない場合、HTTPステータスコード403が返されます。

対話スコープのプロパティ

... /** * @var User * * @Stateful */ private $user; ...

@Statefulアノテーションによって、プロパティを対話に紐付けることができます。プロパティは対話に限定されたセッション変数のように振る舞います。

対話開始直後に実行されるユーザー定義メソッド

... /** * @Init */ public function initialize() { $this->user = new User(); } ...

@Initアノテーションが付与されたメソッドは、対話の開始直後に自動的に実行されます。これらのメソッドは主に@Statefulが付与されたプロパティの初期化のために使われます。

複数のブラウザーウィンドウまたはタブのサポート

ブラウザーウィンドウまたはタブでそれぞれ別々の対話を実行することができます。

PHPMentorsPageflowerBundleを使いはじめるには？

PHPMentorsPageflowerBundleを使いはじめるに際には、ページフローの登録を含めた具体的なコード[Controller] ユーザー登録のページフローを実装した。 · 270b1c3 · phpmentors-jp/phpmentors-training-example-symfonyが参考になるでしょう。

参考

PHPMentorsPageflowerBundle

Symfony Advent Calendar 2014 (Qiita) 4日目

前(12月3日 )

次(12月5日)

Webサービスで、ユーザーのアカウントごとにサブディレクトリを割り当てたいとします（最近はユーザーアカウントごとにサブドメインを割り当てる方が主流かもしれませんが）。例えば次のような形です。

トップページ

http://example.com/

ユーザー hidenorigoto のコンテンツ

http://example.com/hidenorigoto/profile

http://example.com/hidenorigoto/report/20141124

ユーザー someone のコンテンツ

http://example.com/someone/profile

http://example.com/someone/report/20141124

このような形をとるシステムを、みなさん一度は実装したことがあるのではないでしょうか。

問題となる箇所

登録ユーザー（hidenorigoto や someone ）がこのサービスのトップページへアクセスした時に「自分のプロフィール」というリンクを表示することを考えてみます。リンク先はプロフィール表示用のアクションで、ProfileControllerクラスのindexAction() で実装します。examplebundle_profile_index というルートを割り当てるとすると、ルート定義は次のようになります。

ルート定義の例

examplebundle_profile_index: path: /{userdir}/profile defaults: { _controller: ExampleBundle:Profile:index }

このように、ユーザーごとのサブディレクトリがパラメーター (userdir) になっています。

Symfonyのルーティング機能はとても便利で、コントローラーからでもテンプレートからでも（その他の任意の場所からでも）router サービスを使えば、透過的にURLを生成できます。ただし、必要なパラメーターは生成する箇所でその都度渡さなくてはなりません。今回の要件のようにほとんどすべてのURL生成にユーザーのサブディレクトリが必要な場合、どうなるでしょうか？ あらゆる処理にログインユーザーオブジェクトを渡し、それを参照してサブディレクトリパラメーターを準備しなくてはなりません。次に示すようなコード（PHPコード、Twigテンプレートコード）をいろいろなところに書くことになってしまいそうです。

問題コード：コントローラー

<php $subdirectory = $loginUser->getSubdirectory(); $url = $router->generate(‘examplebundle_profile_index’, [‘userdir’ => $subdirectory]);

問題コード：テンプレート

{% set subdirectory = loginUser.subdirectory %} <a href=“{{ path(‘examplebundle_profile_index’, {‘userdir’: subdirectory}) }}”>プロフィール</a>

「リンクのためのURL生成」というのは、ページの処理本体（プロフィールを表示する etc）からすると補助的な処理でしかありません。補助的な処理のために、本来不要であった依存を1つ増やして機能を実現した、ということになります。このような依存関係は排除すべきです。

解決策：Router を拡張する

今回の例では、URLへのサブディレクトリの付加処理がアプリケーションの個々の機能とは直交しており、横断的な関心事であることが分かります。Webアプリケーションの横断的関心事の多くは、すでにフレームワークが担当している領域でもあります。サブディレクトリの付加はURLに関する処理なので、近い役割をすでに担当している Router を拡張するという方法をとってみます。

Router

Router を継承したクラスで generate() メソッドをオーバーライドします。ログインユーザーに応じてサブディレクトリパラメーターを自動的に追加するようにしています。

ExampleBundle/Routing/Router.php

<php ... class Router extends RouterBase { private $securityContext; public function setSecurityContext($securityContext) { $this->securityContext = $securityContext; } public function generate($name, $parameters = array(), $referenceType = self::ABSOLUTE_PATH) { // 除外 if (preg_match('/^login/i', $name)) { // ルート名がexamplebundleから始まるものを対象 } elseif (preg_match('/^examplebundle/i', $name)) { if ($this->securityContext->getToken()) { // ユーザーからディレクトリ名を取得 // (エンティティの内容による） $loginUser = $this->securityContext->getToken()->getUser(); $userDir = $loginUser->getSubdirectory(); } else { $userDir = 'default'; } // サブディレクトリパラメーターをマージ $parameters = array_merge($parameters, ['userdir' => $userDir]); } return parent::generate($name, $parameters, $referenceType); } }

Router の置き換え定義

デフォルトの router サービスを置き換えます。

ExampleBundle/Resources/config/services.yml

router: class: ExampleBundle\Routing\Router parent: router.default calls: - [setSecurityContext, ["@security.context"]]

上記の例は router サービスを「後勝ち方式」で完全に置き換えてしまいます。といっても、もともとの router は router.default のエイリアスなので、定義本体は残っています。その router.default を、新しいルーターサービスの parent に指定しています。これで、組み込みの router サービスに変わって、拡張した router サービスが使われるようになります。

サービスの置き換えは上記の他に、router サービスをデコレートする方法などもあります。[*1]

アクセスしたリソースごとにアクセス権を確認する処理は？

リソースごとのアクセス権の処理は、ルーティングの役割とは別の話になります。ルーティングのレイヤーとしては、単にルート定義にしたがって、アクセスするリソース（someoneのプロフィール）が特定される、という基本機能をそのまま使うのもよいでしょう。

私が実務で今回紹介した拡張を利用したプロジェクトでは、サブディレクトリがそれぞれ完全に独立しており、他のユーザーのサブディレクトリのリソースは絶対に閲覧不可という要件だったため、セキュリティレイヤーの認証処理の一部として実装しました。この時は、他のユーザーのサブディレクトリは「存在しないモノ」という位置づけで処理していました。

Symfony Securityコンポーネントで推奨される方法としては、SecurityVoter を定義する方法[*2]があります。コントローラーごとに異なった指定がある場合等は、こちらの方法がよいですね。

また、Symfony勉強会で@brtriverさんが発表されていたルーティングレイヤーでアクセス権の処理を行うようにする方策[*3]もあります。

いずれにしても、ルートに対してのINとOUT（URL生成とURLへのアクセス）は対になっているので、ルート生成側で横断的な機能を作ったのであれば、URLへのアクセス側でも同じように何らかの横断的処理が必要となります。

まとめ

解決したい問題をどこで解決するとよいのか？ 問題によって選択肢はいくつかあり得ますが、上手い場所、特にフレームワークやライブラリがすでに「問題」として扱っている（＝その関心を対象とするクラスがある）ものに寄せると、それを軸に拡張して解決するといった方法がとれます。

参考

[*1] Advanced Container Configuration (Symfony DependencyInjection component)

[*2] How to Use Voters to Check User Permissions (The Symfony CookBook)

Symfonyフレームワークの動作を設定するコンフィギュレーションとその背後の仕組みは、Symfonyのアーキテクチャを支える強力な屋台骨となっています。この仕組みの応用例の1つとして、コンフィギュレーションエントリをダイナミックに定義する仕掛けを見てみます。

通常のコンフィギュレーション

通常の静的なコンフィギュレーションは、バンドル内のDependencyInjectionディレクトリ以下にConfigurationクラスを用意し、そこで定義されたツリー構造に従って読み込まれます。コンフィギュレーションクラスの例は設定の仕様とは等を参照してください。この場合、あらかじめ固定のコンフィギュレーショングラマーがあり、それにもとづいてコンフィギュレーションファイルに設定を記述し、そのファイルの設定を読み込んでサービスコンテナが動作します。

アプリケーション開発の多くの場面ではこのような静的な定義で十分ですが、コンフィギュレーションで記述したい内容が、必ずしも1つのバンドルの内容だけで決まるとは限りません。他のバンドルと疎結合な状態を保ちつつ、協調して機能するようなコンフィギュレーションはどうやって定義するのでしょうか。

Securityバンドルのエンティティプロバイダの例

他のバンドルと協調動作するコンフィギュレーションの例として、Securityバンドルのエンティティプロバイダの例を紹介します。Symfonyで認証ユーザーのプロバイダーとしてDoctrineのエンティティクラスを使う場合、次のようにsecurity.ymlのprovidersに定義します。

providers: my_entity_provider: entity: class: SecurityBundle:User property: username manager_name: ~

この定義でentityというのがプロバイダの種類を表しており、他にはmemoryがあります。entityの場合はSecurityバンドルの機能とDoctrineの機能が連携して動作しますが、そういったDoctrineを前提とした機能をSecurityバンドルが抱え込んでいるのでしょうか？ ちなみに、EntityUserProviderクラスはDoctrineBridgeという連携パッケージにあります。

このダイナミックな定義の流れは、次の図のようになっています。

Securityバンドルにおけるエンティティプロバイダのグラマー定義は、Securityエクステンションが保持しているプロバイダーファクトリーによって決まるようになっています。Securityバンドルには、このファクトリーのためのインターフェイスが定義されています。

SecurityBundle / DependencyInjection / Security / UserProvider / UserProviderFactoryInterface.php

interface UserProviderFactoryInterface { public function create(ContainerBuilder $container, $id, $config); public function getKey(); public function addConfiguration(NodeDefinition $builder); }

エクステンションは、コンフィギュレーションの仕組みが動作する前に読み込まれています。Doctrineバンドルのbuild()メソッドで、Securityエクステンションがロードされている場合は、Securityエクステンションへエンティティプロバイダーファクトリーを登録しています。

DoctrineBundle / DoctrineBundle.php

public function build(ContainerBuilder $container) { parent::build($container); $container->addCompilerPass(new RegisterEventListenersAndSubscribersPass('doctrine.connections', 'doctrine.dbal.%s_connection.event_manager', 'doctrine'), PassConfig::TYPE_BEFORE_OPTIMIZATION); if ($container->hasExtension('security')) { $container->getExtension('security')->addUserProviderFactory(new EntityFactory('entity', 'doctrine.orm.security.user.provider')); } $container->addCompilerPass(new DoctrineValidationPass('orm')); }

プロバイダーファクトリーとして登録されるEntityFactoryは、コンフィギュレーションノードを追加するメソッド(addConfiguration())を持っています。

Bridge / Doctrine / DependencyInjection / Security / UserProvider / EntityFactory.php

class EntityFactory implements UserProviderFactoryInterface { ... public function addConfiguration(NodeDefinition $node) { $node ->children() ->scalarNode('class')->isRequired()->cannotBeEmpty()->end() ->scalarNode('property')->defaultNull()->end() ->scalarNode('manager_name')->defaultNull()->end() ->end() ; } }

Securityバンドルのグラマー準備段階で、登録されたプロバイダーファクトリーのノード追加メソッドを呼び出しています($factory->addConfiguration())。

SecurityBundle / DependencyInjection / MainConfiguration.php

foreach ($this->userProviderFactories as $factory) { $name = str_replace('-', '_', $factory->getKey()); $factoryNode = $providerNodeBuilder->children()->arrayNode($name)->canBeUnset(); $factory->addConfiguration($factoryNode); }

これにより、security.ymlを読み込む段階では、グラマー定義としてentityという項目がすでに有効になっている状態になります。コンフィギュレーションファイルが読み込まれ、エンティティプロバイダーが有効になります($factory->create())。

SecurityBundle / DependencyInjection / SecurityExtension.php

private function createUserDaoProvider($name, $provider, ContainerBuilder $container, $master = true) { $name = $this->getUserProviderId(strtolower($name)); foreach ($this->userProviderFactories as $factory) { $key = str_replace('-', '_', $factory->getKey()); if (!empty($provider[$key])) { $factory->create($container, $name, $provider[$key]); return $name; } }

（しかし、ここはサービスコンテナのコンパイル段階であって、有効になるといってもエンティティプロバイダーのサービス定義が追加されるのみです。アプリケーションのランタイムまで、実際のオブジェクトはインスタンス化されません）

Bridge / Doctrine / DependencyInjection / Security / UserProvider / EntityFactory.php

class EntityFactory implements UserProviderFactoryInterface { public function create(ContainerBuilder $container, $id, $config) { $container ->setDefinition($id, new DefinitionDecorator($this->providerId)) ->addArgument($config['class']) ->addArgument($config['property']) ->addArgument($config['manager_name']) ; }

まとめ

サービスコンテナと、コンフィギュレーションとエクステンションの動きが見えてくると、Symfonyがどのように作られ動いているのか、把握しやすくなります。Securityバンドルはこの仕組みを最も高度に利用しているバンドルの1つです。ソースを読んでみるとさまざまな発見があります。

参考

SecurityBundle Configuration (“security”) (master) - Symfony

フォームは、PHPメンターズの設計と実装の型で述べているように、アプリケーションレイヤーにて実装されます。今回はフォームのバリデーションの拡張についてとりあげます。

バリデーションの仕組みの基本

ユーザーが入力した値を受け取り、アプリケーションのフォームでその入力を表すオブジェクト（フォームのデータを格納する入れ物、フォームDTO: Data Transfer Objectと名づけます）が組み立てられます。このフォームDTOの持つデータが妥当かどうかをチェックするのがバリデーションの役割です。

バリデーションはフォームDTOに対して行われるため、SymfonyではフォームDTOクラスにバリデーションの定義を記述します。

class Author { /** * @Assert\NotBlank() * @Assert\Length(min = "3") */ private $firstName; }

フォームDTOのデータを確認するための様々な制約がSymfonyに用意されています。基本的には、フォームDTOのフィールドについて検証を行うもので、処理はフォームDTO内に閉じている前提になっています。

しかし、フォームを使うアプリケーションでは単純に単一エントリのデータの妥当性検査を行うだけでなく、関連データも含めた整合性検査も行いたい場合があります。簡単な例は「登録するメールアドレスがシステム内でユニークであること」といった条件です。ユーザーが入力したデータだけでなく、すでに登録されているデータを検索してチェックしなくてはなりません。Symfonyにはこの目的に特化したUniqueEntityという制約が用意されていますが、このような処理を一般化して考えると、単なるユニーク制約ではなく、「ドメインのルールに基づくバリデーション」を行いたいということになります。

ドメインのルールはどこに表されている？

ドメイン駆動設計に「仕様（Specification）」というパターンがあります（Symfonyでの実装例）。この名前から想起されるとおり、バリデーションで使いたいようなルールは、ドメインの仕様として表すことができます。先ほど例に挙げたユニークであるかどうかという制約もドメインにおける仕様です。仕様オブジェクトとして独立させる他に、リポジトリのメソッドとして表現してもよいでしょう。

仕様として表現する場合、これは1つのオブジェクトで、状態を持たないサービスの一種です。この中では自由に他のサービスやリポジトリを組み合わせて使えます。ですから、アプリケーションのフォームにおけるバリデーションに、ドメインレイヤーのサービスを手軽に指定できればよさそうです。

バリデーションにサービスのメソッドを使う

Alert  これ以降の「サービス」は、DDDのサービスのことではなくて、Symfonyのコンテナで扱うサービスを指します。

Symfonyはサービスコンテナをアーキテクチャの基盤に持っており、さまざまな場面でサービスに処理を分散させることができます。ドメインレイヤーのサービスでも、コンテナに登録してあればどこからでも呼び出せます。

問題は、サービスを使ったバリデーションのための制約が、Symfonyの組み込みでは用意されていないということです。また、制約を記述しているフォームDTOやエンティティは、サービスコンテナの参照を保持しません。どうやってサービスをバリデーション時に呼び出せばよいでしょうか？

筆者の使っているServiceCallbackという制約を紹介します。ServiceCallback制約を使うと、フォームDTOに対してサービスのメソッドをバリデーションに使えます。以下は、サービスコンテナに登録されたdomain.member.allow_upgrade_specというサービスのisSatisfiedByメソッドをバリデーション時に呼び出す記述例です。

/** * @AssertServiceCallback(service="domain.member.allow_upgrade_spec", method="isSatisfiedBy", message="you can't upgrade.") */ class Member {

呼び出すサービスの方はとてもシンプルで、フォームDTOを引数で受け取るisSatisfiedByを定義し、サービスとして登録するのみです。必要であれば他のサービスやリポジトリなどをDIで注入して使うこともできます。検査結果をtrue/falseで返します。

use JMS\DiExtraBundle\Annotation As DI; /** * @DI\Service("domain.member.allow_upgrade_spec") */ class AllowUpgradeSpecification { /** * inject services if you need */ private $memberRepository; public function isSatisfiedBy($member) { // リポジトリなどを使った条件のチェック ... return true; } }

ServiceCallbackバリデーターの実装

カスタムバリデーターの実装には、ServiceCallback制約とServiceCallbackValidatorを作り、バリデーターとして使えるようサービスコンテナに登録しています。

<?php namespace PHPMentors\ValidatorBundle\Validator\Constraints; use Symfony\Component\Validator\Constraint; /** * @Annotation */ class ServiceCallback extends Constraint { public $method; public $service; public $message = 'Service callback returns an error.'; /** * {@inheritdoc} */ public function getTargets() { return self::CLASS_CONSTRAINT; } /** * {@inheritdoc} */ public function validatedBy() { return 'PHPMentorsServiceCallbackValidator'; } }

<?php namespace PHPMentors\ValidatorBundle\Validator\Constraints; use Symfony\Component\DependencyInjection\ContainerAwareInterface; use Symfony\Component\DependencyInjection\ContainerInterface; use Symfony\Component\Validator\Constraint; use Symfony\Component\Validator\ConstraintValidator; use Symfony\Component\Validator\Exception\ConstraintDefinitionException; class ServiceCallbackValidator extends ConstraintValidator implements ContainerAwareInterface { /** * @var ContainerInterface */ protected $container; /** * {@inheritdoc} */ public function validate($object, Constraint $constraint) { if (null === $object) { return; } if (!$this->container->has($constraint->service)) { throw new ConstraintDefinitionException; } $service = $this->container->get($constraint->service); if (!method_exists($service, $constraint->method)) { throw new ConstraintDefinitionException(sprintf('Method "%s" targeted by ServiceCallback constraint does not exist', $constraint->method)); } $result = call_user_func(array($service, $constraint->method), $object); if (false == $result) { $this->context->addViolation($constraint->message); } } /** * {@inheritdoc} */ public function setContainer(ContainerInterface $container = null) { $this->container = $container; } }

parameters: php_mentors_validator.service_callback.class: PHPMentors\ValidatorBundle\Validator\Constraints\ServiceCallbackValidator services: php_mentors_validator.service_callback: class: %php_mentors_validator.service_callback.class% calls: - [ setContainer, ["@service_container"] ] tags: - { name: validator.constraint_validator, alias: PHPMentorsServiceCallbackValidator }

上記コードはSymfony 2.4で動作確認しているものです。2.0向けでは多少書き換えないといけません。動作しているコード例をこちらにあげてあります。

まとめ

ServiceCallback制約を使うことで、バリデーションの記述の自由度が増し、バリデーションのためにフォームDTOやエンティティに余計な知識を埋め込んでしまうことを避けられます。同時に、ドメインの知識がアプリケーションに散らばってしまうことをも防げます。

この制約の実装自体が（厳密なエラー処理等をしていないことを除外しても）とてもシンプルなのは、サービスコンテナやバンドルを土台としているSymfonyのアーキテクチャの恩恵です。しかしその一方で、今回紹介したようにアプリケーションを開発する上でSymfonyに足りない要素があることも事実です。少しだけ手間をかけて仕組みを用意することで、アプリケーションレイヤーとドメインレイヤーの分離を維持することができます。こうしてSymfonyのようなOSSのフレームワークを自分用に育てていけば、頑強な基盤と同時に高い生産性を無理なく両立していけるでしょう。

参考

How to create a Custom Validation Constraint (current) - Symfony

PHPの出力バッファリングは、日本において文字エンコーディングの変換を中心に広く使われてきました。文字エンコーディングとしてUTF-8が定着してきた現在、出力バッファリングは出力文字エンコーディングの変換という用途では余り使われなくなってきていると思われますが、古いアプリケーションでは依然として必要とされていることでしょう。

以下のコードは出力バッファリングの簡単な例です。

<?php ob_start(function ($buffer) { return '__START__' . $buffer . '__END__'; }); echo 'foo'; ob_end_flush(); echo 'bar'; // "__START__foo__END__bar" と表示される

出力バッファの内容は、ob_end_flush()関数やob_get_flush()関数の呼び出しによって明示的に出力バッファをフラッシュするか、スクリプトが終了するタイミングで標準出力に送信されます。

Symfonyにおける出力バッファの扱い

SymfonyではSymfony\Component\HttpFoundation\Response::send()メソッドによってHTTPヘッダと内容の送信が行われます。

Symfony\Component\HttpFoundation\Response(v2.3.4):

<?php ... class Response { ... /** * Sends HTTP headers and content. * * @return Response * * @api */ public function send() { $this->sendHeaders(); $this->sendContent(); if (function_exists('fastcgi_finish_request')) { fastcgi_finish_request(); } elseif ('cli' !== PHP_SAPI) { // ob_get_level() never returns 0 on some Windows configurations, so if // the level is the same two times in a row, the loop should be stopped. $previous = null; $obStatus = ob_get_status(1); while (($level = ob_get_level()) > 0 && $level !== $previous) { $previous = $level; if ($obStatus[$level - 1]) { if (version_compare(PHP_VERSION, '5.4', '>=')) { if (isset($obStatus[$level - 1]['flags']) && ($obStatus[$level - 1]['flags'] & PHP_OUTPUT_HANDLER_REMOVABLE)) { ob_end_flush(); } } else { if (isset($obStatus[$level - 1]['del']) && $obStatus[$level - 1]['del']) { ob_end_flush(); } } } } flush(); } return $this; } ...

出力バッファの送信は、HTTPヘッダと内容の送信の後の少々込み入ったコードで実装されています。コードを見ると、出力バッファのうち削除フラグがtrueのものだけが実際に送信されることがわかります。

Symfonyにはob_start()関数相当のAPIはありません。また、ob_end_clean()関数による出力バッファのクリアも行われません。よってSymfonyでは設定ファイル等による実行時設定やユーザーによるob_start()関数の呼び出しを通した出力バッファリング設定が、そのまま実行環境で有効となります。

出力バッファリングを使う場合はバージョン2.3.4以降または2.2.6以降を使うこと

Symfony 2.3.3以前および2.2.6以前のバージョンは、PHP 5.4で導入された新しい出力APIをサポートしていないため、前述のコードによる出力バッファのクリアが行われません。出力バッファリングを使う場合は、バージョン2.3.4以降または2.2.6以降を使うようにしましょう。

参考

Symfonyでアプリケーションを開発している時に、Twigテンプレートで何度に記述しているビューロジックやフォーマット処理を何処かにまとめたいと考えることが頻繁にあります。複数のプロジェクトで使いまわせるような汎用的な処理はTwig拡張として独自のタグや関数、フィルタにしてしまうと便利ですが、アプリケーション固有の処理で、かつたくさんの種類があると、それらをいちいちTwigの関数などにするのは手間です。

かといって、テンプレートに渡ってくるエンティティオブジェクトにアプリケーション用のフォーマットメソッドなどを実装し始めると、とたんにエンティティオブジェクトにメソッドが増えてしまいます。そもそもこれはアプリケーション側の要求であり、ドメインオブジェクトに持たせるべきものではありません。

そこで、コントローラからテンプレートをレンダリングする時に、ページオブジェクトという中間オブジェクトを1つ用意してやります。ページオブジェクトは、たとえばコントローラと1対1になるように用意します。テンプレートで必要になるオブジェクトやデータは、すべてページオブジェクトが持つようにします（ページオブジェクトはDIコンテナの管理下におき、ユーティリティ系オブジェクトはDIにより注入されるようにしておくとクリーンになります）。

テンプレートで使いたいフォーマット処理があれば、ページオブジェクトにメソッドとして実装します。そうすれば、Twigテンプレートから簡単に呼び出せます。このページオブジェクトはフレームワークの制約を受けない自由なクラスですから、汎用メソッドはTraitにしたりクラスの継承を用いたり、独自のユーティリティクラスにするなども自由に行えます。

サンプル

DDDの仕様パターンの実装サンプルである「キャンペーンサンプル」にて、ページオブジェクトを使っています。以下がキャンペーン関連ページを表示するコントローラに対応するキャンペーンページクラスです。

phpmentors-example-campaign / src / Example / CampaignBundle / Page / CampaignPage.php

class CampaignPage extends AppPage { /** * @var OpenCampaignSpecification */ protected $openCampaignSpec; /** * @var CampaignRepository */ protected $campaignRepository; /** * @var ArrayCollection */ protected $campaignList; public function __construct(OpenCampaignSpecification $openCampaignSpec, CampaignRepository $campaignRepository) { $this->openCampaignSpec = $openCampaignSpec; $this->campaignRepository = $campaignRepository; } public function index() { $this->campaignList = $this->campaignRepository->selectSatisfying($this->openCampaignSpec); } public function all() { $this->campaignList = $this->campaignRepository->findAll(); } /** * @param \DateTime $date * @return string */ public function dateFormat(\DateTime $date) { return $date->format('n月j日'); } /** * @return \Doctrine\Common\Collections\ArrayCollection */ public function getCampaignList() { return $this->campaignList; } /** * @return \Example\CampaignBundle\Domain\Data\Repository\CampaignRepository */ public function getCampaignRepository() { return $this->campaignRepository; } /** * @return \Example\CampaignBundle\Domain\Specification\OpenCampaignSpecification */ public function getOpenCampaignSpec() { return $this->openCampaignSpec; } }

テンプレート側では、キャンペーンページオブジェクト経由でキャンペーン一覧データや、開催中キャンペーン仕様オブジェクトにアクセスし、キャンペーンが開催中かどうかの判定を行なっています（この例ではページオブジェクトに判定メソッドを実装せず、仕様オブジェクトのメソッドをそのまま利用しています）。

phpmentors-example-campaign / src / Example / CampaignBundle / Resources / views / Campaign / all.html.twig

{% extends "ExampleCampaignBundle:Campaign:layout.html.twig" %} {% block content %} <h1>すべてのキャンペーン一覧</h1> <dl> {% for campaign in campaignPage.campaignList %} <dt>{{ campaign.title }} {% if campaignPage.openCampaignSpec.isSatisfiedBy(campaign) %} <strong>開催中</strong>{% endif %}</dt> <dd>開始日：{{ campaignPage.dateFormat(campaign.startDate) }}<br /> 説明：{{ campaign.description }} </dd> {% endfor %} </dl> {% endblock %}

本ブログではこれまで「Stagehand_TestRunnerおよびMakeGoodによるSymfonyの機能テストの実行」、「Symfonyアプリケーションのテスト実行環境を改善する」といった記事でSymfonyのユニットテスト実行環境の構築についてご紹介してきました。本記事ではSymfony2ベースのユーザー登録サンプルで私たちが採用している、PHPUnit、Stagehand_TestRunner、MakeGoodいずれにも対応したユニットテスト実行環境の構築手順を改めてご紹介します。

ユニットテスト実行用ブートストラップファイルの作成

最初にユニットテスト実行用のブートストラップファイルとして以下のようなPHPスクリプトを作成します。

app/bootstrap_test.php:

<?php $_SERVER['KERNEL_DIR'] = __DIR__; require_once $_SERVER['KERNEL_DIR'] . '/bootstrap.php.cache';

PHPUnit以外のプロダクトでComposerのオートローディングが有効でないものを使う場合、このファイルでロードや設定を行うようにします。例えば、インクルードパス上にあるPhakeを使う場合のコードは以下のようになります。

app/bootstrap_test.php:

<?php $_SERVER['KERNEL_DIR'] = __DIR__; require_once $_SERVER['KERNEL_DIR'] . '/bootstrap.php.cache'; require_once 'Phake.php'; Phake::setClient(Phake::CLIENT_PHPUNIT);

Note ブートストラップファイルはStagehand_TestRunnerまたはMakeGoodのプリロードスクリプト機能とPHPUnitのブートストラップ機能によって2回ロードされることがあります。したがって、ブートストラップファイルのコードは、複数回ロードされても問題が発生しないようにしておかなければなりません。

ユニットテスト実行環境の設定

次に前述のブートストラップファイルを使用するようにPHPUnitのXML設定ファイルを変更します。

app/phpunit.xml.dist:

<?xml version="1.0" encoding="UTF-8"?> <!-- http://www.phpunit.de/manual/current/en/appendixes.configuration.html --> <phpunit ... bootstrap = "bootstrap_test.php"> ...

テストランナーとしてMakeGoodを使用する場合はプロジェクトのプロパティを以下のように設定します。

プロジェクトのプロパティを開き、MakeGoodを選択します。

テスティングフレームワークでPHPUnitを選択します。

テストフォルダーにsrcディレクトリを追加します。

プリロードスクリプトに前述のブートストラップファイルのパスを入力します。

ユニットテストの実行

最後にそれぞれのテストランナーのユニットテスト実行方法を示します。

PHPUnit

$ php /path/to/phpunit -c app/phpunit.xml.dist

Stagehand_TestRunner

$ php /path/to/testrunner phpunit -p app/bootstrap_test.php -R src

Stagehand_TestRunner（phpunit:passthroughコマンド）

$ php /path/to/testrunner phpunit:passthrough -p app/bootstrap_test.php -c app/phpunit.xml.dist

Note phpunit:passthroughはStagehand_TestRunner経由でphpunitコマンドを実行するコマンドです。Stagehand_TestRunnerでは1つのファイルに複数のテストクラスを定義することができますが、phpunitでは1つのファイルに1つのテストクラスしか定義することができません。したがって、1つのファイルに複数のテストクラスが定義されている場合、phpunitコマンドではすべてのテストを実行できず、カバレッジ等が使い物にならないという状況が発生します。phpunit:passthroughコマンドを使うと、1つのファイルに複数のテストクラスが定義されている場合でもすべてのテストを実行することができます。

MakeGood

継続的テストが有効な場合はファイルを保存する度に自動的にテストが実行されます。また、MakeGoodビューやコンテキストメニューからいつでも任意のテストを実行することもできます。詳細についてはMakeGoodユーザーガイドをご覧ください。

参考