fiberphp/migration

📋 FiberPHP 数据库迁移 —— Schema 构建器、迁移执行器、命令行工具，版本管理，开箱即用。

dev-master 2026-08-30 15:49 UTC

Requires

• php: >=8.3
• fiberphp/console: dev-master
• fiberphp/database: dev-master
• fiberphp/framework: dev-master
• fiberphp/support: dev-master

Requires (Dev)

• phpunit/phpunit: ^11.0

MIT

• PangBin

• database
• schema
• migration
• migrate
• fiberphp

Published on Packagist.org on 2026-08-30 15:50 UTC

README

FiberPHP 数据库迁移子包。提供 Schema 构建器（Blueprint）、迁移执行器（Migrator）、迁移文件生成器（Creator）与一组命令行工具，支持表结构版本管理、批量回滚、刷新重置，覆盖 MySQL / PostgreSQL / SQLite 三种驱动方言。

特性

• Schema 构建器：Schema::create/table/drop/dropIfExists/rename/hasTable/hasColumn 静态门面，内部委托 Blueprint 链式声明字段与索引
• Blueprint 字段链：id/string/text/integer/bigInteger/float/decimal/boolean/datetime/date/timestamp/json/enum + nullable/default/comment/after 修饰；timestamps/softDelete 快捷；index/unique/primary/dropIndex/dropColumn 索引与列操作
• 外键链式：foreign(columns).references(columns).on(table).onDelete(action).onUpdate(action)，dropForeign 解除
• 驱动感知 DDL：toSql() 按 driver（mysql/pgsql/sqlite）生成方言化建表 / 改表语句，表选项（engine/charset/collate/表注释）按需应用
• 迁移版本管理：migrations 日志表记录已执行迁移与批次号（batch），run 计算 pending 差集按序执行
• 事务包裹：MySQL / PgSQL 迁移在事务内执行（失败自动回滚）；SQLite 对 DDL 事务支持有限，直接执行
• 时间戳文件名：YYYY_MM_DD_His_Snake_name.php，按字典序天然保证执行顺序
• 匿名类迁移：迁移文件 return new class extends Migration { up()/down() };，无需显式命名空间
• 命令行工具：make:migration / migrate:run / migrate:rollback / migrate:refresh / migrate:status

环境要求

• PHP >= 8.3
• fiberphp/framework dev-master
• fiberphp/database dev-master
• fiberphp/console dev-master
• fiberphp/support dev-master

安装

composer require fiberphp/migration

安装后 PackageInstaller::discover 自动发布 config/migration.php，并通过 PackageManifest 注册 5 个迁移命令。

配置

config/migration.php：

return [
    // 迁移文件所在目录（相对于 BASE_PATH）
    'path' => base_path('database/migrations'),

    // 迁移记录表名
    'table' => 'migrations',

    // 使用的数据库连接名（null 表示使用默认连接）
    'connection' => null,
];

命令

命令	说明
make:migration <name> [--table=]	创建迁移文件（传 --table 生成 create 表模板，否则生成空白模板）
migrate:run	执行所有 pending 迁移（按文件名顺序，记入下一批次）
migrate:rollback	回滚最后一批迁移（按 batch 降序执行 down）
migrate:refresh	回滚全部迁移后重新执行（refresh = rollback + run）
migrate:status	列出所有迁移与执行状态（Ran=Yes/No）

示例：

# 创建建表迁移
php fiber make:migration CreateUsersTable --table=users

# 执行迁移
php fiber migrate:run

# 查看状态
php fiber migrate:status

# 回滚最后一批
php fiber migrate:rollback

# 全部回滚并重新迁移
php fiber migrate:refresh

编写迁移

迁移文件位于 database/migrations/，命名格式 YYYY_MM_DD_His_Snake_name.php（由 Creator 自动生成时间戳前缀），文件须返回一个继承 Migration 的匿名类实例：

<?php

declare(strict_types=1);

use FiberPHP\Migration\Blueprint;
use FiberPHP\Migration\Migration;
use FiberPHP\Migration\Schema;

return new class extends Migration {
    public function up(): void
    {
        Schema::create('users', function (Blueprint $table): void {
            $table->id();
            $table->string('name', 64)->comment('用户名');
            $table->string('email', 128)->unique();
            $table->string('password_hash', 255);
            $table->boolean('active')->default(true);
            $table->timestamps();
            $table->softDelete();

            // 外键示例
            $table->foreign('dept_id')
                ->references('id')
                ->on('departments')
                ->onDelete('cascade');
        });
    }

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

修改已有表用 Schema::table()：

Schema::table('users', function (Blueprint $table): void {
    $table->string('phone', 20)->after('email')->nullable();
    $table->dropColumn('password_hash');
    $table->index(['name', 'active']);
});

Blueprint 主要字段方法

类别	方法
主键	id() / incrementId($column)
数值	integer / bigInteger / float / decimal / boolean
字符串	string($col, $len=255) / text / enum($col, $allowed) / json
时间	datetime / date / timestamp / timestamps() / softDelete()
修饰	nullable() / default($col, $val) / defaultVal($val) / comment($c) / after($col)
索引	index / unique / primary / dropIndex / dropColumn / renameColumn
外键	foreign → references → on → onDelete / onUpdate / dropForeign
表选项	engine / charset / collate / tableComment

目录结构

src/
├── Blueprint.php                         # 表结构构建器（链式字段 + 驱动感知 toSql）
├── Creator.php                           # 迁移文件生成器（时间戳命名 + stub）
├── Install.php                           # 包安装器（发布 config + 注册命令）
├── Migration.php                         # 迁移基类（up/down + schema() 代理）
├── MigrationRepository.php               # 迁移日志表读写（migrations 表）
├── Migrator.php                          # 迁移执行器（run/rollback/refresh/status）
├── Schema.php                            # Schema 静态门面（委托给 Blueprint）
├── Command/
│   ├── AbstractMigrationCommand.php      # 命令基类（惰性绑定 Migrator 单例）
│   ├── Make.php                          # make:migration
│   ├── Migrate.php                       # migrate:run
│   ├── Refresh.php                      # migrate:refresh
│   ├── Rollback.php                     # migrate:rollback
│   └── Status.php                       # migrate:status
└── Exception/
    └── MigrationException.php

License

MIT License (c) 2026 庞斌，详见 LICENSE。