Migration to Laminas

Migration to Laminas

Laminas and its subprojects are an open source continuation of Zend Framework and its subprojects, and are the official fork of the project now that it has been archived and abandoned.

For purposes of this document, when we refer to "Zend Framework", we mean any package originally provided by the Zend Framework project or its subprojects, including those provided by Apigility or Expressive.

You can migrate:

  • Individual projects or applications that depend on Zend Framework, or have dependencies on components that depend on Zend Framework.
  • Libraries that depend on Zend Framework components.

1. Preparation

Ensure you have an up-to-date Composer

Due to features of Composer our dependency plugin uses, we require Composer 1.7.0 and up. If you're unsure what version you are on, run composer --version. If you are on an older version, run composer self-update.

(We assume you use Composer to install Zend Framework, as it is the only supported mechanism currently.)

Make sure your code is under version control

The migration tool changes source code, updates tempaltes, modifies your composer.json and removes your composer.lock and vendor/ subdirectory, among other things. If you want to be able to roll back in the case of a problem, please make certain your code is under version control!

We recommend Git. If your application is not currently under version control, install git, and then:

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

You will then be able to see what changes you introduce.

2. Install laminas-migration

There are three ways to install the tool:

  1. Via a global composer requirement (recommended)
  2. Via cloning
  3. As a local dependency

Via a global composer requirement

Composer allows you to require packages in a global context as well. If you choose this option, you will run:

$ composer global require laminas/laminas-migration

It is up to you to ensure that the vendor/bin/ subdirectory of your global Composer installation is in your environment $PATH. You can locate the global context directory using:

$ composer global config home

Adding to the PATH

The mechanism for adding to your environment $PATH variable depends on your operating system.

For Linux, Mac, and other *nix variants, you can do so by adding a line like the following at the end of your profile configuration file (e.g., $HOME/.bashrc, $HOME/.zshrc, $HOME/.profile, etc.):


    export PATH={path to add}:$PATH
    

For Windows, the situation is a bit more involved; this HOWTO provides a good tutorial on the subject.

Via cloning

Clone the repository somewhere:

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

Install dependencies:

$ cd laminas-migration
$ composer install

From there, either add the bin/ directory to your $PATH (see the note on adding to the PATH, above), symlink the bin/laminas-migration script to a directory in your $PATH, or create an alias to the bin/laminas-migration script using your shell:

# Adding to PATH:
$ export PATH=/path/to/laminas-migration/bin:$PATH
# Symlinking to a directory in your PATH:
$ cd $HOME/bin && ln -s /path/to/laminas-migration/bin/laminas-migration .
# creating an alias:
$ alias laminas-migration=/path/to/laminas-migration/bin/laminas-migration

As a local dependency

In this case, require it as you would any other dependency:

$ composer require --dev laminas/laminas-migration

For purposes of usage, when we refer to the laminas-migration CLI tool, the path will be ./vendor/bin/laminas-migration.

If you choose this option, make sure you remove the migration tooling when you are done with your migration:

$ composer remove --dev laminas/laminas-migration

3. Run the migration command

Once you have installed the laminas-migration tooling, enter a project you wish to migrate, and run the following:

$ laminas-migration migrate

You may want to use the --exclude or -e option one or more times for directories to exclude from the rewrite, or the --filter or -f option one or more times to provide regular expressions of which files to include in the rewrite.

As an example, to exclude the data/ subdirectory, you could run:

$ laminas-migration migrate -e data

For more information on available options, use the command's help function:

$ laminas-migration help migrate

4. Verify changes (optional)

At this point, you can verify that the changes look correct. As an example, if you use git, you could run the following command to determine what has changed:

$ git diff

Things you might want to look for:

  • Renaming of files or classes in your own code that reference ZF components. As an example My\Models\ZendMailTransport might get renamed to My\Models\LaminasMailTransport. Such renames are typically okay, and any references to those classes will be rewritten as well. However, if external code may depend on them, you should verify.
  • Changes to configuration keys. Most of these are made to match changes in the Laminas libraries themselves, but you should check to see if they are specific to your own code.

5. Install dependencies

Once migration is done and you've performed any verification steps you need, install dependencies:

$ composer install

6. Test

Run your unit tests, do end-to-end tests, whatever — but exercise the application in some way.

If anything does not work, determine the specifics, and report either:

  • In the repository of the specific component where you are observing problems.
  • The #laminas-issues channel of the Laminas Slack.

Summary

To summarize the steps to migrate:

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

Questions?