PHP Array_mergeで連想配列を正しく結合【上書きルールも迷わない】

PHPで配列を扱う場面では、設定値の統合や検索条件の組み立てなど、連想配列を結合したいケースが頻繁にあります。そこでよく使われるのがarray_mergeですが、数値キーと文字列キーで挙動が異なるため、思った結果にならず戸惑う方も少なくありません。
特に連想配列では、同じキーがあると上書きされるのか、追加されるのかを正確に理解しておくことが重要です。
この記事では、PHP Array_merge 連想配列の基本から、よくある失敗、類似関数との違い、実務で安全に使うコツまでを、コード例と比較表を交えて専門的にわかりやすく解説します。

PHP Array_mergeで連想配列を結合するときの基本

PHPのarray_mergeは、複数の配列を1つにまとめるための代表的な関数です。連想配列に使う場合は特に便利ですが、内部ルールを曖昧なまま使うと、期待した値が消えたり、キー構造が変わったりすることがあります。
実務では、設定配列のデフォルト値とユーザー指定値を統合したり、APIへ渡すパラメータを組み立てたりする場面で利用されます。
そのため、単に配列をくっつける関数として覚えるのではなく、キーの種類ごとの動作を正確に把握しておくことが大切です。

まず押さえるべきなのは、array_mergeは元の配列を破壊せず、新しい配列を返すという点です。可読性の高いコードにしやすい一方で、意図せず同じ変数へ再代入し忘れると結果が反映されません。
また、可変長引数で複数配列を順番に受け取り、後ろにある配列ほど優先される設計です。
連想配列を扱うなら、上書き順序とキーの保持ルールを理解することが最初の一歩になります。

array_mergeの基本構文

array_mergeの基本構文は非常にシンプルで、複数の配列を引数として渡すだけです。返り値として結合済みの新しい配列が返されます。
たとえば、デフォルト設定と環境別設定を統合する場合は、後ろの配列に書かれた値が優先されます。これにより、初期値を保ちつつ必要部分だけを差し替える実装がしやすくなります。
一方で、同名キーの扱いを理解していないと、なぜ値が変わったのか分からなくなるため注意が必要です。

コード例は次のとおりです。
$base = ['host' => 'localhost', 'port' => 3306];
$override = ['port' => 3307, 'charset' => 'utf8'];
$result = array_merge($base, $override);
この結果、portは3307に上書きされ、charsetが新たに追加されます。
つまり、連想配列では後から渡した配列の値が優先されると覚えると理解しやすいです。

連想配列で重要なキーの扱い

連想配列で重要なのは、文字列キーと数値キーでarray_mergeの動作が異なる点です。多くの開発者が混乱するのは、配列という同じ見た目でも、キーの型によって結果が変わるからです。
文字列キーは、同じキー名が存在すると後から渡した配列の値で上書きされます。これは設定値の統合には便利ですが、元の値を残したい場合には不向きです。
数値キーは上書きではなく追加扱いになり、結合後に0からの連番へ再割り当てされます。

この挙動は、混在配列で特に注意が必要です。
たとえば、ID一覧のような数値キーの配列と、設定情報のような文字列キーの配列を一緒に扱うと、意図しない構造変化が起こることがあります。
設計段階で、対象が純粋な連想配列なのか、数値添字を含む配列なのかを明確にしておくと安全です。
特に既存コードの保守では、配列の中身だけでなくキー型の確認も重要です。

連想配列での上書きルールと挙動

PHPでarray_mergeを使う際に最も知っておきたいのが、同一キーが存在する場合の上書きルールです。連想配列では、キー名が同じなら後ろの配列の値が採用されます。これはシンプルですが、上書きの意図がコードに表れていないと、保守時に誤解を招きやすいポイントでもあります。
一方、数値キーは結合後に再採番されるため、同じ数字のキーがあっても上書きではありません。
この違いを正しく理解すると、設定配列やオプション配列のマージ処理を安定して書けるようになります。

