Caution: You are browsing the legacy symfony 1.x part of this website.
Cover of the book Symfony 5: The Fast Track

Symfony 5: The Fast Track is the best book to learn modern Symfony development, from zero to production. +300 pages showcasing Symfony with Docker, APIs, queues & async tasks, Webpack, SPAs, etc.

generator.yml設定ファイル

1.2
Symfony version
1.4
Language

symfonyのadminジェネレーターはモデルクラス用のバックエンドインターフェイスの作成を可能にします。 PropelもしくはDoctrineをORMとして使うことで機能します。

作成

adminジェネレーターモジュールはpropel:generate-adminもしくはdoctrine:generate-adminタスクによって作成されます:

$ php symfony propel:generate-admin backend Article

$ php symfony doctrine:generate-admin backend Article

上記のコマンドはArticleモデルクラス用のarticle adminジェネレーターモジュールを作成します。

note

generator.yml設定ファイルはPHPファイルとしてキャッシュされます; 処理はsfGeneratorConfigHandlerクラスによって自動的に管理されます。

設定ファイル

上記のようなモジュールの設定はapps/backend/modules/job/article/generator.ymlファイルで行います:

generator:
  class: sfPropelGenerator
  param:
    # パラメーターの配列

ファイルは2つのメインエントリー: classparamを格納します。 クラスはPropelに対してsfPropelGeneratorでDoctrineに対してはsfDoctrineGeneratorです。

paramエントリーは生成されたモジュール用の設定オプションを格納します。 model_classはこのモジュールにバインドされるモデルクラスを定義し、themeオプションはデフォルトで使用するテーマを定義します。

しかしメインのコンフィギュレーションはconfigエントリの下にあります。 これは7つのセクションに分かれます:

  • actions: リストとフォームで見つかるアクションのデフォルトコンフィギュレーション
  • fields: フィールド用のデフォルトコンフィギュレーション
  • list: リスト用のコンフィギュレーション
  • filter: フィルター用のコンフィギュレーション
  • form: 新規ページ/編集フォーム用のコンフィギュレーション
  • edit: 編集ページ用固有のコンフィギュレーション
  • new: 新規ページ用固有のコンフィギュレーション

最初に生成されるとき、すべてのセクションは空なものとして定義されます。 adminジェネレーターはすべての実行可能なオプションに対して適切なデフォルトを定義します:

generator:
  param:
    config:
      actions: ~
      fields:  ~
      list:    ~
      filter:  ~
      form:    ~
      edit:    ~
      new:     ~

この章ではconfigエントリーを介してadminジェネレーターをカスタマイズするために使うことのできるすべての利用可能なオプションを説明します。

note

すべてのオプションはPropelとDoctrineの両方で利用可能で言及していなければ同じ動作をします。

フィールド

多くのオプションはフィールドのリストを引数として受け取ります。 フィールドは実際のカラム名もしくは仮想的な名前になります。 両方のケースにおいてゲッターはモデルクラスで定義しなければなりません(getの後にキャメルケースのフィールド名が続く)。

adminジェネレーターはコンテキストに基づき、フィールドをレンダリングするためのスマートなやり方を知っています。 レンダリングをカスタマイズするには、パーシャルもしくはコンポーネントを作ります。 慣習では、パーシャルにはプレフィックスとしてアンダースコア(_)を、コンポーネントにはプレフィックスとしてチルダ(``)をつけます:

display: [_title, ~content]

上記の例において、titleフィールドはtitleパーシャルによってレンダリングされ、contentフィールドはcontentコンポーネントによってレンダリングされます。

adminジェネレーターはパーシャルとコンポーネントに対していくつかのパラメーターを渡します:

  • neweditページに対して:

    • form: 現在のモデルオブジェクトに関連づけされているフォーム
    • attributes: ウィジェットに適用されるHTML属性の配列
  • listページに対して:

    • type: list
    • MODEL_NAME: 現在のオブジェクトのインスタンス、MODEL_NAMEは小文字版のモデルクラスの名前。

editもしくはnewページにおいて、2つのカラムレイアウトを維持したい場合(フィールドラベルとウィジェット)、パーシャルもしくはコンポーネントテンプレートは次のテンプレートに従います:

<div class="sf_admin_form_row">
  <label>
    <!-- Field label or content to be displayed in the first column -->
  </label>
  <!-- Field widget or content to be displayed in the second column -->
</div>

オブジェクトプレースホルダー

オプションのなかにはモデルオブジェクトプレースホルダーを受け取ることができるものがあります。 プレースホルダーは%%NAME%%のパターンに従う文字列です。 NAMEの文字列はオブジェクトのゲッターメソッドの名前に使われる妥当な文字列になります(getの後にキャメルケースバージョンのNAME文字列が続く)。 たとえば、%%title%%$article->getTitle()の値に置き換えられます。 現在のコンテキストに関連するオブジェクトに従ってプレースホルダーの値は実行時に動的に置き換えられます。

