php-migrations (crazyfd/php-migrations)

为 PHP 应用提供尽可能接近 Laravel 的数据库迁移能力，底层直接复用 Illuminate Database（支持 10.x / 11.x / 12.x / 13.x） 原生 Migrator / Schema Builder，行为与 Laravel Migration 保持一致。本包内置 Webman 集成，可直接通过 php webman migrate 使用。

基于 hyde1/eloquent-migrations / pxianyu/webman-migrations 升级维护，感谢原作者。

背景

我们的业务迭代很快，之前技术栈是 Laravel + Octane。但由于业务场景比较特殊、流量较大，服务经常遇到性能瓶颈和稳定性问题，在现有硬件资源无法进一步扩容的情况下，我们经过多方面评估，最终将 Laravel 迁移到了 Webman。

迁移之后，Webman 在高并发和高性能场景下的表现确实非常优秀，也很好地解决了我们之前遇到的一些问题。

但在实际迁移过程中，我们也发现了一个比较明显的问题：Laravel 生态经过多年的发展，已经形成了一套非常完善、成熟的组件体系，而 Webman 生态中的部分通用组件存在维护不及时、版本兼容性不足，以及与新版 illuminate/* 组件适配不完善等情况。

与此同时，我们并不希望因为从 Laravel 迁移到 Webman，就放弃 Laravel 中成熟的开发习惯和生态能力。更重要的是，我们希望 Laravel → Webman 的迁移能够尽可能平滑，让原有项目的代码、业务逻辑和成熟组件得到最大程度的复用，而不是为了适配 Webman 而进行大量重构和重复开发。

因此，我们决定围绕现代 Laravel / Illuminate 生态进行适配和维护，在保持 Laravel 原有使用方式和开发体验的基础上，让这些组件能够更好地运行在 Webman 环境中。通过这种方式，尽可能降低 Laravel 项目迁移到 Webman 的改造成本，让原有代码少改甚至不改即可继续使用。

不仅仅是解决当前项目的兼容性问题，更是逐步补齐 Webman 生态中缺失的通用组件，并长期维护一批高质量、现代化的 PHP 组件包，同时将 Webman 作为官方支持的一等集成场景。

简单来说，我们希望做到：

享受 Webman 的高性能，同时保留 Laravel 成熟的生态、开发体验和代码资产，让 Laravel → Webman 不再意味着大规模重写。

环境要求

• PHP >= 8.1
• illuminate/database ^10.0 || ^11.0 || ^12.0 || ^13.0（核心组件需同 major 版本）

注意：实际 PHP 最低版本还取决于安装的 illuminate major 版本；例如 illuminate/database 13.x 要求 PHP >= 8.3。

Webman 集成为可选依赖（suggest），需要时安装：

composer require crazyfd/php-migrations
composer require workerman/webman-framework webman/console # 如项目中尚未安装

安装

composer require crazyfd/php-migrations

安装后自动创建：

• config/plugin/eloquent/migrations/（插件配置与命令注册）
• database/migrations/（迁移文件目录）
• database/seeders/（填充文件目录）

框架集成

目前阶段适配 Webman，其他框架暂无；后续会根据实际需求再评估适配（核心层已框架无关，集成成本可控）。

Webman

配置数据库

在 Webman 中，本项目直接读取 config/database.php：

return [
    'default' => 'mysql',
    'connections' => [
        'mysql' => [
            'driver'   => 'mysql',
            'host'     => '127.0.0.1',
            'port'     => '3306',
            'database' => 'demo',
            'username' => 'root',
            'password' => '',
            'charset'  => 'utf8mb4',
            'prefix'   => '',
        ],
        'pgsql'  => [ /* ... */ ],
        'sqlite' => [
            'driver'   => 'sqlite',
            'database' => '/path/to/database.sqlite',
            'prefix'   => '',
        ],
    ],
];

默认连接会同时注册为 default，因此 -d default 与 -d mysql（默认连接名）等价。

编写 Migration（Laravel 风格）

<?php

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

return new class extends Migration
{
    public function up(): void
    {
        Schema::create('users', function (Blueprint $table) {
            $table->id();
            $table->string('name');
            $table->string('email')->unique();
            $table->timestamps();
        });
    }

    public function down(): void
    {
        Schema::dropIfExists('users');
    }
};

Schema Facade 已由本插件自动注册，迁移文件内可以像 Laravel 一样直接使用 Schema::、Blueprint 等。

也可以使用迁移基类提供的连接（不依赖 Facade）：

$this->schema()->create('users', function (Blueprint $table) { /* ... */ });

命令

常用参数：

