Testing migrating to Laminas

Written by Rob Allen / Original link on Nov. 6, 2019

Zend Framework is renaming to Laminas and all the source code is moving to a new GitHub organisation. Implicitly this means a new PHP top level namespace. As you can imagine, this implies that a lot of our code will need to change, so Matthew, Michał and the team have been writing migration tooling to make this easier.

It's now time to test it and they need all the help they can get on real-world codebases, so let's look at how we do that. I have a relatively large Slim Framework application that uses a variety of Zend Framework components including Zend-Authentication, Zend-Acl, Zend-Config, Zend-Form, Zend-InputFilter and Zend-Mail, so maybe it's a good case-study.

Note: The migration-tooling is currently in testing and not ready for production!

Rather helpfully Matthew has written a guide on how to test the Laminas Migration, so we'll follow the instructions.

Step 1: Install laminas-migration

I already have a global Composer set-up and its bin directory is on my path, so I ensured it was up to date and then installed laminas-migration into it:

$ composer global update
$ composer global require laminas/laminas-migration

(As a side-note, I see that the tools I have in my global composer have changed over time as I no long have PHPUnit globally, but have added, changelog-generator)

Step 2: Create a new branch

Don't work on the main line directly, so next we create a branch:

$ git checkout -b migrate-to-laminas
Switched to a new branch 'migrate-to-laminas'

Step 3: Run the migration

Now we can run the migration tool itself:

$ laminas-migration migrate -e docs

The -e option allows you to excluded directories; I don't want my docs directory to be updated.

Interestingly, the tool provides no output on success, but running git status shows that things happened!

$ git status
On branch migrate-to-laminas
Changes not staged for commit:
  (use "git add/rm ..." to update what will be committed)
  (use "git restore ..." to discard changes in working directory)
    modified:   app/modules/Page/src/AdminPageController.php
    modified:   app/modules/Page/src/EditPageForm.php
    modified:   composer.json
    deleted:    composer.lock
    modified:   tests/Unit/Page/AdminPageControllerTest.php
    modified:   tests/Unit/Page/EditPageFormTest.php
    deleted:    lib/Logger/ZendMailHandler.php

Untracked files:
  (use "git add ..." to include in what will be committed)

no changes added to commit (use "git add" and/or "git commit -a")

I've removed a lot of lines, but a few things are of interest:

Step 4; Run composer install

We need to bring our dependencies back. As we're in testing, we need to manually add the Laminas repository to composer.json, but won't need this after the official migration from Zend Framework to Laminas.

$ composer config repositories.laminas composer
$ composer install

Step 4; Test!

Now we just need to test that everything still works. Firstly, I ran my unit tests and they passed. Then we ran the integration tests and did manual testing. All continued to work.

We'd love it if you could report your results on the #laminas-migration-testing channel on the ZF Slack (invite link). Alternatively, if you're not on Slack, leave a comment on the gist or ping @getlaminas on Twitter.

That's it

That's all that's required. The summary based on Matthew's gist is:

$ composer global require laminas/laminas-migration
$ cd some/project
$ git checkout -b laminas-migration
$ laminas-migration migrate -e data
$ composer config repositories.laminas composer
$ composer install
$ vendor/bin/phpunit

That's not a lot of work.

If you have any Zend Framework components in your application, please test the migration to Laminas. Matthew and Michał have worked really hard on this to make it very easy for all of us and it would be great if we can iron out any kinks before we go live with the change.

roballen calevans calevans roballen

« First steps with Windows on Vagrant - Embedding Notist slides »