3.n アノテーションリファレンス

[kiy0taka]

3.n アノテーションリファレンス

共通

@Inject

DIコンテナに管理されているオブジェクトを、実行時に設定します。

value要素(必須)

アノテーションのパラメータにはDIコンテナに登録している各オブジェクトのキーを指定します。

/**
 * @Service
 */
class CartService
{
    /**
     * 実行時このフィールドにProductClassRepositoryのインスタンスが設定される
     * @Inject(ProductClassRepository::class)
     */
    protected $productClassRepository;
}

コントローラー

@route

ルーティングの定義をするためのアノテーションです。コントローラーのクラスとメソッドに対して指定します。

service要素

DIコンテナに登録するキーを指定します。この要素は、クラスに対して@Routeアノテーションを指定する場合に有効になります。service要素を省略すると、コントローラーがDIコンテナで管理されないため、@Injectによる依存注入が行われなくなります。

/**
 * @Route(service=ProductController::class)
 */
class ProductController
{
    ...
}

path要素(必須)

ルーティングのパスを指定します。/products/detail/1 などパスにリクエストパラメーターを含める場合は、/products/detail/{id} という形で指定します。管理画面の場合は /{_admin}/ で始まるパスを指定します。

/**
 * @Route(service=ProductController::class)
 */
class ProductController
{
    /**
     * パスの{id}部分の値がメソッド引数$idに渡される
     * @Route("/product/detail/{id}")
     */
    public function detail($id)
    {
        ...
    }
}

クラスとメソッドの@Routeアノテーションにそれぞれpath属性を指定した場合は、クラスに指定したpathが接頭辞となります。

/**
 * @Route("/product", service=ProductController::class)
 */
class ProductController
{
    /**
     * このメソッドは /product/list というパスでルーティングされる
     * @Route("/list")
     */
    public function list()
    {
        ...
    }
}

name要素

ルーティング名を指定します。

requirements要素

必須パラメータの指定を行います。/products/detail/{id} というパスを指定した場合にパラメーターidが必須かつ数値である場合は、requirements={"id" = "\d+"} という形で必須条件を指定します。条件に合わないパスでリクエストされた場合は404が返ります。

defaults要素

パスに含まれるパラメータが省略された場合のデフォルト値を設定します。

@method

methods要素

許容するHTTPメソッドを指定します。省略した場合はすべてのHTTPメソッドを許容します。

class ProductController
{
    /**
     * POSTのみを許容するメソッド
     * @Route("/product/update")
     * @Method("POST")
     */
    public function update()
    {
        ...
    }
}

@template

使用するテンプレートを指定します。

template要素(必須)

メソッド終了後にレンダリングするテンプレートのパスを指定します。

class ProductController
{
    /**
     * 正常終了するとProduct/foo.twigがレンダリングされる
     * @Route("/product/foo")
     * @Teplate("Product/foo.twig")
     */
    public function foo($name)
    {
        // テンプレートに渡すパラメータを返す
        return ["name" -> $name];
    }
}

@forwardonly

ルーティングされているメソッドが、クライアントから直接呼び出されるのを禁止して、forward呼び出し時にのみ実行されるように制限します。

class ProductController
{
    /**
     * このメソッドはクライアントから/product/fooというパスでアクセスできる
     * @Route("/product/foo")
     */
    public function foo($app)
    {
        // barメソッドにフォワード
        return $app->forward("/product/bar");
    }


    /**
     * このメソッドはクライアントから直接/product/barというパスではアクセスできない
     * 他のメソッドからフォワードされたときだけ実行される
     * @ForwardOnly
     * @Route("/product/bar")
     */
	public function bar()
	{
	    ...
 	}
}

エンティティ

Doctrine アノテーション

Entityクラスとデータベースのマッピングを指定します。詳細はDoctrineのドキュメントを参照してください。

/**
 * @ORM\Table(name="dtb_product")
 * @ORM\InheritanceType("SINGLE_TABLE")
 * @ORM\DiscriminatorColumn(name="discriminator_type", type="string", length=255)
 * @ORM\HasLifecycleCallbacks()
 * @ORM\Entity(repositoryClass="Eccube\Repository\ProductRepository")
 */
class Product extends AbstractEntity
{
    /**
     * @ORM\Column(name="id", type="integer", options={"unsigned":true})
     * @ORM\Id
     * @ORM\GeneratedValue(strategy="IDENTITY")
     */
    private $id;

    /**
     * @ORM\Column(name="name", type="string", length=255)
     */
    private $name;

    ...
}

@EntityExtension

Entity拡張を実装したトレイトに宣言するアノテーションです。Entity拡張についてはドキュメントを参照してください。

value要素(必須)

拡張対象とするEntityクラスを指定します。

/**
 * Productにメーカー名を追加するEntity拡張
 * @EntityExtension(Product::class)
 */
trait ProductTrait
{
    /**
     * @ORM\Column(type="string", nullable=true)
     */
    public $maker_name;
}

