Creating a SilverStripe 4 module
Tips for creating a SilverStripe 4 module with PHPStorm and Composer
SilverStripe 4 is a quite big step up from the previous version 3 when it comes to modern code structure. And perhaps the biggest change from version 3 is of course that all classes now use namespacing.
All this is really nice but if you are accustomed to working with SS3 it can be a bit confusing too. Therefore I am going to share with you some tips for how you could work with Composer when creating a module for SilverStripe 4. I use OSX, so the instructions in this article are for that platform.
And these instructions are for creating a module that you are meaning to share with others and therefore want to use Composer locally for testing it out. If you just want some code separation you could always add a local module next to your app catalog in your project.
Since all installed modules in SS4 are placed in the vendor catalog thats where we would like to our new module to be located as well. To accomplish this you can work with a local catalog when you are developing your module. Then refer to that catalog in your SS4 projects Composer file. Do it like this:
- Start a new clean SilverStripe project by installing it with composer in your local development environment. This will be your test project into which you will import the module that you work on. See this link for instructions on how to set up a new SilverStipe site locally: https://www.silverstripe.org/download/
- Create a folder in your local environment where you can keep the modules that you are working on. I have such a folder in my local "htdocs" folder (one "step up" from the site folders) and have named it "_modules" so that it gets located at the top of the list in Finder.
- In the "modules" folder create a folder for the module that you want to work on and place all code there. The structure of the code in your module should follow the guidelines listed under "Custom Code Structure" in this page: https://docs.silverstripe.org/en/4/getting_started/directory_structure/
- Open PHPStorm and create a project out of the clean SilverStripe installation that you made.
- Then add your module and its content as an additional content root in the project: https://www.jetbrains.com/help/phpstorm/configuring-content-roots.html
By configuring your module as a secondary content root you get access to all the classes etc from your main project, which means that you can rely on PHPStorms functions for helping you out with importing classes from SilverStripe and other resources that reside in your main project that your module will need.
Import your local module to the test project
Add a Composer file to your module. Here is whats needed in there: https://docs.silverstripe.org/en/4/developer_guides/extending/how_tos/publish_a_module/
- Open the test projects Composer file and add a reference to your local module by adding it as a path reference, like this:
- Make sure that your modules Composer file contains the things it needs, here is an example:
- Things to note here is that the name should be the same as what you refer to when referring to your module in the test projects composer file.
- The type must be silverstripe-vendormodule if you want to publish the module later on.
- The autoload->psr4 parameter must have the namespace of your module pointing to the catalog where the code for the module is located (should be src).
- Now its just to open up the test projects folder in the Terminal and run
composer updateand your module should be fetched by composer and created as a symlinked catalog under the vendor catalog.
Then when you are done with the development and testing of your module you can go ahead and publish it on GitHub and Packagist. And because of the fact that you already are using Composer for your local development it will be a super easy thing to do.
And here is a tuturial of that part from the excellent Uncle Cheese, enjoy: https://www.silverstripe.org/learn/lessons/v3/publishing-your-own-module
PS. One last thing, dont forget to set your test site in developer mode before starting by adding
SS_ENVIRONMENT_TYPE="dev" to the .env file that replaces the _ss_environment.php file from SS3.