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

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上にいくつかのパッケージは存在しているもののメンテナンスが停止していました。
そこで、方針を転換しました。
vendor/pear-pear.php.netごとリポジトリ内のlib/pear-pear.php.netへコピーして資産化する。- パッチ済みのコードをそのままGitにコミットする。
- 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"
]
}

これで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対応やクリーンな設計への置き換え)に集中できる基盤が整いました。

📝 「スタブ経由」だからうまくいった!実データクラスへの安全な移行
レガシーなPEAR依存を解消する際、つい「どうやって本物のPEARパッケージを新しいPHPやComposer環境で完璧に動かすか」という方向で頭を悩ませます。
しかし、歴史の長いPEARパッケージには、実アプリでは使っていない機能が大量に詰まっています。これらを新しいPHPで置き換えるのは心が折れそうな作業です。
そこで「書籍のサンプルコードだから、実データを返さなくてもいい」という身軽さもあり、いったん固定データを返すスタブを用意することにしました。 次の段階で、スタブを実データを返すクラスへ移行しました。
結果的には、スタブを経由したことでいい効果がありました。
💡 なぜ「スタブを経由する」ほうがいいのか?
「スタブ=テスト用の固定データを返すもの。だから実アプリの置き換えには使えない」と思われがちですが、実はスタブを経由することに最大のメリットがあると思いました。
- 「本当に使っている機能」が浮き彫りになる いきなりフルセットのPEARパッケージを置き換えようとすると全容に振り回されますが、まずスタブを作ってテスト(Golden Master)を通すことで、「自分のアプリケーションが、そのパッケージのどのメソッドを、どんな引数で実際に使っているか」という境界線が明確になります。
- 「フルセットの移植」という泥沼から解放される PEARの全コードを無理にメンテナンスし続ける必要がなくなります。必要なのは「アプリが求めている最小限のメソッド」だけです。
- スタブの皮を被せたまま、中身を「実データ」にスッと差し替えられる 最小限のインターフェースを持つスタブを作ってしまえば、次のステップはそのスタブの構造を維持したまま、中身のロジックを「実データを返す処理」に置き換えるだけです。
🚀 「動く土台」が移行を劇的にシンプルにする
「スタブ」をただのテスト用モックとして終わらせず、現代のきれいなクラスへと生まれ変わらせるための「クッション(安全な通過点)」として活用する。このステップを踏むことで、PEAR依存を安全かつスムーズに解消することができました。
まとめ
レガシーPHPのモダナイゼーションにおけるPEAR依存解消のステップは、以下のように段階的に進めると非常に安全です。
- 当時の
pearコマンドや Composer 1 の PEAR リポジトリで動かす。 - 古い構文(
=& newなど)を自動パッチ(シェルスクリプト)で現代のPHPに適応させる。 - Composer 2対策として、安定したパッチ済みコードをローカル(
lib/)に抱えてクラスマップ管理する。 - テスト(Golden Master)を通過させるため、最終的にスタブ(Stub)へと置き換えて外部依存を断つ。
レガシーコードの寿命を延ばし、安全に現代的なコードベースへ移行するための参考になれば幸いです。