また、複数配列をまとめて結合する場合は、右側にある配列ほど優先度が高くなります。
したがって、どの配列を先に書くかは単なる記述順ではなく、仕様そのものに直結します。
実務では、デフォルト値、環境設定、ユーザー入力の順で並べることが多く、優先順位を自然に表現できます。
順番の意味を明確にすることが、バグ防止に直結します。

同じ文字列キーがある場合の動作

連想配列で同じ文字列キーがある場合、array_mergeは後から渡した配列の値で上書きします。
たとえば、['mode' => 'dev']と['mode' => 'prod']を結合すると、結果のmodeはprodになります。
このルールは分かりやすい反面、誤って重要な値を消してしまう原因にもなります。特に、複数人開発でキー名の衝突が起きると、原因調査に時間がかかりがちです。

そのため、上書き前提で使うのか、保持前提で使うのかを事前に決めておくことが重要です。
必要であれば、マージ前にarray_key_existsで衝突を検知したり、キー名を名前空間風に整理したりすると安全です。
上書きが仕様として正しいなら、コメントや変数名で意図を示すと可読性が上がります。
単に便利だから使うのではなく、上書きされる前提を設計に組み込むことが大切です。

数値キーが混在するときの注意点

array_mergeでは、数値キーを持つ要素は末尾に追加され、その後キーが0から振り直されます。
これはリストの結合には便利ですが、元のキーに意味がある場合には問題になります。たとえば、IDや優先順位をキーとして使っている配列では、結合後に元の関連性が崩れる可能性があります。
見た目には要素が残っていても、キー情報が失われるため、後続処理で不具合を招くことがあります。

特に注意したいのは、連想配列だと思っていた配列に、実は数値文字列や整数キーが混ざっているケースです。
PHPでは配列キーの型変換も絡むため、意図せず数値キーとして扱われることがあります。
キーを保持したまま結合したい場合は、array_mergeではなく配列結合演算子や、目的に応じた別の関数を検討するべきです。
挙動が曖昧なときは、結合前後でvar_dumpなどを使ってキー構造を確認すると安心です。

array_mergeと配列結合演算子の違い

PHPで配列をまとめる方法はarray_mergeだけではありません。配列結合演算子を使う方法もあり、見た目は似ていても結果は大きく異なります。
array_mergeは後ろの配列を優先して上書きするのに対し、配列結合演算子は左側のキーを優先して保持します。
この違いを理解していないと、値が変わらない、または消えないといった混乱につながります。
目的に応じて使い分けることが、PHPでの配列操作では非常に重要です。

特に連想配列では、どちらを使うかで仕様がまったく変わります。
上書きしたいならarray_merge、既存値を守りたいなら配列結合演算子という考え方が基本です。
また、数値キーの扱いも異なるため、単純に好みで選ぶのではなく、キー構造を含めて判断する必要があります。
チーム開発では、どの方針で結合するかをコーディングルールにしておくと保守性が高まります。

どちらを使うべきかの判断基準

使い分けの基準は明確です。後から渡す値で上書きしたいならarray_merge、最初に定義した値を優先したいなら配列結合演算子が向いています。
たとえば、ユーザー指定値でデフォルト設定を上書きするならarray_mergeが自然です。逆に、既存の設定を保護しながら不足分だけ補いたいなら配列結合演算子が適しています。
この判断を誤ると、仕様と実装が食い違いやすくなります。

また、読み手が一目で意図を理解できるかも重要です。
array_mergeは関数名から結合の意図が伝わりやすく、複数配列を順に統合しやすい利点があります。
一方で、左側優先という動作を簡潔に表現したいときは配列結合演算子が読みやすい場合もあります。
どちらが正しいかではなく、何を優先したいかで選ぶのが適切です。

実務で迷いやすいケース

実務で迷いやすいのは、設定配列の結合と、データ一覧の結合が同じ感覚で扱われてしまうケースです。
設定配列では同名キーの上書きが期待どおりでも、一覧データでは数値キーの再採番が予想外の結果になることがあります。
さらに、配列のネストが深くなると、単純なarray_mergeでは内側の配列ごと置き換わってしまうため注意が必要です。
特に設定ファイルの統合では、この点が落とし穴になります。

