Modules
What is a module?
A module is a group of independent MVC elements. The use of modules allows for re-usability and encapsulation of your code. A module typically resides within an application sub-directory named modules. It is suggested to take advantage of modules whenever you're working on a large project, of which you believe it's code-base will be more than just a few lines of code. It will help you to keep things neatly in order.
A module can operate independently, like for example a blog module or an album module. You can route directly to the module controllers, without having to access any global code. Modules can also be used in a true HMVC context, where controllers call other controllers, which will produce (a part of) the result needed to generate the result of the page request.
Module configuration
To be able to use modules, you will have to tell FuelPHP where your modules are stored. By default, this is in the modules folder of your application. You use the 'modules_path' setting in your applications config.php file to define your module path. You can also define multiple paths. If you do, they will be searched in the sequence you have defined them.
/**
* To enable you to split up your application into modules which can be
* routed by the first uri segment you have to define their basepaths
* here.
*/
'module_paths' => array(
APPPATH.'modules'.DS, // path to application modules
APPPATH.'..'.DS.'globalmods'.DS // path to our global modules
),
When you define your paths, make sure they end with DS, the FuelPHP platform independent directory separator.
Module namespace
One of the problems often encountered when working with independently developed code are class name collisions. For example, a lot of modules come with an admin controller. To avoid collisions, in FuelPHP every module lives in its own PHP namespace, which must be named identical to the folder name of the module.
<?php
/**
* Module controller in the MyModule module
*/
namespace MyModule;
class Controller_Widget {
// put your controller code here, just like for an application controller
}
Module folder structure
You start creating a module by creating a folder for your new module in the modules folder you have defined in the configuration. The folders name determines the name of the module, and the name of the namespace for the classes in the module. This name is also used in the URI if you want to route to the modules controllers, or as part of the Request in case of an HMVC call.
As a module can be viewed as a self contained part of the application, you'll notice that the module folder structure is very familiar. It is the same as the structure of the application folder. The following folder structure is supported for a module:
- classes
- controller
- model
- view
- config
- lang
- views
At the time of writing, tasks and migrations are not yet supported within a module.
Module routing
To be written.
HMVC requests
Besides using modules as a way of separating logically independent parts of your application, you can also use module controllers in an HMVC context, where one of your application's controllers calls one of more module controllers to create the final result of the URI requested.
One common use of this is when you use a theme or template engine to generate your pages, where every page is divided into sections, and sections are populated by widgets. By using modules to produce the widget output, you can create a highly modular application, with easy to re-use components.
You call a module controller method using the Request class:
// fetch the output of a mymodule controller method
$widget = Request::factory('mymodule/mycontroller/mymethod/parms', false)->execute()->output;
Note that you have to use 'false' as second parameter to the factory() call, to prevent your URI to be routed. If you don't, and you request a non-routable URI, you will end up with a 404 error!
Using static calls
It is also possible to call static methods in a module class. For this to work, FuelPHP needs to be able to autoload the class when you reference it in your code. Which means you will have to tell FuelPHP where to find the module. There are two ways to do this.
You can preload the module by specifying the module to load in the 'always_load', 'modules' setting of your applications config.php file:
'always_load' => array(
/**
* These modules are always loaded on Fuel's startup. You can specify them
* in the following manner:
*
* array('module_name');
*
* A path must be set in module_paths for this to work.
*/
'modules' => array('mymodule'),
You can also add the module manually at runtime, before you use any of the static methods:
// add the module MyModule to FuelPHP
Fuel::add_module('mymodule');
You then call the module class like this:
\mymodule\myclass::mymethod('parms');