Symfony Doctrineのライフサイクルイベントを完全ガイド！初心者でもわかるPrePersistの使い方

Doctrineのライフサイクルイベント（PrePersistなど）を使う方法

先生と生徒の会話形式で理解しよう

生徒

「Symfonyでデータベースに保存するときに、作成日時や更新日時を自動で入れる方法はありますか？毎回自分で入力するのは大変そうです。」

先生

「SymfonyではDoctrine ORMという仕組みを使ってデータベースとやり取りしますが、そのDoctrineにはライフサイクルイベントという便利な機能があります。PrePersistというイベントを使えば、保存前に自動で値をセットできますよ。」

生徒

「ライフサイクルイベントやPrePersistって名前が難しそうですが、初心者でも理解できますか？」

先生

「大丈夫です。紙の書類にハンコを押すイメージで考えると、とても分かりやすくなります。SymfonyとDoctrineの基本から、PrePersistを使った自動処理まで、ゆっくり解説していきましょう。」

1. SymfonyとDoctrine ORM、ライフサイクルイベントの全体像

まずは、SymfonyとDoctrine ORMの関係を簡単に整理してから、ライフサイクルイベントという機能のイメージをつかんでいきましょう。SymfonyはPHPで作られたフレームワークで、大きなWebアプリケーションを作りやすくしてくれる土台のような存在です。そしてDoctrine ORMは、Symfonyでデータベースにアクセスするときによく使われるライブラリで、テーブルやカラムをPHPのクラスやプロパティとして扱えるようにしてくれます。

初心者の方は「データベース」と聞くと難しく感じるかもしれませんが、イメージとしては、たくさんの表（テーブル）が並んだ大きな表計算のようなものだと思ってください。Doctrine ORMは、その表計算の一行を「エンティティ」というPHPクラスのインスタンスとして扱えるようにしてくれます。SymfonyとDoctrineを組み合わせることで、SQLという専門的な言語を直接書かなくても、オブジェクト指向の書き方でデータを保存したり取得したりできるようになります。

ここで出てくる「ライフサイクルイベント」とは、エンティティが「保存される直前」「更新される直前」など、あるタイミングに自動的に呼び出される仕組みのことです。人間の生活にたとえると、朝起きる前に必ず目覚まし時計が鳴る、家を出る前に自動で電気が消える、といった「決まったタイミングで自動で起こる処理」のイメージです。Doctrineのライフサイクルイベントの中でも、PrePersistというイベントは「新しく保存する前に実行される」タイミングを扱います。

2. PrePersistとは？紙の書類にハンコを押すイメージで理解しよう

Doctrine ORMのPrePersistイベントは、「エンティティをデータベースに初めて保存する直前」に自動で呼び出される処理です。初心者の方にも分かりやすいように、日常生活の例で考えてみましょう。会社で紙の申請書を提出するとき、総務の人が「受付日」のハンコをポンと押してから書類をファイルに閉じることがあります。このとき、わざわざ申請者が日付を書く必要はなく、受付する担当者が決まったルールで日付をつけてくれます。

PrePersistは、まさにこの「受付日ハンコ」と同じイメージです。Symfonyのエンティティを新規保存するときに、開発者が毎回「作成日時」や「作成者」を手でセットしなくても、DoctrineのライフサイクルイベントであるPrePersistを使えば、自動で値を入れてくれます。これにより、Symfonyのアプリケーションで同じような処理を毎回書かずに済み、ミスも減らせます。

PrePersistという言葉自体は少しカタカナが多くて難しく感じますが、「Pre」は「前」、「Persist」は「永続化＝保存する」という意味です。つまりPrePersistは「保存する前」というタイミングを表しています。用語の意味を知っておくと、SymfonyやDoctrineの公式ドキュメントを読むときも理解しやすくなります。

3. SymfonyのエンティティでPrePersistを使う基本的な流れ

次に、SymfonyとDoctrine ORMでPrePersistを使うときの基本的な流れをイメージでつかんでみましょう。細かいコードの書き方よりも、まずは「何をどこに書くのか」を理解することが大切です。Symfonyでは、データベースの一行に相当する「エンティティクラス」を作成し、その中にプロパティ（カラムに対応する項目）を定義します。例えば記事のタイトル、本文、作成日時、更新日時などをプロパティとして持つクラスを考えます。

Doctrineのライフサイクルイベントを使う場合、このエンティティクラスの中に「保存の前に実行してほしいメソッド」を用意し、そのメソッドにPrePersistというアノテーションや属性を付けます。するとDoctrineは、Symfonyのアプリケーションからエンティティを保存するときに、そのメソッドを自動的に呼び出してくれます。このメソッドの中で作成日時を現在の日時に設定したり、まだ値が入っていないフラグを初期化したりといった処理を書きます。

イメージとしては、エンティティクラスの中に「保存前チェック担当」のメソッドを一つ作り、「このメソッドは保存の前に必ず呼び出してね」とDoctrineにお願いしておく感じです。Symfonyで複数の画面やフォームから同じエンティティを保存するときでも、PrePersistを使えば共通の処理を一箇所にまとめられるので、後から修正するときも楽になります。

4. PrePersistで作成日時を自動セットするサンプル

