一、前置环境准备（必做）

1. 核心依赖软件

表格

软件	版本要求	作用
PHP	≥7.4（推荐 8.1+）	包运行基础
Composer	最新版	包管理 / 构建
Git	任意	版本控制 / 发布
编辑器	VSCode/PhpStorm	编码

2. 环境校验命令

bash

运行

# 校验PHP版本
php -v
# 校验Composer（升级到最新）
composer -V
composer self-update
# 校验Git
git --version

3. 账号准备

GitHub/Gitee 账号（托管代码）
Packagist.orgFile 账号（发布包，用 GitHub 一键登录）

二、项目初始化（核心：composer.json + 目录结构）

我们开发一个通用字符串工具包（示例：my/string-utils），全程标准化操作。

1. 创建项目目录 & 初始化

bash

运行

# 1. 创建包目录（命名：小写+中划线，全局唯一）
mkdir string-utils && cd string-utils

# 2. 交互式生成composer.json（核心文件，一路回车可默认，关键项手动填）
composer init

2. composer init 关键配置详解（重点）

交互式提问核心项必须正确填写，其余默认即可：

plaintext

Package name (<vendor>/<name>) : my/string-utils  # 包名：厂商名/包名（全网唯一）
Description : 通用PHP字符串工具包                  # 包描述
Author : 你的名字 <你的邮箱>                        # 作者信息
Minimum Stability : stable                         # 最低稳定性（stable=稳定版）
Package Type : library                             # 包类型（library=通用库）
License : MIT                                      # 开源协议（最常用）
Define your dependencies: no                       # 暂不定义依赖
Define your dev dependencies: no                   # 暂不定义开发依赖
Add PSR-4 autoload mapping? yes                   # 开启PSR-4自动加载（必选）

3. 最终目录结构（PHP 包标准结构）

初始化后手动补全目录，行业通用规范：

plaintext

string-utils/
├── src/                # 核心源码目录（必选）
├── tests/              # 单元测试目录（专业包必备）
├── docs/               # 文档目录（可选）
├── composer.json       # Composer配置文件（核心）
├── .gitignore          # Git忽略文件
├── README.md           # 包使用文档（必选）
└── LICENSE             # 开源协议文件

4. 完善 composer.json（重中之重）

打开文件，手动补全自动加载、脚本配置，最终完整版：

json

{
    "name": "my/string-utils",
    "description": "通用PHP字符串工具包，支持脱敏、截取、大小写转换等",
    "type": "library",
    "license": "MIT",
    "authors": [
        {
            "name": "你的名字",
            "email": "你的邮箱@xxx.com"
        }
    ],
    "minimum-stability": "stable",
    "require": {
        "php": ">=7.4"  # 限制PHP最低版本
    },
    "autoload": {
        "psr-4": {
            "My\\StringUtils\\": "src/"  # PSR-4映射：命名空间→源码目录
        }
    },
    "autoload-dev": {
        "psr-4": {
            "My\\StringUtils\\Tests\\": "tests/"
        }
    },
    "scripts": {
        "test": "phpunit"  # 快捷执行测试
    }
}

核心知识点

PSR-4 自动加载：命名空间 My\StringUtils 对应 src/ 目录，文件名 = 类名（大驼峰）
包名唯一：vendor/name 不能和 Packagist 已有包重复

三、编写核心业务代码

严格遵循命名空间 + 大驼峰类名，我们写 3 个常用方法：字符串脱敏、首字母大写、去除空格。

1. 创建核心工具类

新建文件：src/StringHelper.php

php

运行

<?php

namespace My\StringUtils;

/**
 * 字符串工具类
 * @method static string desensitize(string $str, int $start=2, int $end=2) 字符串脱敏
 * @method static string trimAll(string $str) 去除所有空格
 */
