レガシーPHPリファクタ 27:PEAR依存の解消とComposer環境への移行アプローチ

PEAR(PHP Extension and Application Repository)は、PHP 4およびPHP 5の時代に広く使われていた、PHPコードのパッケージ管理システム(およびその公式リポジトリ)です。Composerや名前空間(namespace)が誕生する以前、Webアプリケーション開発に欠かせない多くの機能がPEARパッケージとして提供されていました。

PEAR - PHP Extension and Application Repository

今回は、PEAR依存のコードを現代のComposer環境へ移行し、さらに最終的なスタブ化に至るまでのステップをご紹介します。


1. 書籍CD-ROM・公式リポジトリからの導入(当時の背景)

古い環境では、PHP同梱の pear コマンドを使用するか、PEAR公式サイトから直接アーカイブをダウンロードして組み込んでいました。

C:\>cd \xampp\php
C:\>pear info Services_Amazon
C:\>pear install -f -o XML_Serializer
C:\>pear install -f -o Cache
C:\>pear install -f -o Services_Amazon

C:\>pear install -f -o PEAR::Net_UserAgent_Mobile

C:\>pear install auth

その後、この書籍のサンプルコードをGitHubリポジトリとして公開するにあたり、まずはSmartyを v2.6.33 から Composer経由で利用するように現代化しました。

それに伴い、「PEARパッケージの依存関係も、pearコマンドで管理するのではなくComposerで一元管理したい」という課題に直面することになります。


2. Composer 1時代:PEARリポジトリの活用とパッチ適用

Composer 1系では、repositories に type: "pear" を指定することで、PEARパッケージを vendor/ 下に直接ダウンロードして管理することができました。

composer.json の設定例

{
    "repositories": [
        {
            "type": "pear",
            "url": "https://pear.php.net/"
        }
    ],
    "require": {
        "pear-pear.php.net/Net_UserAgent_Mobile": "^1.0",
        "pear-pear.php.net/Auth": "^1.6",
        "pear-pear.php.net/Services_Amazon": "^0.9.0",
        "pear-pear.php.net/Pager": "^2.5"
    }
}
smartybook/composer.json at e27c64b93af362b98288c3ada32ce16a389bd0b4 · ninton/smartybook
Smarty動的Webサイト構築入門サンプルソース. Contribute to ninton/smartybook development by creating an account on GitHub.

PHP 7.4 / 8.x での罠:=& new の置き換え

古いPEARライブラリには、PHP 5時代によく見られた参照によるオブジェクト代入(=& new)が残っており、そのままでは警告やエラーが発生します。そのため、次のようなシェルスクリプト(patch-pear.sh)を用意し、ダウンロード直後にパッチを当てる運用を行いました。

#!/bin/bash -ux

cd smartybook/vendor/pear-pear.php.net

# 参照代入の検出と置換
find . -name "*.php" | xargs -l1 grep --with-filename -e '=\s*&\s*new'
find . -name "*.php" | xargs -l1 sed -ri 's/=\s*\&\s*new/= new/'
find . -name "*.php" | xargs -l1 grep --with-filename -e '=\s*&\s*new'

# Authパッケージのメソッドシグネチャ調整
sed -ri 's/function fetchData\(\$user, \$pass\)/function fetchData\(\$user, \$pass, \$isChallengeResponse = false\)/' Auth/Auth/Container/Array.php

3. Composer 2への移行とローカル管理(lib/ への退避)

Composer 2系にバージョンアップを試みたところ、Composer 2系ではPEARリポジトリ(type: "pear")のサポートが廃止されているという問題に直面しました。

Packagist上にいくつかのパッケージは存在しているもののメンテナンスが停止していました。

そこで、方針を転換しました。

  1. vendor/pear-pear.php.net ごとリポジトリ内の lib/pear-pear.php.net へコピーして資産化する。
  2. パッチ済みのコードをそのままGitにコミットする。
  3. Composerの autoload.classmap および include-path で読み込ませる。

composer.json のクラスマップ・インクルードパス設定

{
    "autoload": {
        "classmap": [
            "lib/"
        ]
    },
    "include-path": [
        "lib/pear-pear.php.net/Archive_Tar",
        "lib/pear-pear.php.net/Auth",
        "lib/pear-pear.php.net/Console_Getopt",
        "lib/pear-pear.php.net/HTTP_Request",
        "lib/pear-pear.php.net/Net_Socket",
        "lib/pear-pear.php.net/Net_URL",
        "lib/pear-pear.php.net/Net_UserAgent_Mobile",
        "lib/pear-pear.php.net/Pager",
        "lib/pear-pear.php.net/PEAR",
        "lib/pear-pear.php.net/Services_Amazon",
        "lib/pear-pear.php.net/Structures_Graph",
        "lib/pear-pear.php.net/XML_Parser",
        "lib/pear-pear.php.net/XML_Serializer",
        "lib/pear-pear.php.net/XML_Util"
    ]
}
smartybook/composer.json at 6fec44a25f2af812f84e8ba0d311a5f68623e3bb · ninton/smartybook
Smarty動的Webサイト構築入門サンプルソース. Contribute to ninton/smartybook development by creating an account on GitHub.