tip

モデルが別のモデルへの外部キーを持つとき、PropelとDoctrineは関連オブジェクト用のゲッターを定義します。 ほかのゲッターに関して、オブジェクトを文字列に変換する意味のある__toString()メソッドを定義していればプレースホルダーとして使うことができます。

コンフィギュレーションの継承

adminジェネレーターのコンフィギュレーションはコンフィギュレーションカスケードの原則に基づきます。 継承ルールは次のとおりです:

  • neweditformを継承しformfieldsを継承する
  • listfieldsを継承する
  • filterfieldsを継承する

クレデンシャル

credentialオプション(下記を参照)を使うユーザークレデンシャルに基づいて、(リストとフォーム上の)adminジェネレーターのアクションを隠すことができます。 しかしながら、リンクもしくはボタンが現れないとしても、違法なアクセスからアクションが適切にセキュアな状態でなければなりません。 adminジェネレーターのクレデンシャル管理機能は表示のみを処理します。

credentialオプションはlistページのカラムを隠すためにも使うことができます。

アクションのカスタマイズ

設定が十分ではないとき、生成メソッドをオーバーライドできます:

メソッド 説明
executeIndex() listビューアクション
executeFilter() フィルターを更新する
executeNew() newビューアクション
executeCreate() 新しいJobを作成する
executeEdit() editビューアクション
executeUpdate() Jobを更新する
executeDelete() Jobを削除する
executeBatch() バッチアクションを実行する
executeBatchDelete() _deleteバッチアクションを実行する
processForm() Jobフォームを処理する
getFilters() 現在のフィルターを返す
setFilters() フィルターをセットする
getPager() listページャーを返す
getPage() ページャーページを取得する
setPage() ページャーページをセットする
buildCriteria() list用にCriteriaをビルドする
addSortCriteria() list用にソートのCriteriaを追加する
getSort() 現在のソートカラムを返す
setSort() 現在のソートカラムをセットする

テンプレートのカスタマイズ

それぞれの生成テンプレートを上書きできます:

テンプレート 説明
_assets.php テンプレートに使うCSSとJSをレンダリングする
_filters.php フィルターボックスをレンダリングする
_filters_field.php 単独のフィルターフィールドをレンダリングする
_flashes.php flashメッセージをレンダリングする
_form.php フォームを表示する
_form_actions.php フォームのアクションを表示する
_form_field.php 単独のフォームフィールドを表示する
_form_fieldset.php フォームのフィールドセットを表示する
_form_footer.php フォームのフッターを表示する
_form_header.php フォームのヘッダーを表示する
_list.php listを表示する
_list_actions.php listアクションを表示する
_list_batch_actions.php listバッチアクションを表示する
_list_field_boolean.php listの単独のブール型フィールドを表示する
_list_footer.php listのフッターを表示する
_list_header.php listのヘッダーを表示する
_list_td_actions.php 列用のオブジェクトアクションを表示する
_list_td_batch_actions.php 列用のチェックボックスを表示する
_list_td_stacked.php 列用のstackedレイアウトを表示する
_list_td_tabular.php list用の単独フィールドを表示する
_list_th_stacked.php ヘッダー用の単独のカラム名を表示する
_list_th_tabular.php ヘッダー用の単独のカラム名を表示する
_pagination.php listページパジネーションを表示する
editSuccess.php editビューを表示する
indexSuccess.php listビューを表示する
newSuccess.php newビューを表示する

外見のカスタマイズ

生成されるテンプレートは多くのclassid属性を定義するのでadminジェネレーターの外見はとても簡単にカスタマイズできます。

editもしくはnewページにおいて、それぞれのフィールドのHTMLコンテナーは次のクラスを持ちます:

  • sf_admin_form_row
  • フィールドの型に依存するクラス: sf_admin_textsf_admin_booleansf_admin_datesf_admin_timeもしくはsf_admin_foreignkey
  • sf_admin_form_field_COLUMNCOLUMNがカラムの名前です。

listページにおいて、それぞれのフィールドのHTMLコンテナーは次のクラスを持ちます:

  • フィールドの型に依存するクラス: sf_admin_textsf_admin_booleansf_admin_datesf_admin_time、もしくはsf_admin_foreignkey
  • sf_admin_form_field_COLUMNCOLUMNがカラムの名前です。

利用可能なコンフィギュレーションオプション

fields

fieldsセクションはそれぞれのフィールドに対するデフォルトコンフィギュレーションを定義します。 このコンフィギュレーションはすべてのページに対して定義されページごとにオーバーライドできます(listfilterformeditnew)。

label

デフォルト: 人間にわかりやすいカラムの名前

labelオプションはフィールドに使うラベルを定義します:

