District modules

This project uses a module design pattern where functionality is split into individual modules rather than everything mashed together. This ensures a clear separation of concerns and easier packaging and extending of functionality.

The package used to facilitate this pattern is Laravel Modules. It is recommended you thoroughly read the docs as it will likely answer any questions you have about this approach.

Creating a new module

Documentation here and basic example:

lando artisan module:make my_module

Note that each District module extends the Core module which is a hard dependency.

Module generator stubs and helpers

Have a read of this page for ways to accelerate module generation, specifically stubs that suit the structure of this site. Stubs are found in stubs/nwidart-stubs and are use with the above module:make command but also module:make-**** commands (eg lando artisan module:make-model Posts PostsModule).

Adding dependencies to your module

In the module folder edit composer.json and add your dependency then cd to project root and run lando composer update, this will install all dependencies from all modules using composer-merge-plugin.

Adding config to your module

Ref. to "Config load order" readme.

  1. Add a config file to your module under Modules/MyModule/Config/
  2. Determine if you want this config to either:
    • Override default app config or third party package config
    • Or get overridden by the app
  3. Define the config file name in your module service provider (Modules/MyModule/Config/MyModuleServiceProvider) by adding to the property $configsOverrideable or $configsOverriding

Adding middleware to your module

Each module service provider should extend Modules\Core\Providers\BaseModuleServiceProvider that takes care of populating any middleware defined by the module thanks to its own Http\Kernel.

In your module service provider you can populate arrays for each middleware type, e.g:

  • protected array $globalMiddleware = [Middleware\TrustProxies::class]
  • protected array $routeMiddleware = ['can' => \Illuminate\Auth\Middleware\Authorize::class]
  • protected array $groupMiddleware = ['web' => [Middleware\EncryptCookies::class,]]

Example

In your module dir, add Modules/MyModule/Config/myconfig.php, then in your MyModuleServiceProvider add

protected array $configsOverriding = ['myconfig'];

and finally access config with

config('myconfig');

Module dependency management

Some District Modules depend on external packages and also depend on each others. Make sure to use composer to define all of your module dependencies.

  1. In MyModule/composer.json specify a version, by default 1.0.0
  2. Add external packages required by your module under require in MyModule/composer.json then run composer update from the project root.
  3. Make sure to include all dependencies in composer.json. If you are unsure, you can double check your module interdependencies at the URL /core/devtools/modules-list
  4. Listing interdependencies in composer.json will ensure that errors are thrown if the module is removed from the repo and when running composer install (part of build process) or composer require

Config load order

Config files are loaded in the following order:

  1. App (app/config)
  2. Third party modules
  3. Modules (Modules/YourModules/Config). The order of merging then depends on how the config is defined. See here "Adding config to your module".