--database=pgsql   指定连接
--path=admin       只执行指定子目录的迁移
--realpath         --path 为绝对路径
--pretend          只打印 SQL 不执行（兼容 --dry-run）
--force            生产环境跳过确认
--step             migrate: 逐条记录 batch；rollback: 回滚最近 N 条
--seed / --seeder  迁移后执行填充（migrate / migrate:fresh / migrate:refresh）

示例：

php webman migrate -d sqlite --seed
php webman migrate:rollback --step=2
php webman migrate:fresh -d pgsql --seed
php webman migrate -d mysql --pretend

# Laravel 风格（兼容写法）
php webman make:seeder UsersTableSeeder
php webman db:seed
php webman db:seed --class=UsersTableSeeder
php webman db:seed --class=UsersTableSeeder --force
php webman migrate:fresh --seed --seeder=UsersTableSeeder

Seeder

<?php

namespace Database\Seeders;

use Eloquent\Migrations\Seeds\Seeder;

class UsersTableSeeder extends Seeder
{
    public function run(): void
    {
        $this->table('users')->insert([
            ['name' => 'alice', 'email' => 'alice@example.com'],
        ]);
    }
}

Laravel Compatibility

与 Laravel 基本一致：

• Migration 文件写法（匿名类 + up() / down()）
• 迁移排序（文件名字典序）、batch、rollback / reset / refresh / fresh / status 语义
• --pretend / --step / --force / --seed 参数行为
• 填充命令同时提供两套命名：seed:run / db:seed、seed:create / make:seeder， 支持 db:seed --class=XxxSeeder（短类名或 FQCN 均可）
• Schema Builder 全部由 Illuminate Database 原生提供（字段类型、索引、外键、->change() 等）

与 Laravel 的差异（由 Webman 架构决定）：

• 命令通过 php webman xxx 而非 php artisan xxx 运行
• 迁移目录固定为 database/migrations（可通过 --path 指定子目录）
• --force 的"生产环境"判定读取插件配置 default_environment，而非 Laravel 的 APP_ENV
• 不支持 Laravel 的迁移缓存 / migrate:isolate 等需要完整 Laravel 容器的特性

架构分层

本包核心层框架无关，Webman 只是官方支持的一等集成场景：

• Migration / Seeder / Schema 能力优先复用 Illuminate Database 原生实现
• Eloquent\Migrations\Support\ConfigResolver 负责收口配置解析，解析顺序：
  1. ConfigResolver::set(array)（框架 adapter / 测试显式注入）
  2. --config 指定的配置文件（如 elmigrator.php，纯 PHP CLI 模式）
  3. Webman 插件配置 config/plugin/eloquent/migrations/app.php（在 Webman 中运行时）
• src/config/plugin/eloquent/migrations 只负责 Webman 插件配置发布和命令注册
• src/Command 目录为纯 Symfony Console 命令，不依赖任何框架
• bin/elmigrator 提供独立 CLI 入口，非 Webman 项目可直接使用

独立使用（无框架）

在项目根目录创建 elmigrator.php：

<?php
$capsule = new Illuminate\Database\Capsule\Manager();
$capsule->addConnection([
    'driver'   => 'mysql',
    'host'     => '127.0.0.1',
    'database' => 'demo',
    'username' => 'root',
    'password' => '',
    'prefix'   => '',
]);

return [
    'default_environment' => 'development',
    'paths' => [
        'migrations' => 'database/migrations',
        'seeds'      => 'database/seeders',
    ],
    'migration_table' => 'migrations',
    'db' => $capsule->getDatabaseManager(),
];

然后：

vendor/bin/elmigrator migrate
vendor/bin/elmigrator migrate:status
vendor/bin/elmigrator migrate:rollback

加载配置文件时会自动注册 Schema 等 Facade，迁移文件内可继续使用 Laravel 写法。

其他框架（自行集成，暂无官方支持）

目前官方只提供 Webman 集成。其他框架可以自行通过 ConfigResolver::set() 注入配置数组后，使用 Eloquent\Migrations\Application::create() 获取注册好全部命令的 Symfony Console 应用；如有通用框架（如 Symfony、ThinkPHP）的官方适配需求，欢迎提 issue 反馈。

兼容矩阵

Database Support

常见问题

migrate:status 提示 "The migration table is not installed"

这不是报错，是首次使用前的正常状态：migrations 记录表尚未创建。执行一次 php webman migrate（或 php webman migrate:install）即可自动创建。

SQLite 报 "Database file at path ... does not exist"

illuminate/database 10+ 出于安全考虑不会自动创建 SQLite 文件（防止在错误路径静默建库）。两种解决方式：

touch runtime/your_database.sqlite          # 手动创建
php webman create:database your_database.sqlite  # 或用本包命令自动创建

运行测试

composer install
composer test

License

MIT