class StringHelper
{
    /**
     * 字符串脱敏（手机号/姓名通用）
     * @param string $str 原始字符串
     * @param int $start 保留开头位数
     * @param int $end 保留结尾位数
     * @return string
     */
    public static function desensitize(string $str, int $start = 2, int $end = 2): string
    {
        $len = mb_strlen($str);
        if ($len <= $start + $end) return $str;
        $mask = str_repeat('*', $len - $start - $end);
        return mb_substr($str, 0, $start) . $mask . mb_substr($str, -$end);
    }

    /**
     * 去除字符串所有空格（含中文空格）
     * @param string $str
     * @return string
     */
    public static function trimAll(string $str): string
    {
        return preg_replace('/\s+/u', '', $str);
    }

    /**
     * 首字母大写（支持中文）
     * @param string $str
     * @return string
     */
    public static function ucfirst(string $str): string
    {
        $first = mb_substr($str, 0, 1);
        $rest = mb_substr($str, 1);
        return mb_strtoupper($first) . $rest;
    }
}

2. 生成自动加载文件

执行命令，生成 vendor 目录和自动加载文件：

bash

运行

composer dump-autoload

四、单元测试（专业包标配，必做）

用 PHPUnit 做测试，保证代码稳定性。

1. 安装 PHPUnit（开发依赖）

bash

运行

composer require --dev phpunit/phpunit ^9.0

2. 编写测试用例

新建文件：tests/StringHelperTest.php

php

运行

<?php

namespace My\StringUtils\Tests;

use My\StringUtils\StringHelper;
use PHPUnit\Framework\TestCase;

class StringHelperTest extends TestCase
{
    // 测试脱敏方法
    public function testDesensitize()
    {
        $this->assertEquals('13****56', StringHelper::desensitize('13800138056', 2, 2));
    }

    // 测试去空格
    public function testTrimAll()
    {
        $this->assertEquals('abc123', StringHelper::trimAll(' a b c 123 '));
    }

    // 测试首字母大写
    public function testUcfirst()
    {
        $this->assertEquals('Hello', StringHelper::ucfirst('hello'));
    }
}

3. 执行测试

bash

运行

# 方式1：快捷命令（composer.json中配置的script）
composer test

# 方式2：原生命令
./vendor/bin/phpunit tests/

✅ 输出 OK (3 tests, 3 assertions) 代表测试通过！

五、Git 版本控制（发布必备）

1. 配置 .gitignore（PHP 包标准）

新建 .gitignore，忽略无用文件：

plaintext

vendor/
composer.lock
.phpunit.result.cache
.idea/
.vscode/
*.log

2. 初始化 Git & 提交代码

bash

运行

# 初始化仓库
git init

# 添加所有文件
git add .

# 提交代码
git commit -m "feat: 初始化字符串工具包，新增脱敏/去空格/首字母大写方法"

3. 语义化版本打 Tag（Composer 版本核心）

Composer基于 Git Tag 识别版本，遵循 x.y.z 语义化：

bash

运行

# 打版本标签（v1.0.0 稳定版）
git tag v1.0.0

# 查看标签
git tag

六、发布到 Packagist（全网可安装）

1. 推送到 GitHub

GitHub 新建公开仓库（名称：string-utils）
执行推送命令：

bash

运行

# 关联远程仓库
git remote add origin git@github.com:你的用户名/string-utils.git

# 推送代码+标签
git push -u origin main --tags

2. Packagist 提交包

登录 Packagist.org
点击右上角 Submit
粘贴 GitHub 仓库地址，点击 Check → Submit
成功！你的包已全网发布 🎉

3. 配置自动同步（必做）

后续更新代码，自动同步到 Packagist：

GitHub 仓库 → Settings → Webhooks → Add webhook
Payload URL：https://packagist.org/api/github
Content type：application/json
Secret：Packagist 个人中心的 API Token
点击添加，完成自动同步

七、本地测试（未发布前调试，开发神器）

开发阶段无需发布，本地项目直接引入本地包测试：

