迁移到 Laminas

导航

迁移到 Laminas

Laminas 及其子项目是 Zend Framework 及其子项目开源版本的延续，该项目将作为正式分支，原有官方项目将进行归档并逐渐废弃。

在本文档中，我们提及的 "Zend Framework" 均表示最初由 Zend Framework 项目提供的包文件 以及其子项目 包括 Apigility 或 Expressive.

可以进行的迁移:

  • 依赖 Zend Framework 项目，或者其组件的单个组件或者应用。
  • 依赖 Zend Framework 组件的库。

1. 准备工作

确保你安装了最新版本的 Composer

我们的插件依赖 Composer 并需要 1.7.0 及以上版本。 如果你不确定当前使用的版本，可以运行 composer --version 来查看版本。 如果版本过低，运行 composer self-update 进行升级。

（目前唯一的限制在于，我们默认你使用的是 Composer 安装的 Zend Framework。）

确保你使用的版本控制软件管理的你当前代码

迁移工具会修改你的代码，升级模板，修改composer.json文件，移除 composer.lock vendor/ 以及其子目录，以及一些其他的更改。 如果你想要在出问题后回滚你的代码，请务必确保你使用了版本控制软件来管理你的代码！

我们推荐 Git. 如果你的应用当前未使用版本公职软件，你可以安装 git 并进行如下操作: 

$ cd path/to/your/application
$ git init .
$ echo "vendor/" > .gitignore
$ git add .
$ git commit -m 'Initial import'

接下来你就可以随时查看你对代码进行了哪些更改。

2. 安装 laminas-migration

这里有三种安装方式:

  1. 通过 composer 的 require 命令 (推荐)
  2. 直接 clone
  3. 使用本地环境变量

通过 composer 的 require 命令

Composer 允许你通过全局方式调用安装包文件。如果你使用当前当时： 

$ composer global require laminas/laminas-migration

这样做需要你确保环境变量 $PATH 指向了 Composer安装包的子目录 vendor/bin/。你可以使用如下命令来查找已经配置好的目录： 

$ composer global config home

添加环境变量

环境变量 $PATH 配置取决于你当前的操作系统。

对于 Linux, Mac, 及其他类 *nix 系统来说，你可以在 profile 配置(e.g., $HOME/.bashrc, $HOME/.zshrc, $HOME/.profile, etc.)文件中添加如下配置： 


    export PATH={path to add}:$PATH
    // 例如 Linux 中在我们需要在用户目录下的 .profile 文件中中添加如下代码：
    export PATH=$HOME/.config/composer/vendor/laminas/laminas-migration/bin:$PATH
    // 然后执行即可
    source .profile

对于 Windows 系统来说操作会稍微复杂；参考： this HOWTO

直接 clone

Clone仓库:

$ git clone https://github.com/laminas/laminas-migration.git

安装依赖:

$ cd laminas-migration
$ composer install

目前，我们同样 $PATH 中添加了 bin/ 目录，(参见以上 添加环境变量部分) 将脚本目录 bin/laminas-migration 软连接到 $PATH 中，或者使用 shell 脚本来创建 bin/laminas-migration 的别名： 

# 添加到PATH:
$ export PATH=/path/to/laminas-migration/bin:$PATH
# 添加软连接:
$ cd $HOME/bin && ln -s /path/to/laminas-migration/bin/laminas-migration .
# 创建别名:
$ alias laminas-migration=/path/to/laminas-migration/bin/laminas-migration

3. 运行迁移命令

一单你安装了 laminas-migration 工具，进入你需要迁移项目的目录，运行： 

$ laminas-migration migrate

你可能需要一次或者多次使用 --exclude 或 -e 参数 来 排除 不需要重写的目录，或者使用 --filter 或 -f 参数来使用正则表达式 指定 需要重写的文件。

举个例子， 排除 data/ 子目录, 可以运行:

$ laminas-migration migrate -e data

保守的迁移方式

如果你有升级路径的限制，并且不想将任何包升级到最新的版本，你可能需要使用 --keep-locked-versions 来确保composer.json中所有的包都将从 composer.lock 中获取版本信息来安装。

我们鼓励你采用 非保守 的方式来迁移，以避免因为使用旧版本的包二导致迁移laminas中存在的问题。

如果你使用这种方式升级之后遇到了问题，我们将不会解决方案，因此我们强烈建议你升级到最新版。 

$ laminas-migration migrate -e data --keep-locked-versions

我们可以通过命令查看其他可用的方法:

$ laminas-migration help migrate

4. 验证修改 (可选)

此时，你可以查看进行的更改。例如，如果你使用git，你可以使用如下命令来查看更改： 

$ git diff

你将会看见进行如下更改:

  • 重名了了ZF组件的文件或者类。例如My\Models\ZendMailTransport 重命名成了 My\Models\LaminasMailTransport。 这样的重命名方式通常来说是可取的，和这个类有关的所有引用也将会被重写。 然而，如果有外部代码依赖他，同样也需要去验证。
  • 配置的名称也将会被修改。其中大多数的更改是为了匹配 Laminas 库本身。 但是还是需要你检查其中是否包含了你自定义代码的部分。

5. 安装依赖

一旦迁移并且执行了相关验证后，就可以开始安装依赖了： 

$ composer install

6. 测试

运行单元测试，并执行端到端的测试，无论如何都要使用一些方式来验证你的应用。

有任何不能执行的地方，都可以将其细节部分报告给我们：

  • 在你出现问题的特定包中报告给我们。
  • 或者通过Laminas Slack 的 #laminas-issues 渠道。

提交迁移 (可选)

之前我们使用了 --keep-locked-versions 参数, 你肯定需要对比 composer.json 以便恢复旧的程序包 以及移除迁移之前的程序使用的不必要了程序包。 清理完 composer.json 之后，你可能需要使用如下的命令来更新 composer.lock ： 

$ composer update --lock

总结

迁移步骤如下:

$ composer global require laminas/laminas-migration
$ cd some/project
$ laminas-migration migrate # maybe with -e data or -e data/cache
$ composer install

问题咨询

迁移到 Laminas