You should be familiar with [Upgrading a project to Silverstripe CMS 4](upgrading_project) before reading this guide. The process for upgrading a Silverstripe CMS module is very similar to the process for Upgrading a Silverstripe CMS project. This guide focuses on highlighting ways in which upgrading a module differs from upgrading a regular project.
Making your module compatible with Silverstripe CMS 4 is only one part of the process. As a module maintainer, you also want to provide a good upgrade experience for your users. Your module can integrate with the [Silverstripe CMS upgrader](https://github.com/silverstripe/silverstripe-upgrader) just like the Silverstripe CMS core modules.
Your Silverstripe CMS 4 module should ship with a `.upgrade.yml` file. This file is read by the upgrader and will define new APIs introduced by the upgraded version of your module. Each step in this guide details what entry you should add to your module's `.upgrade.yml` file.
You'll want to run your module upgrade on a dedicated development branch. While it's possible to upgrade a module from within a Silverstripe CMS project, it's usually cleaner and easier to clone your module and work directly on it.
To require the development branch of your module in a Silverstripe CMS 4 project, you can use composer and prefix the name the name of your branch with `dev-`.
If the development branch is hosted on a different Git remote than the one used to publish your module, you'll need to add a VCS entry to your test project's `composer.json` file.
Before you can install your module in a Silverstripe CMS 4 project, you must update your module's `composer.json` file to require Silverstripe CMS 4 compatible dependencies. In most cases, you'll be better off updating your module's composer file manually, especially if your module only requires a small number of dependencies. You can use upgrader's `recompose` command if you want, but you'll need to carefully validate the resulting `composer.json` file.
Silverstripe CMS 4 modules are now installed inside the vendor directory. To get your module installed in the vendor directory, you'll need to update its `type` to `silverstripe-vendormodule`. You'll also need to add a dependency to `silverstripe/vendor-plugin`.
When upgrading a project, it is recommended to require recipes rather than modules. However, when upgrading a module, you want to limit the number of additional packages that gets installed along with your module. You should target specific packages that your module depends on.
For example, let's say your module adds a ModelAdmin to the Silverstripe CMS administration area without interacting with the CMS directly. In this scenario, the main module you need is `silverstripe/admin` which contains the `ModelAdmin` class and related administration functionality. If you update your `composer.json` file to require `silverstripe/recipe-cms`, you'll force your users to install a lot of modules they may not need like `silverstripe/cms`, `silverstripe/campaign-admin`, `silverstripe/asset-admin`, `silverstripe/versioned-admin`.
Choose constraints based on the minimum version of Silverstripe CMS 4 you are planning on supporting and allow your module to work with future releases.
For example, if your module requires an API that got introduced with the 4.1 release of `silverstripe/framework`, then that's the version you should target. You should use the caret symbol (`^`) over the tilde (`~`) so your module works with more recent releases. In this scenario, your constraint should look like `"silverstripe/framework": "^4.1"`.
If you run composer commands from your module's folder, a lock file will be created and dependencies will be installed in a vendor folder. You may also get `project-files` and `public-files` entries added under the `extra` key in your composer.json.
While these changes may be useful for testing, they should not be part of the final release of your module.
### Finalising the module's dependency upgrade
You should commit the changes to your module's `composer.json` and push them to your remote branch.
By this point, your module should be installable in a test Silverstripe CMS 4 project. It will be installed under the vendor directory (e.g.: `vendor/example-user/silverstripe-example-module`). However, it will throw exceptions if you try to run it.
As a module maintainer, you shouldn't be shipping any environment file with your module. So there's no need for you to run the upgrader `environment` command. If your module requires environment variables, you should update your documentation accordingly, but otherwise you can move on to the next step.
If your module codebase is structured in folders, you can use the `--psr4` and `--recursive` flag to quickly namespace your entire module in one command. This command will recursively go through the `code` directory and namespace all files based on their position relative to `code`.
[Learn more about configuring autoloading](https://getcomposer.org/doc/04-schema.md#autoload) in your `composer.json` file.
### Preparing your `.upgrade.yml` file
`add-namespace` will create a `.upgrade.yml` file that maps your old class names to their new namespaced equivalent. This will be used by the `upgrade` command in the next step.
Depending on the nature of your module, you may have some class names that map to other common names. When the `upgrade` command runs, it will try to substitute any occurrence of the old name with the namespaced one. This can lead to accidental substitution. For example, let's say you have a `Link` class in your module. In many project the word `Link` will be used for other purposes like a field label or property names. You can manually update your `.upgrade.yml` file to define a `renameWarnings` section. This will prompt users upgrading to confirm each substitution.
Make sure to commit this file and to ship it along with your upgraded module. This will allow your users to update references to your module's classes if they use the upgrader on their project.
### Finalising your namespaced module
By this point:
* all your classes should be inside a namespace
* your `composer.json` file should have an autoload definition
However, your codebase is still referencing Silverstripe CMS classes by their old non-namespaced names. Commit your changes before proceeding to the next step.
This step will allow you to update references to deprecated APIs. If you are planning on making changes to your own module's API, take a minute to define those changes in your `.upgrade.yml`:
You can define warnings for deprecated APIs along with a message. If there's a one-to-one equivalent for the deprecated API, you can also define a replacement. e.g.:
While Silverstripe CMS 4 projects can get away with directly referencing static assets under some conditions, modules must dynamically expose their static assets. This is necessary to move modules to the vendor folder and to enable the public web root.
This process is essentially the same for projects and modules. The only difference is that module static asset paths must be prefix with the module's name as defined in their `composer.json` file.
Depending on the nature of your module, you might need to perform additional tasks to complete the upgrade process. For example, the `framework` module ships with a file migration task that converts files from the old Silverstripe CMS 3 structure to the new structure required by Silverstripe CMS 4.
Extend [BuildTask](api:SilverStripe/Dev/BuildTask)s and create your own migration task if your module requires post-upgrade work. Document this clearly for your users so they know they need to run the task after they're done upgrading their project.
The upgrader can be run on projects that have already been upgraded to Silverstripe CMS 4. As you introduce new API and deprecate old ones, you can keep updating your `.upgrade.yml` file to make it easy for your users to keep their code up to date. If you do another major release of your module aimed at Silverstripe CMS 4, you can use all the tools in the upgrader to make the upgrade process seamless for your users.
