Developing software in the Real World

Testing migrating to Laminas

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:

(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:

Step 3: Run the migration

Now we can run the migration tool itself:

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!

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

  • All uses of a Zend component are replaced with Laminas

    In my case, this is nearly always the set of use statements at the top.

    For example, an arbitrary git diff shows:

  • Your own classes containing Zend are renamed

    I have a class called ZendMailHandler. This was renamed to LaminasMailHandler and hence the filename lib/Logger/ZendMailHandler.php was renamed to lib/Logger/LaminasMailHandler.php.

    Note that function names, variable names, strings and comments which use the wordZend are not changed, so you’ll have to do them yourself if you want to.

  • composer.json is updated. vendor and composer.lock are removed

    After updating composer.json, the migration tool has blown away my vendor directory and removed composer.lock, so I’ll need to run composer update to get them back.

  • 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.

    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:

    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.

Thoughts? Leave a reply

Your email address will not be published. Required fields are marked *