PHP Composer

Composer 是 PHP 的依賴管理工具，用於管理專案的第三方套件。

安裝 Composer

# macOS / Linux
curl -sS https://getcomposer.org/installer | php
sudo mv composer.phar /usr/local/bin/composer

# 確認安裝
composer --version

初始化專案

# 互動式建立 composer.json
composer init

# 或直接建立 composer.json

{
  "name": "myname/myproject",
  "description": "My PHP Project",
  "type": "project",
  "require": {
    "php": ">=8.1"
  },
  "autoload": {
    "psr-4": {
      "App\\": "src/"
    }
  }
}

安裝套件

# 安裝套件
composer require monolog/monolog

# 安裝開發依賴
composer require --dev phpunit/phpunit

# 安裝特定版本
composer require monolog/monolog:^3.0

# 移除套件
composer remove monolog/monolog

版本約束

約束說明
1.2.3精確版本
>=1.0大於等於
^1.2相容版本（1.2.0 到 <2.0.0）
~1.2約略版本（1.2.0 到 <1.3.0）
*任何版本

安裝依賴

# 根據 composer.lock 安裝
composer install

# 更新依賴
composer update

# 更新特定套件
composer update monolog/monolog

# 正式環境安裝（不含開發依賴）
composer install --no-dev

Autoloading

PSR-4 自動載入

{
  "autoload": {
    "psr-4": {
      "App\\": "src/"
    }
  }
}

<?php
// src/Models/User.php
namespace App\Models;

class User {
    // ...
}
?>

<?php
// index.php
require 'vendor/autoload.php';

use App\Models\User;

$user = new User();
?>

更新 autoload

# 修改 autoload 設定後執行
composer dump-autoload

# 優化（正式環境）
composer dump-autoload --optimize

常用套件

# HTTP 客戶端
composer require guzzlehttp/guzzle

# 日誌
composer require monolog/monolog

# 測試
composer require --dev phpunit/phpunit

# 程式碼分析
composer require --dev phpstan/phpstan

# 程式碼風格
composer require --dev friendsofphp/php-cs-fixer

使用套件

<?php
require 'vendor/autoload.php';

use Monolog\Logger;
use Monolog\Handler\StreamHandler;

$log = new Logger('app');
$log->pushHandler(new StreamHandler('app.log', Logger::WARNING));

$log->warning('This is a warning');
$log->error('This is an error');
?>

Scripts

{
  "scripts": {
    "test": "phpunit",
    "lint": "phpstan analyse src",
    "format": "php-cs-fixer fix src"
  }
}

composer test
composer lint
composer format

管理環境變數 (phpdotenv)

在開發專案時，不應該將敏感資料（如資料庫密碼、API Key）直接寫在程式碼中。通常我們會使用 .env 檔案來管理環境變數。

安裝 phpdotenv

composer require vlucas/phpdotenv

使用方式

  1. 在專案根目錄建立 .env 檔案：
DB_HOST=localhost
DB_PASS=s3cr3t
API_KEY=your_api_key_here
  1. 在 PHP 中載入：
<?php
require 'vendor/autoload.php';

$dotenv = Dotenv\Dotenv::createImmutable(__DIR__);
$dotenv->load();

// 取得環境變數
$dbHost = $_ENV['DB_HOST'];
$apiKey = getenv('API_KEY');
?>
記得將 .env 加入 .gitignore，不要將它上傳到受版本控制的代碼庫中。你可以提供一個 .env.example 讓其他開發者參考。

composer.json vs composer.lock

檔案說明
composer.json定義依賴需求
composer.lock鎖定實際安裝的版本
composer.lock 應該加入版本控制，確保團隊使用相同版本。

常用指令

# 顯示已安裝套件
composer show

# 顯示套件資訊
composer show monolog/monolog

# 檢查過期套件
composer outdated

# 驗證 composer.json
composer validate

# 清除快取
composer clear-cache

私有套件

{
  "repositories": [
    {
      "type": "vcs",
      "url": "https://github.com/mycompany/private-package"
    }
  ],
  "require": {
    "mycompany/private-package": "^1.0"
  }
}

專案結構範例

my-project/
├── composer.json
├── composer.lock
├── vendor/
├── src/
│   ├── Controllers/
│   ├── Models/
│   └── Services/
├── tests/
├── public/
│   └── index.php
└── .gitignore

# .gitignore
/vendor/