これでComposer 2環境でも安定してレガシーライブラリをロードできるようになりました。


4. 現在:PEARスタブの用意による「依存からの脱却」

ローカル管理で動くようになったもののPEARパッケージは、中長期的にはモダン化の足かせになります。

まずはリファクタリングの安全性を担保する Golden Master テスト をグリーンに通すことを最優先し、外部依存を排除した固定データを返すスタブクラス(Stub)を用意するアプローチへと進みました。

app/PearStub/
├── AuthStub.php
├── NetUserAgentMobileCommonStub.php
├── NetUserAgentMobileDisplayStub.php
├── PagerStub.php
├── PearPagerMapper.php
├── ServicesAmazonStub.php
└── tests
    └── ServicesAmazonStubTest.php

これにより、古いPEARの仕様にテストが振り回されなくなり、アプリケーション本体のモダン化(PHP 8.5対応やクリーンな設計への置き換え)に集中できる基盤が整いました。

smartybook/app/PearStub/PagerStub.php at main · ninton/smartybook
Smarty動的Webサイト構築入門サンプルソース. Contribute to ninton/smartybook development by creating an account on GitHub.

📝 「スタブ経由」だからうまくいった!実データクラスへの安全な移行

レガシーなPEAR依存を解消する際、つい「どうやって本物のPEARパッケージを新しいPHPやComposer環境で完璧に動かすか」という方向で頭を悩ませます。

しかし、歴史の長いPEARパッケージには、実アプリでは使っていない機能が大量に詰まっています。これらを新しいPHPで置き換えるのは心が折れそうな作業です。

そこで「書籍のサンプルコードだから、実データを返さなくてもいい」という身軽さもあり、いったん固定データを返すスタブを用意することにしました。 次の段階で、スタブを実データを返すクラスへ移行しました。

結果的には、スタブを経由したことでいい効果がありました。

💡 なぜ「スタブを経由する」ほうがいいのか?

「スタブ=テスト用の固定データを返すもの。だから実アプリの置き換えには使えない」と思われがちですが、実はスタブを経由することに最大のメリットがあると思いました。

  1. 「本当に使っている機能」が浮き彫りになる いきなりフルセットのPEARパッケージを置き換えようとすると全容に振り回されますが、まずスタブを作ってテスト(Golden Master)を通すことで、「自分のアプリケーションが、そのパッケージのどのメソッドを、どんな引数で実際に使っているか」という境界線が明確になります。
  2. 「フルセットの移植」という泥沼から解放される PEARの全コードを無理にメンテナンスし続ける必要がなくなります。必要なのは「アプリが求めている最小限のメソッド」だけです。
  3. スタブの皮を被せたまま、中身を「実データ」にスッと差し替えられる 最小限のインターフェースを持つスタブを作ってしまえば、次のステップはそのスタブの構造を維持したまま、中身のロジックを「実データを返す処理」に置き換えるだけです。

🚀 「動く土台」が移行を劇的にシンプルにする

「スタブ」をただのテスト用モックとして終わらせず、現代のきれいなクラスへと生まれ変わらせるための「クッション(安全な通過点)」として活用する。このステップを踏むことで、PEAR依存を安全かつスムーズに解消することができました。


まとめ

レガシーPHPのモダナイゼーションにおけるPEAR依存解消のステップは、以下のように段階的に進めると非常に安全です。

  1. 当時の pear コマンドや Composer 1 の PEAR リポジトリで動かす。
  2. 古い構文(=& new など)を自動パッチ(シェルスクリプト)で現代のPHPに適応させる。
  3. Composer 2対策として、安定したパッチ済みコードをローカル(lib/)に抱えてクラスマップ管理する。
  4. テスト(Golden Master)を通過させるため、最終的にスタブ(Stub)へと置き換えて外部依存を断つ。

レガシーコードの寿命を延ばし、安全に現代的なコードベースへ移行するための参考になれば幸いです。

レガシーPHPリファクタ 27:PEAR依存の解消とComposer環境への移行アプローチ
Smarty動的Webサイト構築入門サンプルソース. Contribute to ninton/smartybook development by creating an account on GitHub.
タイトルとURLをコピーしました