Composer 包开发实战：PSR 标准、自动加载与发布到 Packagist

{
    "name": "acme/awesome-logger",
    "description": "A simple structured logger for PHP 8.1+",
    "type": "library",
    "license": "MIT",
    "require": {
        "php": ">=8.1",
        "psr/log": "^3.0"
    },
    "require-dev": {
        "phpunit/phpunit": "^10.0"
    },
    "autoload": {
        "psr-4": {
            "Acme\\Logger\\": "src/"
        }
    },
    "autoload-dev": {
        "psr-4": {
            "Acme\\Logger\\Tests\\": "tests/"
        }
    },
    "minimum-stability": "stable",
    "prefer-stable": true
}

# 运行时依赖进 require
composer require monolog/monolog

# 开发期工具进 require-dev
composer require --dev phpunit/phpunit
composer require --dev friendsofphp/php-cs-fixer

{
    "repositories": [
        { "type": "vcs", "url": "https://github.com/your-company/private-pkg.git" },
        { "type": "path", "url": "../local-packages/*" },
        { "type": "composer", "url": "https://repo.packagist.example" }
    ]
}

{
    "autoload": {
        "psr-4": {
            "Acme\\Logger\\": "src/"
        }
    }
}

{
    "psr-4": {
        "Acme\\Logger\\": "src/",
        "Acme\\Logger\\Handler\\": "src/Handlers/"
    }
}

require __DIR__.'/vendor/autoload.php';   // 一次引入，全部可用
$logger = new Acme\Logger\StructuredLogger();

{
    "autoload": {
        "files": ["src/functions.php"],
        "classmap": ["src/legacy/"]
    }
}

// PSR-12 要点示例
declare(strict_types=1);

namespace Acme\Logger;

use Psr\Log\LoggerInterface;

final class StructuredLogger implements LoggerInterface
{
    public function __construct(
        private string $channel = 'app',      // 构造器属性提升
    ) {}

    public function log($level, string|\Stringable $message, array $context = []): void
    {
        // ...
    }
}

<!-- phpunit.xml -->
<?xml version="1.0" encoding="UTF-8"?>
<phpunit xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         bootstrap="vendor/autoload.php"
         colors="true">
    <testsuites>
        <testsuite name="unit">
            <directory>tests</directory>
        </testsuite>
    </testsuites>
    <coverage>
        <include>
            <directory>src</directory>
        </include>
    </coverage>
</phpunit>

use PHPUnit\Framework\TestCase;

final class StructuredLoggerTest extends TestCase
{
    public function test_emits_json_line(): void
    {
        $logger = new StructuredLogger('test');
        $out = tmpfile();
        $logger->toStream($out)->info('hello', ['user' => 42]);

        rewind($out);
        $json = json_decode(stream_get_contents($out), true);
        self::assertSame('info', $json['level']);
        self::assertSame(42, $json['context']['user']);
    }
}

name: CI
on:
  push:
  pull_request:
jobs:
  test:
    strategy:
      matrix:
        php: ['8.1', '8.2', '8.3']
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: shivammathur/setup-php@v2
        with:
          php-version: ${{ matrix.php }}
          coverage: xdebug
      - run: composer install --prefer-dist --no-progress
      - run: composer test
      - run: composer phpstan

{
    "scripts": {
        "test": "phpunit",
        "phpstan": "phpstan analyse --level=max src tests",
        "cs": "php-cs-fixer fix --dry-run --diff"
    }
}

git init
git add .
git commit -m "feat: initial release"
git remote add origin git@github.com:acme/awesome-logger.git
git push -u origin main

# 打语义化版本 tag（Packagist 靠 tag 识别版本）
git tag 1.0.0
git push --tags

# 在新项目里直接引用
composer require acme/awesome-logger

# 打补丁 / 小功能 / 破坏性版本分别对应 PATCH / MINOR / MAJOR
git tag 1.1.0
git push --tags
composer update   # 消费方升级

# 平滑升级：按 lock 更新到允许的最新
composer update acme/awesome-logger

# 谨慎场景：精确到 tag
composer require acme/awesome-logger:1.1.0

composer audit              # 扫描已知漏洞
composer audit --locked    # 基于 lock 审计
composer update --dry-run  # 预览变更

# 1. 看当前自动加载出的文件路径
php -r "require 'vendor/autoload.php';
        \$r = new ReflectionClass('Acme\\Logger\\StructuredLogger');
        echo \$r->getFileName().PHP_EOL;"

# 2. 查看包为何不被允许
composer why-not acme/awesome-logger 2.0.0

# 3. 深度调试解析
composer update --dry-run -vvv