Composer 是什麼？PHP Composer 教學（install、require、PSR-4 速查）

Composer 是 PHP 的依賴管理工具：在專案裡宣告需要哪些函式庫與版本範圍，Composer 會下載套件到 vendor/，並產生 vendor/autoload.php 讓你不必手動 require 每個檔案。現代 PHP 專案（Laravel、Symfony、WordPress 外掛開發）幾乎都離不開它。

這篇從「Composer 是什麼」出發，帶你完成安裝、建立專案、讀懂 composer.json／composer.lock，以及 PSR-4 自動載入設定。

指令速查

Composer 解決什麼問題？

手動 require 檔案就像點餐時每道菜都要自己去廚房端——專案一大很快就亂掉。Composer 做兩件事：

1. 管理依賴：解析版本相容性，下載套件與其子依賴到 vendor/
2. 自動載入：產生 autoloader，PHP 只要 require 'vendor/autoload.php' 就能用已安裝的類別

注意：Composer 管理的是每個專案自己的依賴，不是全機共用。不同專案可以用不同版本的同一套件。

安裝 Composer

先確認有 PHP，再依 Composer 官方安裝說明 操作。macOS 用 Homebrew：

brew install composer
composer --version

尚未安裝 Homebrew？可看 Homebrew 教學。

建立第一個 Composer 專案

初始化

composer init

或直接新增套件（會自動建立／更新 composer.json）：

composer require monolog/monolog

執行後 Composer 會更新 composer.json、解析依賴、建立或更新 composer.lock，並安裝到 vendor/。

在 PHP 中載入

<?php

require __DIR__ . '/vendor/autoload.php';

__DIR__ 代表目前檔案所在目錄，比依賴工作目錄更穩定。

composer.json 常見欄位

{
    "name": "vendor/project",
    "description": "專案描述",
    "type": "project",
    "require": {
        "monolog/monolog": "^3.0"
    },
    "require-dev": {
        "phpunit/phpunit": "^11.0"
    },
    "autoload": {
        "psr-4": {
            "App\\": "src/"
        }
    },
    "scripts": {
        "test": "phpunit"
    }
}

正式專案不要用 * 當版本約束；讓 Composer 寫入 lock 檔固定實際版本。完整欄位見 composer.json schema。

PSR-4 自動載入

Composer 是工具；PSR-4 是命名空間對應檔案路徑的規範。兩者常一起用，但職責不同。

專案結構：

project/
├── composer.json
├── src/
│   └── Controllers/
│       └── UserController.php
└── public/
    └── index.php

composer.json：

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

App\Controllers\UserController 對應 src/Controllers/UserController.php：

<?php

namespace App\Controllers;

class UserController
{
    public function index(): string
    {
        return 'Hello, Composer!';
    }
}

修改 autoload 後執行：

composer dump-autoload

composer.lock 要不要提交？

不要把 vendor/ 當版本紀錄——composer.json 描述需求，composer.lock 固定結果。

實用工作流程

新專案：

composer init
composer require vendor/package

從 Git 拉下專案：

composer install

有計畫地更新依賴：

composer update
composer validate

掌握分工後：composer.json 描述需求，composer.lock 固定結果，vendor/autoload.php 把類別帶進來。

常見問題

參考資料

• Composer Introduction
• Composer Basic usage
• Composer CLI Commands
• The composer.json schema
• PSR-4: Autoloader