📘

Symfonyのバリデーション機能を学ぶ - 基本から条件付きバリデーションまで

に公開
2026/03/05

経緯

業務でSymfonyベースのWebアプリケーションを開発していて、フロントエンドからバックエンドまで担当することが増えてきた。現在のプロダクトは長期間Symfonyを使っているが、Symfonyのバリデーション機能が安定する以前から存在するため、バックエンド側のバリデーションは普通のPHPで実装されている。
そこで、既存の実装をSymfonyのValidatorコンポーネントに置き換えることにメリットがあるのか、実際に検証してみることにした。

Symfonyのバリデーションの仕組み

Symfonyでは、Validatorコンポーネントと制約(Constraints)を使用してバリデーションを実装する。公式ドキュメントでは、エンティティにAttribute、YAML、XMLで制約を定義し、$validator->validate()で検証する方法が紹介されている。
本記事では、以下の2つのパターンでバリデーションを試してみる。

パターン1: エンティティと関連付ける場合

Attribute、YAML、XMLで制約を定義し、エンティティにデータをセットしてから検証する。

// エンティティに制約を定義
#[Assert\NotBlank]
#[Assert\Length(min: 3, max: 20)]
private $username;

// 使用時
$user = new User();
$user->setUsername($data['username']);
$errors = $validator->validate($user);

パターン2: バリデーション専用クラスを使う場合

公式ドキュメントには明示されていないが、エンティティと関連付けずに、フォーム入力専用のバリデーションクラスを作成することもできる。

class UserFormValidator
{
    #[Assert\NotBlank]
    public $username;

    #[Assert\Callback]
    public function validate(ExecutionContextInterface $context): void
    {
        // カスタムロジック
    }
}

// 使用時
$formValidator = new UserFormValidator($data);
$errors = $validator->validate($formValidator);

基本的な検証方法

上記で取り上げた2つのパターンを実際に試してみる。

パターン1: エンティティと関連付ける場合

src/Entity/User.php
<?php
namespace App\Entity;

use App\Repository\UserRepository;
use Doctrine\ORM\Mapping as ORM;
use Symfony\Component\Validator\Constraints as Assert;

#[ORM\Entity(repositoryClass: UserRepository::class)]
class User
{
    #[ORM\Id]
    #[ORM\GeneratedValue]
    #[ORM\Column]
    private ?int $id = null;

    #[ORM\Column(length: 255)]
    #[Assert\NotBlank(message: "ユーザー名は必須です")]
    #[Assert\Length(min: 3, max: 20)]
    private ?string $username = null;

    public function getId(): ?int
    {
        return $this->id;
    }

    public function getUsername(): ?string
    {
        return $this->username;
    }

    public function setUsername(string $username): static
    {
        $this->username = $username;
        return $this;
    }
}

コントローラー例:

<?php
namespace App\Controller;

use App\Entity\User;
use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\Routing\Attribute\Route;
use Symfony\Component\Validator\Validator\ValidatorInterface;

class ValidationTestController extends AbstractController
{
    #[Route('/validation/entity', name: 'app_validation_entity')]
    public function entity(Request $request, ValidatorInterface $validator): Response
    {
        $data = [];
        $errors = [];

        if ($request->isMethod('POST')) {
            $data = $request->request->all();

            $user = new User();
            $user->setUsername($request->request->get('username'));

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

        return $this->render('validation_test/index.html.twig', [
            'errors' => $errors,
            'data' => $data,
        ]);
    }
}

YAMLで定義

エンティティに制約を記述する代わりにYAMLファイルで定義する。

config/validator/validation.yaml
App\Entity\User:
  properties:
    username:
      - NotBlank:
          message: "ユーザー名は必須です"
      - Length:
          min: 3
          max: 20
          minMessage: "ユーザー名は3文字以上で入力してください"
          maxMessage: "ユーザー名は20文字以内で入力してください"

コントローラーのコードは全く同じ。YAMLに制約を定義した場合、エンティティのAttributeは不要になる。

バリデーション専用クラス

エンティティと関連付けずに、フォーム入力専用のバリデーションクラスを作成する方法。

src/Validator/UserFormValidator.php
<?php
namespace App\Validator;

use Symfony\Component\Validator\Constraints as Assert;
use Symfony\Component\Validator\Context\ExecutionContextInterface;

class UserFormValidator
{
    #[Assert\NotBlank(message: "ユーザー名は必須です")]
    #[Assert\Length(min: 3, max: 20)]
    public $username;

    #[Assert\NotBlank(message: "パスワードは必須です")]
    #[Assert\Length(min: 8)]
    public $password;

    public function __construct(array $data)
    {
        $this->username = $data['username'] ?? null;
        $this->password = $data['password'] ?? null;
    }

