Tutorial

How to create a simple Silverstripe Module

This tutorial presents a way of creating a module so that you can share it 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 Silverstripe CMS 4+ are placed in the vendor catalog, then, that is where we would like to place our new module 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. You can do that 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:

{
"name": "silverstripe/installer",
"type": "silverstripe-recipe",
"description": "The SilverStripe Framework Installer",
"repositories": [
{
"type": "path",
"url": "../_modules/[your-module-catalog-name]"
}
],
"require": {
"php": ">=5.6.0",
"silverstripe/recipe-plugin": "^1.2",
"silverstripe/recipe-cms": "4.2.1@stable",
"silverstripe-themes/simple": "~3.2.0",
"[your-namespace]/[your-module-name]": "dev-master"
},
...
}

Make sure that your modules Composer file contains the things it needs, here is an example:

{
    "name": "[your-namespace]/[your-module-name]",
    "description": "Lorem ipsum",
    "type": "silverstripe-vendormodule",
    "homepage": "https://github.com/[your-github-space]/[your-module-name]",
    "keywords": [
        "silverstripe"
    ],
    "authors": [
        {
            "name": "Your Name",
            "email": "you@your-domain.com"
        }
    ],
    "license": "BSD-3-Clause",
    "support": {
        "issues": "https://github.com/[your-github-space]/[your-module-name]/issues"
    },
    "require": {
        "silverstripe/cms": "^4",
        "silverstripe/framework": "^4"
    },
    "require-dev": {
        "phpunit/phpunit": "^5.7"
    },
    "autoload": {
        "psr-4": {
            "[your-namespace]\\[your-module-name]\\": "src/"
        }
    },
    "autoload-dev": {
        "psr-4": {
            "[your-namespace]\\[your-module-name]\\": "tests/"
        }
    },
    "extra": {
        "installer-name": "[your-module-name]"
    },
    "prefer-stable": true,
    "minimum-stability": "dev"
}

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 update and and your module should be fetched by composer and created as a symlinked catalog under the vendor catalog.

And later, when you are done with development and testing of your module you can go ahead and publish it on GitHub and Packagist. And thanks to the fact that you are using Composer for your local development it will be a super easy thing to do.

And here is a tutorial regarding this part from the legend himself - 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.

{
    "name": "silverstripe/installer",
    "type": "silverstripe-recipe",
    "description": "The SilverStripe Framework Installer",
    "repositories": [
        {
            "type": "path",
            "url": "../_modules/[your-module-catalog-name]"
        }
    ],
    "require": {
        "php": ">=5.6.0",
        "silverstripe/recipe-plugin": "^1.2",
        "silverstripe/recipe-cms": "4.2.1@stable",
        "silverstripe-themes/simple": "~3.2.0",
        "[your-namespace]/[your-module-name]": "dev-master"
    },
    ...
}