Matomo requires various packages to run. Those requirements are managed using Composer.
If for some reason a new requirement would be needed, we need to require it using composer.
composer require package/name ^1.2.3
If the required package is used for development only, it should be excluded for other environments using:
composer require-dev package/name ^1.2.3
Almost all requirements in our composer.json are defined in a way that allow minor and/or patch release updates without any adjustments in composer.json.
As there are normally no problems expected for those updates there is an automatic GitHub action that automatically checks for updates and creates a Pull Request if any are available.
Every 6 months we should check for possible major updates of our requirements. These can only be upgraded if:
In other cases we usually cannot upgrade to a major update and need to wait for the next Matomo major release. This is to keep backwards compatibility with Matomo for WordPress, the Cloud, and also all the third party plugins on the Marketplace and the many more that aren't on the Marketplace.
There are no breaking changes is usually not a reason to be able to upgrade since there is usually always a breaking change, even if it's just a method definition that changes and then causes issues for Matomo for WordPress.
For Matomo for WordPress major component updates cannot only cause issues with code that we manage, but also cause compatibility issues with the over 50,000 WordPress plugins that may use a different version of that component. Most WordPress plugins use older versions of these components where they have different classes and different method definitions and from past experience this will cause Matomo for WordPress to break suddenly, sometimes even their entire WordPress installation. This can be especially annoying with Auto-Updates in WordPress etc. We wouldn't want to break someone's installation in a minor version update whenever possible.
Support for a newer PHP major version may be a reason to upgrade a component. However, if any possible we want to avoid this and rather fork the component and apply the fixes ourselves assuming it wouldn't be a 4+ days of work to do this. If it's a lot of work then we would need to assess the risk together.
Composer allows viewing all available updates for installed packages:
composer outdated
If there are major updates available we should go through them and update each. As some updates might require code changes on our side it is best to only update one requirement after the other. Otherwise it will be harder to identify why e.g. some code breaks or why some tests start failing. Updating a single requirement can be achieved this way:
composer update --with-dependencies package/name. You need to replace package/name with the name of the requirement, like phpmailer/phpmailer.composer.json and composer.lock.Note: we use the --with-dependencies option, to ensure all dependencies are updated if needed.
It might be possible that updating some dependencies might not work due to the PHP version requirements of Matomo.
Some packages like PHPUnit might already require a higher PHP version than Matomo.
This causes composer not to update to newer versions or a composer install to fail when updating the dependency in composer.json.
If an update to a newer version is mandatory there are basically two possible options * Increase the PHP version requirement (which is usually only done for major releases) * create a fork of the package and lower the minimum requirement (if the code really works with our minimum PHP requirement)
Note: If you want to install newer requirements locally for testing purpose, you can achieve this using the --ignore-platform-reqs option of composer.
We are managing some of our core components and libraries through composer as well. Whenever we release a new version of those packages we should directly issue an update of the composer requirement in Matomo.
composer update matomo/$COMPONENT_NAME. You need to replace $COMPONENT_NAME with the name of the component. For the cache component you may need to execute composer update matomo/cache matomo/doctrine-cache-fork.composer.json and composer.lock.