config:
  fields:
    slug: { label: "URL shortcut" }

help

デフォルト: なし

helpオプションはフィールド用に表示するヘルプテキストを定義します。

attributes

デフォルト: array()

attributesオプションはウィジェットに渡すHTML属性を定義します:

config:
  fields:
    slug: { attributes: { class: foo } }

credentials

デフォルト: なし

credentialsオプションは表示するフィールドに対してユーザーが持たなければならないクレデンシャルを定義します。 クレデンシャルはオブジェクトのリストに対してのみ強制されます。

config:
  fields:
    slug:      { credentials: [admin] }
    is_online: { credentials: [[admin, moderator]] }

note

クレデンシャルはsecurity.yml設定ファイルと同じルールで定義されます。

renderer

デフォルト: なし

rendererオプションはフィールドをレンダリングするために呼び出すPHPコールバックを定義します。 定義されていれば、パーシャルもしくはコンポーネントのようにほかのフラグをオーバーライドします。

コールバックはrenderer_argumentsオプションで定義されるフィールドと引数の値で呼び出されます。

renderer_arguments

デフォルト: array()

renderer_argumentsオプションはフィールドをレンダリングする際にPHPのrendererコールバックに渡す引数を定義します。 rendererオプションが定義される場合のみ使われます。

actions

フレームワークはいくつかの組み込みのアクションを定義します。 これらすべてにプレフィックスとしてアンダースコア(_)がつけられます。 それぞれのアクションはこのセクションで説明するオプションでカスタマイズできます。 同じオプションはlisteditもしくはnewエントリでアクションを定義する際に使うことができます。

name

デフォルト: アクションのキー

nameオプションはアクションに使うラベルを定義します。

action

デフォルト: アクションの名前に基づいて定義されます。

actionオプションはプレフィックスのexecuteなしで実行するアクションの名前を定義します。

credentials

デフォルト: なし

credentialsオプションは表示するアクションに対してユーザーが持たなければならないクレデンシャルを定義します。

note

クレデンシャルはsecurity.yml設定ファイルと同じルールで定義されます。

list

title

デフォルト: サフィックスの"List"がつけられた人間にわかりやすいモデルクラスの名前

titleオプションはlistページのタイトルを定義します。

display

デフォルト: すべてのモデルのカラム、スキーマファイルでの定義順

displayオプションはlistで表示する順序つきカラムの配列を定義します。

カラム前の等号(=)は文字列を現在のオブジェクトのeditページに向かうリンクに変換する規約です。

config:
  list:
    display: [=name, slug]

note

カラムを隠すhideオプションもご覧ください。

hide

デフォルト: なし

hideオプションはlistから隠すカラムを定義します。 カラムを隠すのにdisplayオプションで表示されるカラムを指定するよりも、こちらの方が速いことがあります:

config:
  list:
    hide: [created_at, updated_at]

note

displayhideオプションが両方とも提供される場合、hideオプションが無視されます。

layout

デフォルト: tabular

可能な値: tabularもしくはstacked

layoutオプションはlistを表示するのに使うレイアウトを定義します。

tabularレイアウトでは、それぞれのカラムの値は独自テーブルのカラムにあります。

stackedレイアウトでは、それぞれのオブジェクトはparamsオプション(下記を参照)で定義される単独文字列で表現されます。

note

stackedレイアウトを使う際にもdisplayオプションは必要です。 このオプションはユーザーによってソート可能になるカラムを定義するからです。

params

デフォルト値: なし

paramsオプションはstackedレイアウトを使用する際に使うHTML文字列のパターンを定義するために使われます。 この文字列はモデルオブジェクトプレースホルダーを含むことができます:

config:
  list:
    params:  |
      %%title%% written by %%author%% and published on %%published_at%%.

カラムの前の等号(=)は文字列を現在のオブジェクトのeditページに向かうリンクに変換する規約です。

sort

デフォルト値: なし

sortオプションはデフォルトのsortカラムを定義します。 これは2つのコンポーネントから構成されます: カラムの名前とソートの順序: ascもしくはdesc:

config:
  list:
    sort: [published_at, desc]

max_per_page

デフォルト値: 20

max_per_pageオプションは1つのページを表示するオブジェクトの最大数を定義します。

pager_class

デフォルト値: PropelではsfPropelPager、DoctrineではsfDoctrinePager

pager_classオプションはlistを表示する際に使用するページャークラスを定義します。

batch_actions

デフォルト値: { _delete: ~ }

batch_actionsオプションはlistのオブジェクト選択用に実行できるアクションのリストを定義します。

actionを定義しない場合、adminジェネレーターはプレフィックスがexecuteBatchであるキャメルケース版の名前のメソッドを探します。

実行されるメソッドはidsリクエストパラメーターを通して選択されたオブジェクトの主キーを受け取ります。

tip

