Laravel 扩展包开发指南

以下是 Laravel 扩展包开发的核心指南，涵盖从创建到发布的完整流程：

---

一、扩展包规划

1. 明确功能边界

   • 解决特定问题（如支付集成、SEO工具）
   • 避免重复造轮子（检查 Packagist 现有包）

2. 命名规范

   • 遵循 vendor/package-name 格式（如 yourname/laravel-analytics）
   • 使用 kebab-case（小写+连字符）

---

二、项目初始化

1. 创建目录结构

mkdir laravel-package-demo && cd laravel-package-demo
mkdir -p src/{Providers,Facades} config database/migrations resources/views

2. 初始化 Composer

{
  "name": "your-vendor/package-name",
  "description": "Laravel package demo",
  "type": "library",
  "license": "MIT",
  "autoload": {
    "psr-4": {
      "YourVendor\\PackageName\\": "src/"
    }
  },
  "extra": {
    "laravel": {
      "providers": [
        "YourVendor\\PackageName\\Providers\\PackageServiceProvider"
      ],
      "aliases": {
        "Package": "YourVendor\\PackageName\\Facades\\PackageFacade"
      }
    }
  }
}

---

三、核心组件开发

1. 服务提供者 (src/Providers/PackageServiceProvider.php)

namespace YourVendor\PackageName\Providers;

use Illuminate\Support\ServiceProvider;

class PackageServiceProvider extends ServiceProvider
{
    public function register()
    {
        // 绑定主要实现类
        $this->app->singleton('package', function ($app) {
            return new \YourVendor\PackageName\PackageManager();
        });
        
        // 合并配置文件
        $this->mergeConfigFrom(__DIR__.'/../../config/package.php', 'package');
    }

    public function boot()
    {
        // 发布配置文件
        $this->publishes([
            __DIR__.'/../../config/package.php' => config_path('package.php'),
        ], 'config');

        // 发布迁移文件
        $this->publishes([
            __DIR__.'/../../database/migrations/' => database_path('migrations'),
        ], 'migrations');

        // 加载路由
        $this->loadRoutesFrom(__DIR__.'/../../routes/web.php');
        
        // 加载视图
        $this->loadViewsFrom(__DIR__.'/../../resources/views', 'package');
    }
}

2. 核心功能类 (src/PackageManager.php)

namespace YourVendor\PackageName;

class PackageManager
{
    public function execute()
    {
        return "Package logic executed!";
    }
}

3. 门面 Facade (src/Facades/PackageFacade.php)

namespace YourVendor\PackageName\Facades;

use Illuminate\Support\Facades\Facade;

class PackageFacade extends Facade
{
    protected static function getFacadeAccessor()
    {
        return 'package'; // 需匹配服务容器绑定名
    }
}

---

四、配置文件示例 (config/package.php)

return [
    'api_key' => env('PACKAGE_API_KEY', 'default_value'),
    'options' => [
        'cache_ttl' => 3600,
        'log_errors' => true,
    ],
];

---

五、路由与视图

1. 路由文件 (routes/web.php)

use Illuminate\Support\Facades\Route;

Route::get('/package-demo', function () {
    return app('package')->execute();
});

2. 视图调用 (resources/views/demo.blade.php)

@extends('package::layout')

@section('content')
    <h1>{{ \YourVendor\PackageName\Facades\PackageFacade::execute() }}</h1>
@endsection

---

六、数据库迁移

1. 创建迁移文件 (database/migrations/2023_01_01_create_package_tables.php)

use Illuminate\Database\Migrations\Migration;
use Illuminate\Database\Schema\Blueprint;
use Illuminate\Support\Facades\Schema;

class CreatePackageTables extends Migration
{
    public function up()
    {
        Schema::create('package_items', function (Blueprint $table) {
            $table->id();
            $table->string('name');
            $table->timestamps();
        });
    }
}

---

七、测试配置

1. 安装测试依赖

composer require --dev phpunit/phpunit orchestra/testbench

2. 创建测试用例 (tests/Feature/PackageTest.php)

namespace Tests\Feature;

use YourVendor\PackageName\Facades\PackageFacade;
use Tests\TestCase;

class PackageTest extends TestCase
{
    protected function getPackageProviders($app)
    {
        return ['YourVendor\PackageName\Providers\PackageServiceProvider'];
    }

    public function test_basic_functionality()
    {
        $result = PackageFacade::execute();
        $this->assertEquals('Package logic executed!', $result);
    }
}

---

八、本地测试（使用 Composer 路径仓库）

1. 在 Laravel 项目中添加：

"repositories": [
    {
        "type": "path",
        "url": "../path/to/laravel-package-demo"
    }
]

2. 安装包：

composer require your-vendor/package-name:@dev

---

九、发布到 Packagist

1. 将代码推送到 GitHub/GitLab
2. 在 Packagist 提交仓库 URL
3. 使用 Git 标签发布版本：

git tag v1.0.0
git push --tags

---

最佳实践

1. 版本兼容

   • 在 composer.json 中明确 Laravel 版本约束：

   "require": {
        "laravel/framework": "^9.0|^10.0"
   }
   

2. 持续集成

   • 使用 GitHub Actions 测试多版本支持

   jobs:
     test:
       strategy:
         matrix:
           laravel: [ '9.*', '10.*' ]
   

3. 文档规范

   • 提供清晰的 README.md 包含：
     • 安装说明
     • 配置示例
     • 使用示例
     • 贡献指南

4. 语义化版本

   • 遵守 MAJOR.MINOR.PATCH 规则
   • 重大变更时升级 MAJOR 版本

5. 安全建议

   • 敏感数据使用 .env 配置
   • 数据库操作使用参数绑定
   • 避免直接返回原始错误信息

---

通过以上步骤，您可以构建出专业级的 Laravel 扩展包。实际开发中还需考虑：

• 异常处理机制
• 缓存策略
• 多语言支持
• 前端资源管理（Vite/webpack 集成）

推荐参考官方包示例：

• Laravel Telescope
• Laravel Horizon