nsedenkov/sprint.migration

1C-Bitrix 的迁移模块

维护者

详情

github.com/nsedenkov/sprint.migration

主页

源代码

安装: 7

依赖项: 0

建议者: 0

安全: 0

星标: 0

关注者: 1

分支: 55

类型:bitrix-module

2.8.19 2018-12-03 11:24 UTC

Requires

MIT 659563ec44b815a93d015288747ec85e619cedac

migrationbitrixsprintandreyryabin

This package is auto-updated.

Last update: 2024-09-22 00:08:29 UTC

README

通过 composer 安装

您的 composer.json 示例，将模块安装在 local/modules/

{
  "extra": {
    "installer-paths": {
      "local/modules/{$name}/": ["type:bitrix-module"]
    }
  },
  "require": {
    "andreyryabin/sprint.migration": "dev-master"
  },
}

控制台

创建 migrate.php 脚本以通过控制台运行迁移

其内容

#!/usr/bin/env php
<?php

require_once realpath(__DIR__) . '/local/modules/sprint.migration/tools/migrate.php';

示例命令

  • php migrate.php add (创建新的迁移)
  • php migrate.php ls --search=text (列出按名称和描述过滤的迁移)
  • php migrate.php up (应用所有迁移)
  • php migrate.php up (应用选定的迁移)
  • php migrate.php mark --as=installed (标记迁移为已安装，但不执行)
  • php migrate.php mark unknown --as=new (标记所有未知迁移为新的，实际上是从数据库中删除它们)

所有命令: https://github.com/andreyryabin/sprint.migration/blob/master/commands.txt

迁移文件示例

/bitrix/php_interface/migrations/Version20150520000001.php

<?php
namespace Sprint\Migration;

class Version20150520000001 extends Version {

    protected $description = "";

    public function up(){
        //
    }

    public function down(){
        //
    }
}

其中需要实现 2 个方法 up 和 down，它们在安装和回滚迁移时运行，例如创建信息块或其他任何需要所有项目副本改变的改变。

所有示例: https://github.com/andreyryabin/sprint.migration/tree/master/examples

迁移状态

  • New 新迁移（仅文件）
  • Installed 已安装迁移（文件 + 安装记录）
  • Unknown 未知迁移（仅安装记录）

执行迁移时的消息

  • Version0000 (up) success 迁移安装成功
  • Version0000 (down) success 迁移回滚成功
  • Version0000 (down) error: (text) 迁移回滚失败：错误（错误文本）

模块配置

主要（默认） /local/php_interface/migrations.cfg.php 或 /bitrix/php_interface/migrations.cfg.php

额外的 /local/php_interface/migrations.{NAME}.php 或 /bitrix/php_interface/migrations.{NAME}.php

<?php return array (
  'title' => '',
  'migration_dir' => '',
  'migration_table' => '',
  'migration_extend_class' => '',
  'version_prefix' => '',
  'tracker_task_url' => '',
  'stop_on_errors' => false,
  'show_admin_interface' => true,
  'console_user' => 'admin',
  'version_builders' => array(),
  'version_filter' => array(),
);

title - 配置名称

migration_dir - 迁移目录（相对于 DOC_ROOT），默认：/local/php_interface/migrations 或 /bitrix/php_interface/migrations

migration_table - 存储迁移的数据库表，默认 sprint_migration_versions

migration_extend_class - 迁移类继承的类，默认 Version（你的类必须继承自 Version）

tracker_task_url - 轨迹器中任务链接的模板，在迁移描述中可以指定任务编号，例如 #12345，而模板中应有 $1 这样的结构，例如 https://redmine.ruby-lang.org.cn/issues/$1/，仅在管理后台有效

version_prefix - 迁移类标题，默认 Version（类的完整名称由标题和日期组成）

version_builders - 构造函数（允许执行某些任务的脚本）

stop_on_errors - 当出现错误时停止迁移执行，值选项：true | false，默认 false（不停止）

show_admin_interface - 在管理后台显示迁移服务，值选项：true | false，默认 true（显示）

console_user - 在控制台中启动迁移的用户，值选项：admin | login:userlogin | false，默认 admin（由管理员启动）

