PHP包开发怎么发布

PHP包开发发布完整指南

前期准备

环境要求

• PHP 7.4+（推荐8.0+）
• Composer 2.0+
• Git 账号（GitHub/GitLab）
• Packagist 账号

项目结构规范

my-package/
├── src/                 # 源码目录
│   └── MyClass.php
├── tests/               # 测试目录
├── docs/                # 文档
├── examples/            # 使用示例
├── LICENSE              # 许可证
├── README.md            # 说明文档
├── composer.json        # 包配置
└── .gitignore          # Git忽略文件

创建composer.json

{
    "name": "vendor/package-name",
    "description": "包的功能描述",
    "type": "library",
    "license": "MIT",
    "keywords": ["php", "package", "example"],
    "require": {
        "php": ">=7.4",
        "ext-json": "*"
    },
    "require-dev": {
        "phpunit/phpunit": "^9.0"
    },
    "autoload": {
        "psr-4": {
            "Vendor\\Package\\": "src/"
        }
    },
    "autoload-dev": {
        "psr-4": {
            "Vendor\\Package\\Tests\\": "tests/"
        }
    },
    "authors": [
        {
            "name": "你的名字",
            "email": "your@email.com"
        }
    ],
    "minimum-stability": "stable",
    "prefer-stable": true,
    "scripts": {
        "test": "phpunit"
    }
}

开发与测试

编写代码

// src/MyClass.php
namespace Vendor\Package;
class MyClass
{
    public function hello(): string
    {
        return "Hello World!";
    }
}

编写测试

// tests/MyClassTest.php
use PHPUnit\Framework\TestCase;
use Vendor\Package\MyClass;
class MyClassTest extends TestCase
{
    public function testHello()
    {
        $myClass = new MyClass();
        $this->assertEquals("Hello World!", $myClass->hello());
    }
}

本地测试

# 安装依赖
composer install
# 运行测试
composer test
# 检查代码规范（可选）
composer require --dev phpstan/phpstan
vendor/bin/phpstan analyse src

Git 发布流程

初始化Git仓库

# 在项目目录初始化
git init
# 创建主分支
git branch -M main
# 添加所有文件
git add .
# 创建提交
git commit -m "Initial commit"
# 添加远程仓库
git remote add origin https://github.com/yourusername/my-package.git
# 推送代码
git push -u origin main

创建版本标签

# 创建标签（语义化版本）
git tag v1.0.0
# 或
git tag 1.0.0
# 推送标签
git push origin --tags

发布到 Packagist

注册账号

• 访问 packagist.org
• GitHub账号登录（推荐）或邮箱注册

提交包

网页提交

1. 登录后点击 "Submit Package"
2. 输入Git仓库URL
3. 等待Packagist验证并创建

通过GitHub集成

1. 在GitHub中设置 Webhook
2. 在Packagist中输入GitHub用户名
3. 自动同步更新

设置自动更新（推荐）

在GitHub仓库设置Webhook：

• URL: https://packagist.org/api/github?username=你的用户名&apiToken=你的令牌
• Content-type: application/json
• 触发事件: Releases（或全部）

版本管理与更新

语义化版本规范

主版本号.次版本号.修订号
- 主版本号：不兼容的API修改
- 次版本号：向下兼容的功能性新增
- 修订号：向下兼容的问题修正

更新发布流程

# 修改代码和版本号
# 更新composer.json中的版本信息
# 提交更改
git add .
git commit -m "feat: add new feature"
# 创建新标签
git tag v1.1.0
# 推送代码和标签
git push origin main
git push origin --tags

最佳实践

文档编写

# Package Name
## 安装
composer require vendor/package-name
## 使用
基本用法和示例代码
## 文档
链接到docs目录
## 贡献
如何参与贡献
## 许可证
MIT License

代码质量

• 遵循PSR-12编码规范
• 编写单元测试（覆盖率>80%）
• 使用PHPStan或Psalm进行静态分析
• 添加PHPDoc注释

发布检查清单

• [ ] composer validate 通过
• [ ] 测试全部通过
• [ ] 代码规范检查通过
• [ ] README完善
• [ ] LICENSE文件存在
• [ ] 正确的版本标签
• [ ] 自动更新配置完成

常见问题解决

包找不到

• 检查Packagist是否批准
• 确认包名拼写正确
• 检查composer.json有效性

自动更新失败

• 检查Webhook配置
• 确认Packagist API Token正确
• GitHub仓库权限设置

版本冲突

• 修改composer.json中的依赖约束
• 使用 composer update 更新依赖

进阶技巧

多环境支持

{
    "autoload": {
        "psr-4": {
            "Vendor\\Package\\": "src/"
        },
        "files": ["src/functions.php"]
    }
}

持续集成

# .github/workflows/ci.yml
name: CI
on: [push, pull_request]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: actions/setup-php@v2
      - run: composer install
      - run: composer test

代码覆盖率

<!-- phpunit.xml -->
<phpunit bootstrap="vendor/autoload.php">
    <testsuites>
        <testsuite name="Package">
            <directory>tests</directory>
        </testsuite>
    </testsuites>
    <coverage>
        <include>
            <directory suffix=".php">src</directory>
        </include>
    </coverage>
</phpunit>

通过以上步骤,你就可以成功发布和管理自己的PHP包了，记住要持续维护、更新文档、及时回应用户反馈，这将有助于建立良好的开源社区形象。