コントローラのアノテーションに関する規約

[chihiro-adachi]

概要(Overview)

3.nでは #2127 でSymfonyFrameworkExtraBundleが提供している各種アノテーションを利用できるようになりました。

本issueは、コントローラに付与するアノテーションについての規約の素案です。

アノテーションのコーディング規約

全体コード

/**
 * @Component
 * // - @Routeでコンテナからインスタンスを取得するため、@Componentでコンテナに登録する
 * // - コンテナIDの指定は原則行わなず、クラス名のFQDNでコンテナに登録する
 *
 * @Route(service=TopController::class)
 * // - serviceのみ指定する
 * // - serviceはコントローラのクラス名を指定し、コンテナからインスタンスを取得する
 */
class TopController
{
    /**
     * // @Method("POST")
     * // - ControllerProviderでmatch指定されているものは原則省略する
     * // - POST/DELETE/PUTなど、必要な場合のみ付与する
     *
     * @Route("/", requirements={"id" = "\d+"}, name="homepage")
     * // - path, requirements, nameの順に指定する
     * // - nameは3.0.xのControllerProviderのbindの値を踏襲する
     *
     * @Template("index.twig")
     * // - テンプレート名は省略しない
     * // - メソッドの戻り値はパラメータの連想配列を返却。$app->renderは使用しない
     * // - ※現状省略してもTemplateGuesserが対応していないため機能しない
     *
     * // @ParamConverter
     * // - コードの記述を減らせるため積極的に利用する
     * // - @Route("path/to/{id}") の形式の場合は、自動変換が行われるため@ParamConverterは省略可能
     *
     */
    public function index(Application $app, Request $request, Product $Product)
    {
        return []; // @Templateで指定したtwigに引き渡すパラメータを連想配列で返却
    }
}

メソッドの引数について

メソッドの引数は、3.0.xと同様、Application $app, Request $request, [params...] で統一します。

public function index(Application $app, Request $request, Product $Product...)
{

管理画面のpath指定について

管理画面のpathを指定する場合は、/{_admin}を指定します。

/**
 * @Component
 * @Route(service=CustomerController::class)
 */
class CustomerController
{
    /**
      *  @Route("/{_admin}/customer", name="admin_customer")
      */
    public function index(Application $app, Request $request)
    {

httpsの指定について

3.0.xでは、以下のように、明示的に有効にする必要がありましたが、3.nでは自動的に判定されるため、以下のコードは不要です。

// 強制SSL
if ($app['config']['force_ssl'] == \Eccube\Common\Constant::ENABLED) {
       $c->requireHttps();
}

課題事項

• AbstractControllerの取扱

  • 共通して使用しているメソッドやプロパティは用意しておいてもよいかも
  • $appのメソッド($app->url()など)はコントローラで使用できるようにTrait化する
  • コントローラのテストコードが実装しづらくなるため、実装範囲は要検討

• コントローラのリファクタリング

  • 新規登録, 編集を分割

関連

#2463

[okazy]

使用するコンポーネントが変わっていたりするので更新が必要です。

[chihiro-adachi]

コントローラで使用できるアノテーションは以下を参照してください
http://doc4.ec-cube.net/customize_controller