version_filter - 用于过滤和执行迁移列表的数组

没有任何参数是必需的。

如果配置中指定的迁移目录（migration_dir）或数据库表（migration_table）不存在，模块将创建它们。

当前的配置用星号 * 标记，如在管理后台的配置块和命令行中的 config 命令

在管理后台可以通过点击“切换”按钮切换配置，在控制台中，可以使用 --config={NAME} 参数到任何命令

示例

  • php migrate.php ls --config=release001（切换到 release001 配置并查看迁移列表）
  • php migrate.php up --config=release002（切换到 release002 配置并应用所有迁移）

模块会在切换后记住所选配置

迁移列表过滤示例

创建配置并设置过滤参数

<?php

$config = [
    'migration_dir' => '/migrations/',
];

if (\MyProject::IsDev()){
    $config['version_filter'] = [
        'env' => 'dev',
    ];
}

return $config;

在所需的迁移中指定此过滤器作为 $versionFilter 属性

<?php

namespace Sprint\Migration;


class Version20171219185225 extends Version
{

    protected $description = "";

    protected $versionFilter = [
        'env' => 'dev',
    ];

}

在查看迁移列表或应用/回滚所有迁移时，只会根据你的过滤器进行选择

也可以通过在迁移代码中定义 isVersionEnabled() 方法来实现相同的效果，该方法应根据某些条件返回 true 或 false，从而决定迁移是否出现在迁移列表中

<?php

namespace Sprint\Migration;

class Version20171219185225 extends Version
{

    protected $description = "";

    public function isVersionEnabled()
    {
        return false;
    }

}

创建迁移构造函数示例

创建构造函数类并在配置中声明它

<?php return array (
  'version_builders' => array(
    'MyVersion' => '\MyNamespace\MyVersion',
  ),
);

你的类必须继承自 Sprint\Migration\AbstractBuilder

实现迁移创建算法，类似于

构造函数 /modules/sprint.migration/classes/Sprint/Migration/Builders/IblockExport.php

及其模板 /modules/sprint.migration/templates/IblockExport.php

创建继承自你的类的迁移示例

在配置中指定你的类

<?php return array (
	'migration_extend_class' => '\Acme\MyVersion',
    //'migration_extend_class' => '\Acme\MyVersion as MyVersion',
);

创建此类

<?php
namespace Acme;
use \Sprint\Migration\Version;

class MyVersion extends Version
{
    // ваш код
}

创建 migrate.php add 迁移，结果

<?php

namespace Sprint\Migration;
use \Acme\MyVersion as MyVersion;

class Version20151113185212 extends MyVersion {

    protected $description = "";

    public function up(){
        //
    }

    public function down(){
        //
    }

}

开发者信息

不推荐使用模块的任何内部类。

保证从版本到版本的模块兼容性包括

  • 类 Version（你的迁移继承自它）的方法
  • 帮助器中的方法（在迁移类中包含）
  • commands.txt 中描述的控制台命令
  • migrations.{NAME}.php 配置

如果 up() 或 down() 方法中调用 return false 或发生异常，则迁移不会执行，否则迁移将成功执行

安装所有迁移时按从旧到新的顺序执行，回滚时则相反，从新到旧

当一次性安装或回滚所有迁移时，如果某个迁移执行失败，则该迁移会被跳过，并继续执行其后的迁移，这种行为可以通过配置文件中的参数 stop_on_errors = true 来调整，在这种情况下，迁移会在出现错误的地方停止。

迁移的代码应该是相互独立的，例如，如果一个迁移创建了信息块，那么在另一个迁移中添加任何属性之前，需要检查该信息块是否存在。

这些方法可以在 Sprint\Migration\Helpers\IblockHelper 中找到，例如 addIblockIfNotExists, addPropertyIfNotExists。

从控制台工作的时候，可以指定执行迁移的用户，这通过配置文件中的 console_user 参数来调节，参数值有：admin - 使用默认找到的第一个管理员登录（默认）login:userlogin - 使用用户登录名 userlogin false - 不进行登录

屏幕截图

админка