ここでは、SymfonyとDoctrine ORMでよく使われる「作成日時を自動で入れる」例を見ていきましょう。初心者の方は、コードの細かい書き方を全部覚えようとする必要はありません。まずは「エンティティに日時の項目があり、PrePersistでその値を入れている」という流れだけ理解できれば十分です。Symfonyのプロジェクトで、記事やユーザーなどのエンティティを作成したときに、createdAtという作成日時を自動でセットするケースはとても多く、実用性も高いです。

以下は、DoctrineのライフサイクルイベントであるPrePersistを使って、エンティティの作成日時プロパティを自動で設定するイメージのPHPコードです。


<?php

namespace App\Entity;

use Doctrine\ORM\Mapping as ORM;

#[ORM\Entity]
#[ORM\HasLifecycleCallbacks]
class Article
{
    #[ORM\Id]
    #[ORM\GeneratedValue]
    #[ORM\Column]
    private ?int $id = null;

    #[ORM\Column(length: 255)]
    private ?string $title = null;

    #[ORM\Column(type: 'datetime_immutable')]
    private ?\DateTimeImmutable $createdAt = null;

    #[ORM\PrePersist]
    public function setCreatedAtValue(): void
    {
        if ($this->createdAt === null) {
            $this->createdAt = new \DateTimeImmutable();
        }
    }
}

このサンプルでは、ArticleというエンティティクラスにcreatedAtというプロパティを用意し、PrePersistのライフサイクルイベントでsetCreatedAtValueメソッドを呼び出しています。Symfony側で新しいArticleを保存するとき、開発者が作成日時を意識していなくても、Doctrine ORMが保存前にこのメソッドを動かしてくれます。もしまだ作成日時が空であれば、現在の日時を自動でセットしてくれる仕組みです。

このようにPrePersistを使うと、Symfonyのアプリケーション全体で一貫したルールを保ちながら、作成日時や初期フラグを自動で設定できるので、現場でもよく使われるパターンです。コードの意味がまだぼんやりしていても、「新規保存の直前に自動で日時を入れてくれる仕組み」と覚えておけば十分です。

5. PreUpdateや他のDoctrineライフサイクルイベントとの違い

Doctrine ORMのライフサイクルイベントは、PrePersistだけではありません。Symfonyで実際の開発をしていると、データの更新や削除のタイミングでも自動処理を行いたくなる場面がよくあります。代表的なものとして、PreUpdate、PreRemove、PostPersistなどがありますが、ここでは初心者向けに、PrePersistとの違いが分かる程度に絞って説明します。

PreUpdateは「既に保存されているエンティティが更新される直前」に呼び出されるイベントです。例えば、記事を編集したときにupdatedAtという更新日時を自動で変更したい場合、PreUpdateのライフサイクルイベントを使うと便利です。イメージとしては、PrePersistが「初回登録の前のハンコ」、PreUpdateが「編集し直したときの上書きハンコ」という違いになります。どちらもSymfonyとDoctrineの連携の中で自動で呼び出されるので、アプリケーションのあちこちに同じコードを書かずに済みます。

また、PreRemoveはエンティティを削除する前に呼ばれるイベントで、削除ログを残したり、関連データのチェックを行いたい場合に使われます。PostPersistは保存が完了した後に呼ばれるイベントで、通知の送信や履歴の記録など、保存後に行いたい処理をまとめることができます。ただし、初心者の段階では、まずPrePersistをしっかり理解してから、必要に応じて他のイベントに広げていくと混乱が少なくなります。

6. Doctrineライフサイクルイベントを使うときの注意点と設計の考え方

SymfonyとDoctrine ORMのライフサイクルイベントは非常に便利ですが、何でもかんでもPrePersistなどに詰め込みすぎると、逆に分かりにくいエンティティになってしまいます。初心者のうちは、ライフサイクルイベントには「保存や更新のタイミングにぴったり合う共通処理だけを書く」と意識しておくと良いでしょう。例えば、作成日時や更新日時の自動設定、初期状態のフラグ、削除前の簡単なチェックなどは、ライフサイクルイベントとの相性が良い処理です。

一方で、外部サービスへの通知や複雑なビジネスルールなどをPrePersistに直接書いてしまうと、Symfonyのエンティティクラスが重くなり、どこで何が起きているのか分かりにくくなります。こうした処理は、専用のサービスクラスに分けるなど、設計を工夫した方が読みやすくなります。ライフサイクルイベントはあくまで「トリガー（きっかけ）」であり、実際の処理は別のクラスに委ねる形にすると、Symfonyアプリケーション全体の見通しがよくなります。

また、Doctrineのライフサイクルイベントを使うときは、テストのしやすさも意識しておきましょう。PrePersistやPreUpdateの中でどのような値が設定されるのかを確認したい場合、Symfonyのテスト環境でエンティティを保存し、実際にcreatedAtやupdatedAtの値をチェックするなど、挙動を確かめながら進めると安心です。最初は小さなエンティティで試し、動作イメージをつかんでから実際の本番用コードに取り入れると、Doctrine ORMの理解も深まりやすくなります。

このように、SymfonyのDoctrine ORMにおけるライフサイクルイベント、とくにPrePersistを理解しておくと、データベースに保存する処理を自動化できるだけでなく、アプリケーション全体のルールを統一しやすくなります。初心者の方でも、紙の書類に日付のハンコを押すイメージで考えれば、PrePersistの役割やメリットをイメージしやすくなりますので、少しずつコードを試しながら慣れていきましょう。