章: 第6章: トラブルシューティング
対象OS: Windows / Mac 共通（OS別の違いは各項目に記載）
「動かない理由がわからない」—— エラーを読む技術を身につける
環境構築でつまずく理由のほとんどは「エラーメッセージを読んでいない」か「読んでも意味がわからない」かのどちらかです。PHPの環境エラーはパターンが決まっていて、原因さえわかれば解決策はシンプルです。
この記事では、Windows・Macの両方でよく発生するエラーをパターン別にまとめます。
—
パターン1: php: command not found / 'php' は内部コマンドとして認識されません
### 意味
PHPはインストールされているが、ターミナルのPATHに登録されていない。
### 原因と解決策
| OS | 解決策 |
| Windows（XAMPP） | 環境変数の Path に C:\xampp\php を追加する（第02回を参照） |
| Windows（変更後） | 環境変数の変更は新しく開いたターミナルから有効になる |
| Mac（MAMP） | ~/.zshrc に export PATH="/Applications/MAMP/bin/php/php8.x.x/bin:$PATH" を追記する |
| Mac（Homebrew） | brew install php のあと source ~/.zshrc を実行する |
確認コマンド（どこのPHPが使われているかを調べる）:
# Mac / WSL2
which php
# Windows
where php
—
パターン2: Apacheが起動しない（XAMPPでポートエラー）
### 意味
ポート80がすでに別のプロセスに使われている。
### エラーメッセージ例
Apache shutdown unexpectedly.
### 解決策
原因の特定（Windows）:
netstat -ano | findstr :80
表示されたPIDを確認して、タスクマネージャーで該当プロセスを終了します。
よくある競合プロセス:
| プロセス | 対処 |
| IIS（Internet Information Services） | Windowsの機能で「IIS」を無効化する |
| Skype（旧バージョン） | Skypeの設定でポート80の使用を無効化する |
| 別のApache / Nginx | 起動中の他サービスを停止する |
別のポートに変更する方法（XAMPP）:
C:\xampp\apache\conf\httpd.conf を開き、Listen 80 を Listen 8080 に変更してApacheを再起動します。その場合のアクセスURLは https://phpl4b.com/ になります。
—
パターン3: PHPファイルがダウンロードされる（中身が実行されない）
### 意味
ApacheがPHPファイルをPHPとして処理せず、テキストとして送信している。
### 解決策
- XAMPPを使用している場合: PHPモジュールが有効になっているか確認する。
C:\xampp\apache\conf\httpd.confでLoadModule php_moduleの行がコメントアウトされていないか確認する。 - ビルトインサーバーを使っている場合:
.php拡張子のファイルをphp -Sで起動したディレクトリ以下に置いているか確認する。
—
パターン4: Fatal error: Uncaught Error: Class not found
### 意味
指定したクラスが読み込まれていない。
### よくある原因
| 原因 | 解決策 |
require や include が間違っている |
ファイルパスを確認する（相対パスか絶対パスか） |
| Composerのオートロードが更新されていない | composer dump-autoload を実行する |
| 名前空間の指定が間違っている | use 宣言とクラスのnamespaceが一致しているか確認する |
—
パターン5: MySQLに接続できない
### エラーメッセージ例
SQLSTATE[HY000] [2002] Connection refused
### 確認手順
1. MySQLサービスが起動しているか確認
– XAMPP: Control Panelでグリーン表示か確認
– MAMP: GUIでMySQLランプが点灯しているか確認
– Docker: docker compose ps でStatusがRunningか確認
2. 接続情報が正しいか確認
| 項目 | XAMPPデフォルト | MAMPデフォルト | Dockerの場合 |
| ホスト | 127.0.0.1 |
127.0.0.1 |
サービス名（例: db） |
| ポート | 3306 |
8889 |
3306 |
| ユーザー | root |
root |
compose.ymlで設定した値 |
| パスワード | （空） | root |
compose.ymlで設定した値 |
MAMPの注意: MAMPのMySQLはデフォルトでポート
8889を使います。3306に変更する場合はMAMPのPreferencesから設定します。
—
パターン6: Dockerコンテナが起動しない
### 確認コマンド
# コンテナの状態を確認
docker compose ps
# エラーログを表示
docker compose logs
# 特定サービスのログ
docker compose logs web
### よくある原因
| 原因 | 解決策 |
| ポートが競合している | docker-compose.yml のポート番号を変更する（例: 8080:80 → 8081:80） |
docker-compose.yml のインデントが崩れている |
YAMLはスペースでインデントする（タブ不可） |
| イメージ名が間違っている | docker pull php:8.2-apache で存在を確認する |
—
パターン7: 改行コードの問題（Windows固有）
### 症状
シェルスクリプト（.sh）をLinux環境（WSL2・Docker）で実行すると「コマンドが見つからない」エラーが出る。
### 原因
Windowsのエディタで保存すると改行コードが CRLF（\r\n）になることがあります。Linux/Macは LF（\n）のみを期待するため、余分な \r がコマンド名の末尾に含まれてしまいます。
### 解決策
VS Codeで変換:
- 右下のステータスバーに表示されている
CRLFをクリック →LFを選択して保存する
VS Codeのデフォルト設定:
"files.eol": "\n"
settings.json に追記すると新規ファイルが自動的に LF になります。
—
まとめ
| エラーパターン | 原因 | 確認する場所 |
php: command not found |
PATHの未設定 | 環境変数、~/.zshrc |
| Apache起動失敗 | ポート競合 | netstat、タスクマネージャー |
| PHPがダウンロードされる | モジュール設定ミス | httpd.conf |
| クラスが見つからない | オートロード・パスのミス | composer dump-autoload、namespaceの確認 |
| MySQL接続エラー | サービス未起動・接続情報の誤り | サービスの状態、ポート番号 |
| Dockerコンテナ未起動 | ポート競合・YAMLミス | docker compose logs |
| シェルスクリプトエラー | 改行コードCRLF | VS Codeで LF に変換 |
環境系のトラブルは「エラーメッセージを正確に読む」「ログを確認する」「一つ変えては試す」の繰り返しで解決できます。焦らず順番に確認していきましょう。
