エラーのテンプレートをカスタマイズする方法

エラーが起きるとき、ページが見つからないエラーであれ、サーバーの内部エラー、もしくはその他の例外であれ、symfonyはエラーページを表示します。ページの内容は環境とリクエストの形式によります。

説明をわかりやすくするために、ArticleモジュールのHTML、XML、もしくはJSON形式の表現を返すAPIモジュールを持つアプリケーションがある場合を考えてみましょう。

これを機能させるルーティングの構成は次の通りです:

// apps/frontend/config/routing.yml
api_article:
  url:   /api/article/:id.:sf_format
  param: { module: api, action: article }
  requirements:
    sf_format: (?:html|xml|json)

関連モジュールは次の通りです:

class apiActions extends sfActions
{
  public function executeArticle($request)
  {
    $this->article = ArticlePeer::retrieveByPK($request->getParameter('id'));

    $this->forward404Unless($this->article);
  }

  // ...
}

存在しないidをリクエストに渡すと、アクションは404ページに転送されます。開発環境の中でHTMLフォーマット (http://localhost/frontend_dev.php/api/article/1.html)を使う場合、次のようなエラーメッセージが表示されます:

本番環境(http://localhost/frontend_dev.php/api/article/1.html)において、明らかなセキュリティ上の理由からページは大きく異なります:

では、開発環境でフォーマットをXML(http://localhost/frontend_dev.php/api/article/1.xml)に変更するときにこれがどのように振る舞うのか見てみましょう:

次に、本番環境(http://localhost/api/article/1.xml)です:

ご自分で確認できるように、symfonyに返されたエラーメッセージはリクエストされたXML形式です。

この例は404ページのためにエラーメッセージをカスタマイズするお手本を示しましたが、他の捕捉されない例外に対しても同じことが当てはまります。

テンプレートをプロジェクトのディレクトリ(config/error/)もしくはアプリケーションのディレクトリ(apps/frontend/config/error/)に追加することでそれぞれのフォーマットの出力をカスタマイズすることもできます。

例えば、XML形式のエラーメッセージのための出力をカスタマイズするためには、config/error/error.xml.phpファイルを作ります。 symfonyはカスタマイズされたテンプレートが存在すればデフォルトの代わりに使うぐらい賢いです:

<?xml version="1.0" encoding="<?php echo sfConfig::get('sf_charset', 'UTF-8') ?>"?>
<error>
   <code><?php echo $code ?></code>
   <message><?php echo $text ?></message>
</error>

エラーメッセージのテンプレートをカスタマイズするとき、次の変数にアクセスできます:

• $code: レスポンス状態のコード
• $text: レスポンス状態のテキスト
• $name: 例外のクラスの名前
• $message: 例外メッセージのメッセージ
• $traces: PHPトレースすべてを含む配列
• $format: リクエストされたフォーマット

あまり面白くない出力だとしても、config/error/exception.xml.phpを作ることで、開発環境での出力をカスタマイズすることも可能です。

デフォルトのテンプレートはsymfonyのlib/exception/data/ディレクトリに保存されておりこれはテンプレートをカスタマイズするための良い始点です。

あなただけの独自フォーマットを作るとき、適切なエラーメッセージのテンプレートを作ることが必要になります(config/error/error.FORMAT_NAME.phpとconfig/error/exception.FORMAT_NAME.php)

タスクを簡単にするために、既存のエラーテンプレートを格納できます。例えば、フォーマットがXMLのようなものである場合、デフォルトのXMLエラーメッセージのテンプレートを格納できます:

<?php include sfException::getTemplatePathForError('xml', true) ?>

フォーマットのサポートは可能な限りHTTPを受け入れるsymfony 1.2の別の実例でもあります。