Symfonyでバリデーションメッセージをカスタマイズする方法！初心者向けに丁寧に解説

1. バリデーションメッセージとは？

1. バリデーションメッセージとは？

バリデーションメッセージとは、Webサイトのフォームなどでユーザーが入力した内容に不備があった際、システムから通知される「エラー案内」のことです。

例えば、会員登録画面で名前の欄を空のまま送信ボタンを押したとき、入力欄のすぐ下に「この項目は必須です」や「名前を入力してください」といった赤い文字が表示されることがありますよね。これがバリデーションメッセージです。

初心者の方向けに、具体的な表示例を見てみましょう。例えば「年齢」の入力欄に数字以外を入れた場合、以下のようなメッセージが表示されます。

（標準のメッセージ例）
This value is not valid.

（カスタマイズ後のメッセージ例）
年齢は半角数字で入力してください。

このように、システム側の都合ではなく「ユーザーが次に何をすべきか」を日本語で分かりやすく伝えるために、メッセージのカスタマイズは非常に重要な作業なのです。

2. アノテーションでメッセージを変更する

2. アノテーションでメッセージを変更する

Symfonyのバリデーションは、エンティティクラスのプロパティにアノテーションを付けて設定します。

メッセージを変更したい場合は、messageオプションを追加すればOKです。

use Symfony\Component\Validator\Constraints as Assert;

class User
{
    #[Assert\NotBlank(message: '名前を入力してください')]
    private string $name;

    #[Assert\Email(message: '有効なメールアドレスを入力してください')]
    private string $email;
}

ポイント：

• messageの中に好きな日本語を入れればOK
• ユーザーにとって親切な表現にするとよい

3. メッセージに変数を埋め込む

3. メッセージに変数を埋め込む

一部のバリデーションでは、エラーメッセージの中に変数（プレースホルダー）を使うことができます。

たとえば、最大文字数を指定したときに「〇文字以内にしてください」と表示したい場合です。

#[Assert\Length(
    max: 20,
    maxMessage: '名前は{{ limit }}文字以内で入力してください'
)]
private string $name;

このように {{ limit }} を使えば、自動的に設定した数値（ここでは20）が表示されます。

4. 複数のバリデーションでもメッセージを個別に設定できる

4. 複数のバリデーションでもメッセージを個別に設定できる

同じプロパティに複数のバリデーションルールを設定している場合でも、それぞれに別のメッセージを設定できます。

#[Assert\NotBlank(message: 'メールアドレスは必須です')]
#[Assert\Email(message: '正しいメールアドレス形式で入力してください')]
private string $email;

このようにすることで、「空欄かどうか」と「形式が正しいか」を別々にチェックし、それぞれに応じたメッセージを出せます。

5. 翻訳ファイルで一括管理もできる

5. 翻訳ファイルで一括管理もできる

メッセージを大量に使う場合や、多言語対応したい場合は、翻訳ファイルを使って一括でメッセージを管理する方法もあります。

たとえば、Symfonyでは translations/validators.ja.yaml というファイルを作って、日本語でメッセージを定義できます。

# translations/validators.ja.yaml
Symfony:
  This value should not be blank: 'この項目は必須です'
  This value is not a valid email address: '正しいメールアドレスを入力してください'

これにより、エンティティ側ではmessageを書かなくても、自動的に翻訳が適用されます。

6. 自分で作ったメッセージキーを使うこともできる

6. 自分で作ったメッセージキーを使うこともできる

さらに、独自のメッセージキーを作って、翻訳ファイルと連携することもできます。

#[Assert\NotBlank(message: 'user.name.required')]
private string $name;

# translations/validators.ja.yaml
user:
  name:
    required: '名前を入力してください'

このように階層構造で管理すると、メッセージが整理されて分かりやすくなります。

7. 実行結果でエラーメッセージを確認しよう

7. 実行結果でエラーメッセージを確認しよう

バリデーションを実行して、エラーメッセージが表示されるか確認してみましょう。

$errors = $validator->validate($user);

foreach ($errors as $error) {
    echo $error->getMessage();
}

名前を入力してください
正しいメールアドレスを入力してください

このようにカスタマイズした日本語のメッセージが表示されれば成功です。