Modules guide

Modules are the fundamental containers of functionality in Cherrycake apps.

Modules pack the process-specific logic of an app and have some additional benefits and important differences over regular classes. Modules come in two flavors:

• Core modules

  • Ready-made modules provided by Cherrycake, they implement all the process-specific functionality behind the Cherrycake architecture.

  • Cherrycake comes with a bunch of Core modules aimed to help you build your app. From the main Actions module that routes the requests to your app to modules to work with Css and JavaScript files, to control the user Session, to access Database and Cache servers, automate tasks, store logs and much more.

• App modules

  • Modules created by the developer when creating a new application, which will be in charge of all the processes in your App. You'll have to decide a great App module structure based on the needs of your application.

  • A really simple example of an App module would be the HelloWorld module we created in the Getting started section, but a more complex scenario like an e-commerce site might need modules like Products, Cart, Payments, ProductCategories, Search and so, for example.

Loading modules

Modules must be loaded before they can be used, they can be loaded in three ways:

• As a Base core module, when initializing the engine. Base core modules are loaded right when the engine is initialized. You specify your base modules in the baseCoreModules setup key of Engine::init. See the Deep lifecycle section for more details on this.

• As a dependent module, when they're required by other modules in their Module::dependentCoreModules or Module::dependentAppModules properties. See Specifying module dependencies.

• At any point in your code, programmatically. Just by calling Engine::loadCoreModule or Engine::loadAppModule.

Accessing modules

Once they're loaded, modules are always accessible as properties of the engine. For example, the Patterns module will be available in your code by doing this:

global $e;
$e->Patterns->out("Pattern.html");

Modules lifecycle

When a module is loaded for the first time during a request, this is what happens:

1. The module file is loaded, and the module instantiated.

2. The init method of the module is called, which does the following:

   1. If the module has some dependencies on other modules, they're loaded.

   2. If the module has a configuration file, it is loaded.

   3. Any other module-specific initialization is done.

3. When the engine request has finished, or if any module initialization failed, the end method is called.

App module files

The App modules you create must be stored in the /src directory of your app, and also in their own subdirectory, which has to be named exactly like your module. The file name has to be also the exact name of you module, plus the .php extension.

You can change the default /src directory for the one of your choice by setting the appModulesDir setup key when calling Engine::init

For example, if you were to create a module called Products, it should be stored on the /src/Products/Products.php directory.

Note that both the subdirectory and the file name itself are case-sensitive.

Modules configuration file

Modules can have their own configuration file where all settings related to them should be entered. Configuration files are stored under the /config directory by default, but you can set your own directory specifying the configDir setup key in Engine::init

Module configuration files must have a name that matches the module name, even with upper and lowercase characters. For example, the configuration file for the Database module must be called /config/Database.config.php

Module configuration files must declare a hash array named in the syntax $<ModuleName>Config. For example, this is how a configuration file for the HtmlDocument module would look:

<?php

namespace Cherrycake;

$HtmlDocumentConfig = [
    "title" => "Web page title",
    "description" => "Web page description"
];

You can set default configuration values that will be used if the configuration file didn't exist, or if a specific configuration key was not set on the configuration file. To do so, set the Module::config property of your module, like this:

class MyModule extends \Cherrycake\Module {
    protected $isConfigFile = true;
    protected $config = [
        "title" => "Default title",
        "description" => "Default description"
    ];
}

To get a configuration value from a module, use the Module::getConfig method, for example:

$this->getConfig("title");

See this example working in the Cherrycake documentation examples site.

Modules constants file

Modules can have a constants file specifically aimed to hold their related constant declarations so they will be available anywhere in your code even if the module has not been loaded or initialized. Use them to store constants that are intended to be used outside the module itself.

For example, the Database module declares some useful constants in its constants file like DATABASE_FIELD_TYPE_INTEGER, DATABASE_FIELD_TYPE_TIMESTAMP and DATABASE_FIELD_TYPE_STRING.

Constants files are stored in the same directory as the module file, and the file name has to match the exact name of you module, plus the .constants.php extension. For example, the constants file for a module calledProducts would be stored in /src/Products/Products.constants.php, and it might look like this:

<?php

namespace CherrycakeApp;

const PRODUCTS_SIZE_SMALL = 0;
const PRODUCTS_SIZE_MEDIUM = 1;
const PRODUCTS_SIZE_SMALL = 2;

Specifying module dependencies

When your module makes use of another modules regularly, you should specify them as a dependency.

Set the dependentCoreModules property of your module to specify which Core modules are required by yours, and the dependentAppModules to specify dependencies between your own modules, here's an example:

namespace CherrycakeApp\MyModule;

class MyModule extends \Cherrycake\Module {
    protected $dependentCoreModules = [
        "Database",
        "Patterns"
    ];
    
    protected $dependentAppModules = [
        "MyOtherModule"
    ];
}