    #[Assert\Callback]
    public function validate(ExecutionContextInterface $context, $payload): void
    {
        // パスワードとユーザー名が一致しないことをチェック
        if ($this->username === $this->password) {
            $context->buildViolation('パスワードはユーザー名と異なる必要があります')
                ->atPath('password')
                ->addViolation();
        }
    }
}

コントローラーでの使用:

public function index(Request $request, ValidatorInterface $validator): Response
{
    $data = [];
    $errors = [];

    if ($request->isMethod('POST')) {
        $data = $request->request->all();
        $formValidator = new UserFormValidator($data);
        $errors = $validator->validate($formValidator);
    }

    return $this->render('validation_test/index.html.twig', [
        'errors' => $errors,
        'data' => $data,
    ]);
}

Callbackの基本的な書き方

#[Assert\Callback]
public function validate(ExecutionContextInterface $context, $payload): void
{
    // 条件チェック
    if (/* バリデーション失敗条件 */) {
        $context->buildViolation('エラーメッセージ')
            ->atPath('フィールド名')
            ->addViolation();
    }
}

メリット

  • 複数のエンティティを一度にチェックできる
  • エンティティに影響を与えない
  • 新規画面を作成し、その画面だけに特有のバリデーション制約を設けたい場合に便利

バリデーショングループ

同じエンティティで、状況によって異なるバリデーションルールを適用したい場合に使用。

Attributeでの定義

src/Entity/User.php
<?php
namespace App\Entity;

use Doctrine\ORM\Mapping as ORM;
use Symfony\Component\Validator\Constraints as Assert;

#[ORM\Entity]
class User
{
    #[Assert\NotBlank(message: "ユーザー名は必須です", groups: ["create", "edit"])]
    #[Assert\Length(min: 3, max: 20, groups: ["create", "edit"])]
    private $username;

    #[Assert\NotBlank(message: "パスワードは必須です", groups: ["create"])]
    #[Assert\Length(min: 8, groups: ["create", "password_change"])]
    private $password;

    // ゲッター、セッター省略
}

コントローラーでの使用:

// 新規作成時:パスワード必須
$user = new User();
$user->setUsername($data['username']);
$user->setPassword($data['password']);
$violations = $validator->validate($user, null, ['create']);

// 編集時:パスワードは空なら変更しない
$user = $userRepository->find($id);
$user->setUsername($data['username']);

if (!empty($data['password'])) {
    $user->setPassword($data['password']);
    $violations = $validator->validate($user, null, ['edit', 'password_change']);
} else {
    $violations = $validator->validate($user, null, ['edit']);
}

YAMLでの定義

config/validator/validation.yaml
App\Entity\User:
  properties:
    username:
      - NotBlank:
          message: "ユーザー名は必須です"
          groups: [create, edit]
      - Length:
          min: 3
          max: 20
          groups: [create, edit]
    password:
      - NotBlank:
          message: "パスワードは必須です"
          groups: [create]
      - Length:
          min: 8
          groups: [create, password_change]
グループ 説明
create 新規作成時のバリデーション
edit 編集時のバリデーション
password_change パスワード変更時のバリデーション

考察

今回、Validatorコンポーネントについて学んだが、現在のプロダクトへの導入については慎重に検討すべきだという考えになった。私の一存では決められないが、現時点では以下の理由から導入は見送りたい。
残念だけど。。。

導入を見送る理由

費用対効果の疑問

これが一番の理由。 会社がチーム全員分の学習コストを払ってまで、バグの低減や工数削減につながるイメージが持てなかった。既に既存のバリデーション実装で十分に動いてるし、開発はAIを利用していることもあって、これに置き換えたからといって開発速度が劇的に上がるのかな?と思った。

学習コストと既存資産

既存実装とSymfonyのValidatorで、2つの方式が混在することになるのが一番の懸念。特に新メンバーが参画したときなど、どちらの方式で書くべきか迷わせる原因になりそうで、それがマイナスに作用する気がしている。

バグ増加のリスク

中途半端に両方を使うことで、例えばYAMLに定義があるのを見落として、EntityとYAMLの両方に制約を書いてしまうような事態が起きないかな。。。コードレビューで防げればいいが、当然見落としは発生する。そうなると、どちらの定義が優先されているのか、なぜ重複しているのかといった「意図が不明なコード」が増えるリスクがある。
これはただ想像して書いただけだけど、両方を採用したが故のバグが発生しそう。

使えるかもしれない場面

バリデーション専用クラスであれば、限定的な場面では有用かもしれない。

  • 複数のエンティティをまたいだバリデーションが必要な新規画面を作る場合
  • エンティティに影響を与えずに、画面固有のバリデーションを実装したい場合

検証環境

  • Symfony 8.0.3
  • PHP 8.4.16

参考資料

Discussion