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:

$ 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)
    lib/Logger/LaminasMailHandler.php

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:

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

   use User\User;
  -use Zend\Authentication\AuthenticationService;
  -use Zend\Authentication\Result as AuthenticationResult;
  +use Laminas\Authentication\AuthenticationService;
  +use Laminas\Authentication\Result as AuthenticationResult;
  -use Zend\Stdlib\ArrayUtils;
  +use Laminas\Stdlib\ArrayUtils;
  

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

$ composer config repositories.laminas composer https://laminas.mwop.net/repo/testing
$ composer install

Step 5: 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 https://laminas.mwop.net/repo/testing
$ 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.