新建一个测试项目 test-project
编辑测试项目的 composer.json，添加本地包路径：

json

{
    "repositories": [
        {
            "type": "path",
            "url": "../string-utils"  # 本地包的相对路径
        }
    ],
    "require": {
        "my/string-utils": "dev-main"
    }
}

安装本地包：composer require my/string-utils
测试调用：

php

运行

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

use My\StringUtils\StringHelper;

// 测试脱敏
echo StringHelper::desensitize('13800138056');

八、全网使用你的 Composer 包

发布成功后，任何 PHP 项目都能安装：

1. 安装命令

bash

运行

composer require my/string-utils

2. 代码调用

php

运行

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

use My\StringUtils\StringHelper;

// 1. 手机号脱敏
echo StringHelper::desensitize('13800138056', 3, 4); // 138****8056

// 2. 去除所有空格
echo StringHelper::trimAll(' 你好 世界 123 '); // 你好世界123

// 3. 首字母大写
echo StringHelper::ucfirst('php'); // Php

九、高级优化（专业包加分项）

1. 代码规范检查（PSR-12）

安装 PHP-CS-Fixer，统一代码风格：

bash

运行

composer require --dev friendsofphp/php-cs-fixer

2. 完善 README.md（必写）

标准模板包含：安装、使用示例、API、协议、更新日志

3. 添加 LICENSE 协议

根目录新建 LICENSE，粘贴 MIT 协议文本

4. 版本更新流程

bash

运行

# 1. 修改代码
# 2. 提交代码
git commit -m "fix: 修复脱敏方法中文长度问题"
# 3. 打新版本标签
git tag v1.0.1
# 4. 推送
git push --tags

十、常见问题 & 排错（100% 踩坑解决）

自动加载找不到类检查：命名空间≠目录结构、类名≠文件名、未执行 composer dump-autoload
Packagist 找不到版本必须打Git Tag（v1.0.0），仅推送代码无效
安装包提示稳定性错误composer.json 新增 "minimum-stability": "stable"
命名空间冲突厂商名（vendor）用个人 / 公司英文名，保证唯一

十一、核心规范总结（牢记）

命名规范：包名小写 + 中划线，类名大驼峰，方法小驼峰
自动加载：严格遵循 PSR-4，命名空间与目录一一对应
版本管理：语义化版本 x.y.z，Git Tag 驱动版本
代码质量：必写单元测试、遵循 PSR-12 代码规范

最终成果

你拥有了一个符合行业标准、可全网安装、可迭代维护的 Composer 包，支持框架（Laravel/ThinkPHP）原生使用！

从零开发 Composer 包

一、前置环境准备（必做）

1. 核心依赖软件

2. 环境校验命令

3. 账号准备

二、项目初始化（核心：composer.json + 目录结构）

1. 创建项目目录 & 初始化

2. composer init 关键配置详解（重点）

3. 最终目录结构（PHP 包标准结构）

4. 完善 composer.json（重中之重）

核心知识点

三、编写核心业务代码

1. 创建核心工具类

2. 生成自动加载文件

四、单元测试（专业包标配，必做）

1. 安装 PHPUnit（开发依赖）

2. 编写测试用例

3. 执行测试

五、Git 版本控制（发布必备）

1. 配置 .gitignore（PHP 包标准）

2. 初始化 Git & 提交代码

3. 语义化版本打 Tag（Composer 版本核心）

六、发布到 Packagist（全网可安装）

1. 推送到 GitHub

2. Packagist 提交包

3. 配置自动同步（必做）

七、本地测试（未发布前调试，开发神器）

八、全网使用你的 Composer 包

1. 安装命令

2. 代码调用

九、高级优化（专业包加分项）

1. 代码规范检查（PSR-12）

2. 完善 README.md（必写）

3. 添加 LICENSE 协议

4. 版本更新流程

十、常见问题 & 排错（100% 踩坑解决）

十一、核心规范总结（牢记）

最终成果