バッチアクションの機能はオプションを空の配列: {}にセットすることで無効にできます。

object_actions

デフォルト値: { _edit: ~, _delete: ~ }

object_actionsオプションはlistのそれぞれのオブジェクトで実行可能なアクションのリストを定義します。

actionを定義しない場合、adminジェネレーターはプレフィックスがexecuteListであるキャメルケース版の名前のメソッドを探します。

tip

オブジェクトアクションの機能はオプションを空の配列: {}にセットすることで無効にできます。

actions

デフォルト値: { _new: ~ }

新しいオブジェクトの作成のように、actionsオプションはオブジェクトを受け取らないアクションを定義します。

actionを定義しない場合、adminジェネレーターは`executeListをプレフィックスとするキャメルケースの名前のメソッドを探します。

tip

オブジェクトアクション機能はオプションを空の配列: {}にセットすることで無効にできます。

peer_method

デフォルト値: doSelect

peer_methodオプションはlistで表示するオブジェクトを読み取るために呼び出すメソッドを定義します。

caution

このオプションはPropelに対してのみ存在します。 Doctrineに対しては、table_methodオプションを使います。

table_method

デフォルト値: doSelect

table_methodオプションはlistで表示するオブジェクトを読み取るために呼び出すメソッドを定義します。

caution

このオプションはDoctrineに対してのみ存在します。 Propelに対しては、peer_methodオプションを使います。

peer_count_method

デフォルト値: doCount

peer_count_methodオプションは現在のフィルター用のオブジェクトの個数を算出するために呼び出すメソッドを定義します。

caution

このオプションはPropelに対してのみ存在します。 Doctrineに対しては、table_count_methodオプションを使います。

table_count_method

デフォルト値: doCount

table_count_methodオプションは現在のフィルター用のオブジェクトの個数を算出するために呼び出すメソッドを定義します。

caution

このオプションはDoctrineに対してのみ存在します。 Propelに対しては、peer_count_methodオプションを使います。

filter

filterセクションはlistページに表示されるフォームをフィルタリングするためのコンフィギュレーションを定義します。

display

デフォルト値: 定義の順序で、フィルターフォームクラスで定義されたすべてのフィールド。

displayオプションは表示するフィールドの順序つきリストを定義します。

tip

フィルターフィールドは常にオプションで、表示するフィールドを設定するためにフィルターフォームクラスをオーバーライドする必要はありません。

class

デフォルト値: サフィックスがFormFilterであるモデルクラスの名前

classオプションはfilterフォームに使うフォームクラスを定義します。

tip

フィルタリング機能を完全に除外するには、classfalseにセットします。

form

formセクションはeditnewセクションのためのフォールバックとしてのみ存在します(最初の継承ルールを参照)。

note

フォームセクション(formeditnew)に関して、labelhelpオプションはフォームクラスで定義されたものをオーバーライドします。

display

デフォルト値: フォームクラスで定義されるすべてのクラス。順序は定義された順序と同じ。

displayオプションは表示するフィールドの順序つきリストを定義します。

このオプションはフィールドをグループに分類するためにも使うことができます:

# apps/backend/modules/job/config/generator.yml
config:
  form:
    display:
      Content: [title, body, author]
      Admin:   [is_published, expires_at]

上記のコンフィギュレーションは2つのグループ(ContentAdmin)を定義します。 それぞれがフォームフィールドのサブセットを含みます。

caution

モデルフォームで定義されるすべてのフィールドはdisplayオプションに存在しなければなりません。 そうではない場合、予期しないバリデーションエラーになる可能性があります。

class

デフォルト値: サフィックスがFormであるモデルクラスの名前

classオプションはeditnewページに使うフォームクラスを定義します。

tip

neweditセクションの両方でclassオプションを定義できますが、1つのクラスと条件ロジックを使い違いを考慮するほうがよいです。

edit

editセクションはformセクションと同じオプションを受け取ります。

title

デフォルト: サフィックスが"Edit"である人間にわかりやすいモデルクラスの名前

titleオプションはeditページのタイトルの見出しを定義します。 これはモデルオブジェクトのプレースホルダーを格納できます。

actions

デフォルト値: { _delete: ~, _list: ~, _save: ~ }

actionsオプションはフォームを投稿する際に利用可能なアクションを定義します。

new

newセクションはformセクションと同じオプションを受け取ります。

title

デフォルト: サフィックスが"New"である人間にわかりやすいモデルクラスの名前

titleオプションは新しいページのタイトルを定義します。 これはモデルオブジェクトのプレースホルダーを格納できます。

tip

オブジェクトが新しい場合でも、タイトルの一部として出力したいデフォルトの値を格納できます。

actions

デフォルト値: { _delete: ~, _list: ~, _save: ~, _save_and_add: ~ }

actionsオプションはフォームを投稿する際に利用可能なアクションを定義します。