Entityイベント

Entityのライフサイクルイベントに対するイベントリスナーを宣言するためのアノテーションです。Entityイベントの概要についてはドキュメントを参照してください。

各ライフサイクルイベントに対応する以下のアノテーションがあります。

• @LoadClassMetadata
• @OnClassMetadataNotFound
• @onclear
• @OnFlush
• @postflush
• @PostLoad
• @PrePersist
• @PostPersist
• @PreRemove
• @PostRemove
• @PreUpdate
• @postupdate

value属性(必須)

ライフサイクルイベントの発生元となるEntityクラスを指定します。Entityクラスは配列で複数指定することができます。

/**
 * ProductStockが更新される前に実行するリスナー
 * @PreUpdate("Eccube\Entity\ProductStock")
 */
class ProductStockEventListener implements EntityEventListener
{
    public function execute(LifecycleEventArgs $eventArgs)
    {
        // 商品在庫が更新されたときに行う処理を実装する
    }
}

リポジトリ

@repository

RepositoryクラスのインスタンスをDIコンテナで管理するようにするためのアノテーションです。DIコンテナで管理することで、@Injectを使った依存注入が有効になります。

value要素

DIコンテナに登録するキーを指定します。省略した場合は完全修飾クラス名をキーとしてDIコンテナに登録されます。

/**
 * @Repository
 */
class CustomerRepository
{
    /**
     * @Inject("security.encoder_factory")
     * @var EncoderFactory
     */
    protected $encoderFactory;
}

@QueryExtension

アプリケーション内で利用されているQueryBuilderに対する拡張を行うクラスに使用するアノテーションです。

value属性(必須)

拡張対象のQueryBuilder名を指定します。QueryBuilder名はQueryKeyで定義されている定数のいずれかになります。

/**
 * 管理画面の商品マスター検索を拡張するクラス
 * @QueryExtension(QueryKey::PRODUCT_SEARCH_ADMIN)
 */
class AdminProductListCustomizer extends OrderByCustomizer
{
    /**
     * 常に商品IDでソートする。
     */
    protected function createStatements($params)
    {
        return [new OrderByClause('p.id')];
    }
}

サービス

@service

ServiceクラスのインスタンスをDIコンテナで管理するようにするためのアノテーションです。DIコンテナで管理することで、@Injectを使った依存注入が有効になります。

value要素

DIコンテナに登録するキーを指定します。省略した場合は完全修飾クラス名をキーとしてDIコンテナに登録されます。

/**
 * @Service
 */
class CartService
{
    /**
     * @var ProductClassRepository
     * @Inject(ProductClassRepository::class)
     */
    protected $productClassRepository;

    ...
}

フォーム

@Formtype

FormTypeクラスのインスタンスをDIコンテナで管理するようにするためのアノテーションです。DIコンテナで管理することで、@Injectを使った依存注入が有効になります。

value要素

DIコンテナに登録するキーを指定します。省略した場合は完全修飾クラス名をキーとしてDIコンテナに登録されます。

/**
 * @FormType
 */
class ProductType extends AbstractType
{
    /**
     * @Inject(CategoryRepository::class)
     * @var CategoryRepository
     */
    protected $categoryRepository;

    public function buildForm(FormBuilderInterface $builder, array $options)
    {
        ...
    }
}

@FormExtension

FormExtensionクラスのインスタンスをDIコンテナで管理するようにするためのアノテーションです。DIコンテナで管理することで、@Injectを使った依存注入が有効になります。

value要素

DIコンテナに登録するキーを指定します。省略した場合は完全修飾クラス名をキーとしてDIコンテナに登録されます。

/**
 * @FormExtension
 */
class HelpTypeExtension extends AbstractTypeExtension
{
    ...
}

@FormAppend

エンティティに定義したプロパティをFormTypeへ追加するためのアノテーションです。

auto_render要素

twigへ出力を行う場合、trueを指定します。(デフォルトはfalse)

form_theme要素

form_themeを指定します。

type要素

FormTypeを指定します。

options要素

FormTypeのオプション(ラベルやhtml属性など)を指定します。

/**
 * @Eccube\EntityExtension("Eccube\Entity\BaseInfo")
 */
trait BaseInfoTrait
{
    /**
     * @ORM\Column(name="company_name_vn", type="string", length=255, nullable=true)
     * @Assert\NotBlank(message="入力してください")
     * @Eccube\FormAppend(
     *     auto_render=false,
     *     form_theme="Form/company_name_vn.twig",
     *     type="\Symfony\Component\Form\Extension\Core\Type\TextType",
     *     options={
     *          "required": true,
     *          "label": "会社名(VN)"
     *     })
     */
    public $company_name_vn;
}

FormTypeに追加したプロパティに対するバリデーションの指定には Symfonyのアノテーションを使用することができます。

[okazy]

4.0ではSymfonyのアノテーションを利用しています。
独自のアノテーションも追加しているため、4.0のアノテーションのドキュメントは別途用意します。