Packages in composer

profile picture

Kevin Engineer

12 Jan 2017  ·  2 min read


In this tech tutorial, we show you how to change a library package name in Composer… Use it wisely!

At November Five, we use Symfony as a framework for web-based projects, with Composer as the package manager.

Recently we ran into a problem in one of our projects, when we wanted to change a package name in Composer. So in this post, we’d like to share our solution.

First of all: changing the package name of a library in Composer is something you should (almost) never do. It’s strongly discouraged, and with good reason. However, every rule has an exception: in some cases, it’s the only way to keep libraries up to date. In our case, this exception was our company re-branding: in 2016, we changed our name from Appstrakt to November Five, and so we had to update the package name to keep our namespaces consistent.

Diving in

Let’s say we have following git flow:

Git Flow

This is a normal git flow we use for every project. In this example, we have two projects, named Legacy and Future. Legacy already has the appstrakt/user-bundle installed in its composer.json:

"appstrakt/user-bundle": "1.1.0"

We want to update our libraries and projects to our new name, November Five, so we change the namespace of our library and update our git flow as follows:

New flow

As I said before, our Legacy project has version 1.1.0 – this will continue to work. For our Future project, we started using:

“november-five/user-bundle”: “2.0.0”

After a while, we noticed that our Legacy project had a bug in its user-bundle, a bug which was already fixed in version 2.0.0. The main problem here was that we couldn’t easily update to a next major version without breaking changes. To account for this, we simply made a hotfix branch which only contains the fix for version 1.1.0, and tagged it as version 1.1.1:

Final flow

In our Legacy project, we thought we could simply update our bundle to version 1.1.1 and run composer update appstrakt/user-bundle and it would simply install version 1.1.1. Sadly – you guessed it – things were not that easy.

Composer simply errored: it couldn’t find any appstrakt/user-bundle with version 1.1.1. The question we asked ourself was “Well, why not?”

This is when we realised that apparently, Composer ignores the namespace on the hotfix branch and only checks the namespace on the master branch. To fix the problems with our Legacy project, we had to rename the appstrakt/user-bundle to november-five/user-bundle.

To do that, the following was set in our composer.json:

“november-five/user-bundle”: “1.1.1”

After that, Composer was able to find version 1.1.1 and installed it without a problem.