CakePHPでループ中にsaveする — 2.xの常識は3以降で通用しない

公開 2026-10-25 ／ 更新 2026-10-25 ／ 文：ランツ

foreach の中で save() を呼ぶ。よくある処理ですが、CakePHPはバージョンで作法が完全に変わりました。

2.x では「create() を呼ばないと1件目が上書きされ続ける」という有名な罠がありました。 3.x 以降はORMが作り直されたのでこの罠は消えています。 代わりに別の落とし穴ができました。

saveMany() はアトミックではありません。 公式ドキュメントにそう書いてあります。これを知らずに使うと、途中で失敗したときに中途半端なデータが残ります。

先に結論

2.x で何が起きていたか

当時のモデルは状態を持っていました。$this->Model->save() を続けて呼ぶと、 2回目以降は1回目に保存したレコードのIDが残ったままになり、 新規登録のつもりが同じ行のUPDATEになるという挙動でした。

2.x でよく見た書き方

foreach ($rows as $row) {
    $this->Post->create();        // ← これが無いと上書きされる
    $this->Post->save($row);
}

3.x 以降はどう書くか

Entityを毎回作る

ループのたびに新しいEntityを作る。これだけです。

1件ずつ保存する

$posts = $this->fetchTable('Posts');

foreach ($rows as $row) {
    $post = $posts->newEntity($row);   // 毎回あたらしく作る
    $posts->save($post);
}

saveMany でまとめる

件数が多いなら、1件ずつ save() するより saveMany() です。

まとめて保存する

$posts = $this->fetchTable('Posts');

// 配列からEntityをまとめて作る
$entities = $posts->newEntities($rows);

$result = $posts->saveMany($entities);

公式の説明はこうです。

saveMany はアトミックではない

ここが一番の落とし穴です。 名前からして「まとめて1回で保存する」ように読めますが、中身は違います。

公式の記載

「個別のトランザクションが走る」——つまり1件ごとにコミットされます。

途中で失敗すると何が残るか

transactional() で囲む

公式が案内しているのが transactional() です。

全部成功か、全部失敗か

$posts = $this->fetchTable('Posts');
$entities = $posts->newEntities($rows);

$ok = $posts->getConnection()->transactional(function () use ($posts, $entities) {
    foreach ($entities as $entity) {
        if (!$posts->save($entity, ['atomic' => false])) {
            return false;        // ← false を返すとロールバックされる
        }
    }
    return true;
});

if (!$ok) {
    // 1件も保存されていない状態
}

戻り値とエラーの取り方

save() の戻り値は公式にこう書かれています。

失敗の理由を取る

if (!$posts->save($post)) {
    // どの項目がどう失敗したかはEntityが持っている
    $errors = $post->getErrors();
    // 例: ['title' => ['_empty' => 'タイトルは必須です']]
}

そもそもループで保存する前に

ループの中でDBを触る処理は、件数が増えると必ず遅くなります。 保存の前に、読み込み側も見ておいてください。

CakePHPの公式ドキュメント（エンティティー）にも、こう書かれています。

2.x から移行するときの対応表

古いコードを引き継いだときに、まず当たるところをまとめます。

AIでやるなら

CakePHPはバージョン間でAPIが大きく変わっているので、 AIに聞くと2.xと3.x以降が混ざった回答が返ってきやすい領域です。

バージョンを固定して聞く

プロンプト

CakePHP 5 で、配列から複数レコードをまとめて保存する処理を書いてください。

【環境】
- CakePHP 5
- 「全件成功するか、1件も保存されないか」が要件

【必ず守ること】
- saveMany() はエンティティーごとに個別トランザクションが走るので、
  それだけでは要件を満たさない。transactional() で囲むこと
- Entity はループのたびに新しく作る（使い回さない）
- 失敗したエンティティーの getErrors() をログに出す

【書かないでほしいこと】
- CakePHP 2.x の書き方（create()、saveAll()、loadModel()）

最後に、この処理が件数10万件になったときの問題点を挙げてください。

出てきたコードの検証

動かす前にわざと失敗させてください。

よくある質問

ループの中で save() を呼んでも大丈夫ですか

動きます。ただし1件ごとに個別のトランザクションが走るので、件数が増えると遅くなります。また途中で失敗したときにそこまでの分が残ります。「全部か、ゼロか」が要件なら transactional() で囲んでください。

2.x の create() に相当するものは何ですか

ありません。3.x でORMが作り直され、状態がEntityに移ったためです。代わりにループのたびに newEntity() で新しいEntityを作ってください。

2回目以降がUPDATEになってしまいます

Entityを使い回していませんか。Entityは主キーを保持しているので、同じEntityに patchEntity() で値を入れ替えながら保存すると、そのIDに対するUPDATEになります。毎回 newEntity() で作り直してください。

saveMany() を使えばトランザクションは勝手に効きますか

効きません。公式に「すべてのエンティティーの保存で個別のトランザクションが走ります」と書かれています。単一のトランザクションにしたいなら transactional() を使ってください。

save() が false を返しますが理由が分かりません

Entityが持っています。$entity->getErrors() でバリデーションエラーが取れます。save() の戻り値は成功時に変更されたエンティティー、失敗時に false です。

saveAll() はどこへ行きましたか

3.x 以降は saveMany() です。名前が似ていますがトランザクションの挙動を必ず確認してください。機械的に置き換えると、本番で「途中まで入った」事故になります。

10万件を入れたいのですが遅いです

ORMは大量データの投入に最適化された道具ではありません。Entityの生成とバリデーションが1件ごとにかかります。速さが要件なら、素のSQLで一括INSERTするほうが桁違いに速いことがあります。分割処理とあわせて検討してください。

CakePHP 2.x のまま使い続けても大丈夫ですか

2.x はEOLです。新規では使わないでください。既存のコードを引き継いだ場合は、対応表を見ながら移行を検討してください。

まとめ

CakePHP 2.x の罠は消えました。いまの罠は別のところにあります。

1. create() は要らなくなった。
   3.x 以降は状態がEntityに移ったので、ループのたびに newEntity() で作り直すだけです。 ただしEntityを使い回すと同じ事故が起きます。
2. saveMany() はアトミックではない。
   公式に「すべてのエンティティーの保存で個別のトランザクションが走ります」とあります。 100件中50件目で失敗したら、49件は残ります。
3. 「全部か、ゼロか」が要件なら transactional() で囲む。
   コールバックが false を返せばロールバック、例外ならロールバックして再スローです。

フレームワークのメジャーバージョンが変わったときは、 「動くかどうか」だけでなく「同じ意味のままか」を確認してください。 saveAll() と saveMany() は、名前は似ていても保証している範囲が違います。