古い PHP システムを安全に改修する手順：準備から変更ルールまで

「原因は分かった。でも直すのが怖い」。古い PHP システムの改修でよく耳にする言葉です。どこかを直したら別のところが壊れた、という経験が積み重なると、次の一手がなかなか踏み出せなくなります。

この記事では、古い PHP システムを改修する際に実際に行っている準備と、変更を安全に進めるためのルールをまとめます。

改修前の準備

バージョン管理の確認と整備

まず、変更履歴を残せる仕組みが入っているかを確認します。Git や Subversion が導入済みであればアクセスできる状態を確認し、なければ Git リポジトリを作成してから作業を始めます。

バージョン管理がない状態で改修に入ると、「元に戻したい」と思ったときに手段がありません。古いシステムほど重要な準備です。

旧環境の複製

現行システムと同じ（またはほぼ同じ）動作環境を手元に用意します。仕様が分からない箇所や動作を確認したい部分があっても、手元で動かせる環境があれば調査できます。

基本は Docker などの仮想環境で構築します。OS レベルの依存が強い場合は、Vagrant の方が確実なこともあります。

完全に同一にならないケースもあります。PHP のバージョンが厳密に合わない場合や、セキュリティアップデートが長く適用されていない本番環境では、手元で完全に再現するのが難しいことがあります。どうしても本番環境での確認が必要な場合は、お客様の許可をいただいた上でアクセスします。ただし、ソースコードの解析で対処できることがほとんどで、本番環境への直接アクセスが必要になることは滅多にありません。

E2E テストの準備

E2E（エンドツーエンド）テストとは、実際の画面操作を自動で再現し、「ログイン → データ入力 → 保存 → 一覧に反映」といった一連の動作が正しく動くかを確認する仕組みです。

改修後に主要な操作が壊れていないことを確認できるよう、改修前に E2E テストを用意しておきます。テストの内容はお客様と画面を見ながら確認し、「どの操作が正常に動けば問題ないか」をすり合わせます。お客様から「ここは必ず確認してほしい」という要望をもらえると、テストの精度が上がります。

PHPUnit などのユニットテストも有効ですが、古い PHP 環境では、PHPUnit や依存ライブラリの対応バージョンが限られ、テスト環境を整えるだけで時間がかかることがあります。

実際に CakePHP 2 の案件では、アプリケーション本体の改修よりも、古いテスト環境を維持することの方が重く感じられる場面がありました。その経験から、古い PHP システムの改修では、まず E2E テストで主要な画面操作を守る方針を取ることが多いです。

工期や予算の都合で E2E テストを十分に用意できない場合は、試験仕様書を準備して手動でテストします。ただし、システムの規模が大きい場合は E2E テストがないと見落としが増えるため、何らかの形で整備することをお勧めします。

データベースの機密情報のマスキング

手元の環境で作業する際は、個人情報や機密データをマスキングします。外部に送信しない形で使えるローカルの AI ツールに依頼することも、自作のスクリプトで加工することもあります。外部のクラウド AI にコードやデータを渡す場合は、事前にお客様の確認と許可を取ります。

変更を安全に進めるためのルール

変更量を最小限にする

一度に大きく変えると、何が原因で問題が起きたか分からなくなります。「直したい箇所だけを直す」という原則を守ることで、問題が起きたときの調査が格段に楽になります。改修と同時にリファクタリングを混ぜるのは避けます。

共通処理は影響範囲を確認してから触る

仕様書がないシステムでも、ソースコードを検索するツールを使えば、同じ処理がどこから使われているかを調べられます。使われている場所が多いほど、その変更は広い範囲に影響します。

共通処理は、影響範囲が広い場合ほど慎重に扱います。どうしても修正が必要な場合は、既存の利用箇所に影響が出にくい形にとどめます。

呼び出し方を変えない

既存の処理の使い方を変えると、その処理を使っている箇所もあわせて修正する必要があります。古いシステムでは利用箇所が把握しきれていないことも多く、見落としが生じやすいです。

何かが壊れたときの対処

E2E テストは「何かがおかしい」ことを知らせてくれますが、「どこがおかしいか」までは教えてくれないことがほとんどです。問題箇所の特定はソースコードを細かく調べる必要があります。

古いシステムを改修すると別の箇所が壊れることは珍しくありません。作りが複雑に絡み合っているケースが多いためです。「壊れる可能性がある」ことを前提に進め方を組んでおくと、実際に壊れたときに慌てずに対処できます。

不具合の調査手順については古い PHP システムのバグ調査で最初に確認することもあわせてご覧ください。

「直したいが手が出せない」「改修したら別のところが壊れた」という段階でも、状況の整理からご相談いただけます。レガシーシステム保守またはDX推進・システム改善からどうぞ。

古いシステムを改修・保守できる状態へ戻す取り組みの全体像については、レガシーシステム再生とは？リプレースの前に現行システムを活かす選択肢にまとめています。