また、既存コードで演算子と関数が混在していると、どこで値が上書きされるか追いにくくなります。
そのため、処理の目的ごとに結合方法を統一するのが有効です。
レビュー時には、結果の配列だけでなく、結合方法が仕様に合っているかを見る視点が重要です。
実務では、動けばよいではなく、後から読んでも意図が分かることが品質につながります。

よくある失敗と安全に使うコツ

array_mergeは便利ですが、理解不足のまま使うと、連想配列の値消失やキー崩れの原因になります。
特に、同名キーの上書き、数値キーの再採番、ネスト配列の浅い結合は代表的な注意点です。
こうした特徴は仕様どおりの動作ですが、実装者の想定とずれると不具合に見えてしまいます。
安全に使うには、結合前提のデータ構造を明確にし、必要に応じて事前検証を入れることが有効です。

また、コードの見た目を整えるだけでなく、マージ結果を確認しやすい実装にしておくことも重要です。
配列の役割ごとに変数名を分け、優先順位が伝わる順序で書くと、後から読んだときの理解が早くなります。
加えて、テストでキー衝突時の結果を確認しておくと、仕様変更にも強くなります。
便利な関数ほど、前提を明示して使う姿勢が大切です。

ネストした連想配列を結合するときの考え方

array_mergeは基本的に浅い結合です。つまり、同じキーに配列が入っている場合、内側を細かく統合するのではなく、後ろの配列でそのキー全体が置き換わります。
たとえば、dbというキーの中にhostとportを持つ配列がある場合、後ろの配列でdbの一部だけを変更したつもりでも、前のdb配列全体が消えることがあります。
この動作を知らないと、設定項目の一部が突然なくなったように見えてしまいます。

ネスト配列を扱うなら、必要に応じて再帰的な結合手段を検討するべきです。
ただし、再帰的に結合すれば常に正解というわけではなく、数値キー配列の扱いで期待とずれることもあります。
大切なのは、浅い結合でよいのか、階層単位で保持したいのかを設計で決めることです。
複雑な設定配列では、どの階層までマージ対象にするかを明文化するとトラブルを防げます。

バグを防ぐ実践的なチェックポイント

array_mergeを安全に使うには、実装前後でいくつかの確認を行うと効果的です。
まず、キーが文字列か数値かを確認し、上書きか再採番かを想定しておきます。
次に、同名キーが存在する場合、それが意図した上書きなのかを明確にします。
さらに、ネスト配列なら浅い結合で問題ないかを検討することが重要です。

• 配列キーの型を確認する
• 上書き優先か保持優先かを決める
• ネスト配列の扱いを事前に整理する
• 結合後の配列構造をテストで確認する

これらを徹底するだけで、配列結合に関する不具合は大きく減らせます。
特に保守案件では、配列の内容だけでなく、結合ルールそのものが仕様になっていることが多いため、レビュー時にも確認すべきポイントです。
最終的には、関数の挙動を暗記するより、どの結果を期待するのかを先に定義する姿勢が重要です。

まとめ

PHP Array_merge 連想配列の理解で重要なのは、文字列キーは後ろの配列で上書きされ、数値キーは追加後に再採番されるという基本ルールです。
この仕様を正しく把握すると、設定値の統合やオプション配列の組み立てを安全に行えます。
一方で、キー構造を意識せずに使うと、値の消失や意図しない配列変形につながります。
そのため、配列の種類、優先順位、ネストの深さを確認しながら使うことが大切です。

また、配列結合演算子との違いを理解しておくと、上書きしたいのか保持したいのかに応じて適切な方法を選べます。
実務では、挙動を知っているだけでなく、コードから意図が読み取れるように書くことが品質向上につながります。
array_mergeは非常に便利な関数ですが、連想配列では特にルールの理解が不可欠です。
今回のポイントを押さえれば、配列結合で迷う場面を大きく減らせます。