PHPackages dhii/module-interface - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [Utility & Helpers](/categories/utility) 4. / 5. dhii/module-interface ActiveLibrary[Utility & Helpers](/categories/utility) dhii/module-interface ===================== Interfaces for modules v0.1(6y ago)6129.9k↓46.7%1[2 PRs](https://github.com/Dhii/module-interface/pulls)4MITPHPPHP ^5.3 | ^7.0CI failing Since May 6Pushed 2y ago4 watchersCompare [ Source](https://github.com/Dhii/module-interface)[ Packagist](https://packagist.org/packages/dhii/module-interface)[ RSS](/packages/dhii-module-interface/feed)WikiDiscussions 0.3.x Synced 1mo ago READMEChangelog (5)Dependencies (9)Versions (11)Used By (4) Dhii - Module Interface ======================= [](#dhii---module-interface) [![Continuous Integration](https://github.com/Dhii/module-interface/actions/workflows/continuous-integration.yml/badge.svg)](https://github.com/Dhii/module-interface/actions/workflows/continuous-integration.yml)[![Latest Stable Version](https://camo.githubusercontent.com/5a458a9f9f9016293e18859d8b447009dafd41dcef66e80ec76368b5ef197a71/68747470733a2f2f706f7365722e707567782e6f72672f646869692f6d6f64756c652d696e746572666163652f76657273696f6e)](https://packagist.org/packages/dhii/module-interface)[![Latest Unstable Version](https://camo.githubusercontent.com/2c99661422ccc41a8dc1816e527cb36beaa59e2e38b16b28f681a67bab336041/68747470733a2f2f706f7365722e707567782e6f72672f646869692f6d6f64756c652d696e746572666163652f762f756e737461626c65)](//packagist.org/packages/dhii/module-interface) Details ------- [](#details) This package contains interfaces that are useful in describing modules and their attributes and behaviour. ### Requirements [](#requirements) - PHP: 7.1 and up, until 8 inclusive, ### Interfaces [](#interfaces) - [`ModuleInterface`](src/ModuleInterface.php) - The interface for a module. A module is an object that represents an application fragment. Modules are prepared using `setup()`, which returns a `ServiceProviderInterface` instance that the application may consume, and invoked using `run()`, consuming the application's DI container. - [`ModuleAwareInterface`](src/ModuleAwareInterface.php) - Something that can have a module retrieved. - [`ModuleExceptionInterface`](src/Exception/ModuleExceptionInterface.php) - An exception thrown by a module. ### Usage [](#usage) #### Module Package [](#module-package) In your module's pacakge, create a file that returns a module factory. This factory MUST return an instance of `ModuleInterface` from this pacakge. By convention, this file has the name `module.php`, and is located in the root directory. Below is a very basic example. In real life, the service provider and the module will often have named classes of their own, and factories and extensions will be located in `services.php` and `extensions.php` respectively, by convention. ``` // module.php use Dhii\Modular\Module\ModuleInterface; use Interop\Container\ServiceProviderInterface; use Psr\Container\ContainerInterface; return function () { return new class () implements ModuleInterface { /** * Declares services of this module. * * @return ServiceProviderInterface The service provider with the factories and extensions of this module. */ public function setup() : ServiceProviderInterface { return new class () implements ServiceProviderInterface { /** * Only the factory of the last module in load order is applied. * * @return array|callable[] A map of service names to service definitions. */ public function getFactories() { return [ // A factory always gets one parameter: the container. 'my_module/my_service' => function (ContainerInterface $c) { // Create and return your service instance return new MyService(); }, ]; } /** * All extensions are always applied, in load order. * * @return array|callable[] A map of service names to extensions. */ public function getExtensions() { return [ // An extension gets an additional parameter: // the value returned by the factory or the previously applied extensions. 'other_module/other_service' => function ( ContainerInterface $c, OtherServiceInterface $previous ): OtherServiceInterface { // Perhaps decorate $previous and return the decorator return new MyDecorator($previous); }, ]; } }; } /** * Consumes services of this and other modules. * * @param ContainerInterface $c A container with the services of all modules. */ public function run(ContainerInterface $c): void { $myService = $c->get('my_module/my_service'); $myService->doSomething(); } }; }; ``` In the above example, the module declares a service `my_module/my_service`, and an extension for the `other_module/other_service`, which may be found in another module. Note that by convention, the service name contains the module name prefix, separated by forward slash `/`. It's possible to further "nest" services by adding slash-separated "levels". In the future, some container implementations will add benefits for modules that use this convention. Applications would often need the ability to do something with the arbitrary set of modules they require. In order for an application to be able to group all modules together, declare the package type in your `composer.json` to be `dhii-mod` by convention. Following this convention would allow all modules written by all authors to be treated uniformly. ``` { "name": "me/my_module", "type": "dhii-mod" } ``` What's important here: 1. A module's `setup()` method should not cause side effects. The setup method is intended for the modules to prepare for action. Modules should not actually peform the actions during this method. The container is not available in this method, and therefore the module cannot use any services, whether of itself or of other modules, in this method. Do not try to make the module use its own services here. 2. Implement the correct interfaces. A module MUST implement `ModuleInterface`. The module's `setup()` method MUST return `ServiceProviderInterface`. Even though the [Service Provider](https://packagist.org/packages/container-interop/service-provider) standard is experimental, and has been experimental for a long time, the module standard relies heavily on it. If the module standard becomes ubiquitous, this could push FIG to go forward with the Service Provider standard, hopefully making it into a PSR. 3. Observe conventions. It is important that conventions outlined here are observed. Some are necessary for smooth operation of modules and/or consuming applications. Some others may not make a difference right now, but could add benefits in the future. Please observe these conventions to ensure an optimal experience for yourself and for other users of the standard. #### Consumer Package [](#consumer-package) ##### Module Installation [](#module-installation) The package that consumes modules, which is usually the application, would need to require the modules. The below example uses the [`oomphinc/composer-installers-extender`](https://packagist.org/packages/oomphinc/composer-installers-extender) lib to configure Composer so that it installs all `dhii-mod` packages into the `modules` directory in the application root. Packages `me/my_module` and `me/my_other_module` would therefore go into `modules/me/my_module` and `modules/me/my_other_module` respectively. ``` { "name": "me/my_app", "require": { "me/my_module": "^0.1", "me/my_other_module": "^0.1", "oomphinc/composer-installers-extender": "^1.1" }, "extra": { "installer-types": ["dhii-mod"], "installer-paths": { "modules/{$vendor}/{$name}": ["type:dhii-mod"] } } } ``` ##### Module Loading [](#module-loading) Once a module has been required, it must be loaded. Module files must be explicitly loaded by the application, because the application is what determines module load order. The load order is the fundamental principle that allows modules to extend and override each other's services in a simple and intuitive way: 1. Factories in modules that are loaded later will completely override factories of modules loaded earlier. Ultimately, for each service, only one factory will be used: the one declared last. So if `my_other_module`is loaded after `my_module`, and it declares a service `my_module/my_service`, then it will override the `my_module/my_service` service declared by `my_module`. In short: **last factory wins**. 2. Extensions in modules that are loaded later will be applied after extensions of modules loaded earlier. Ultimately, extensions from *all* modules will be applied on top of what is returned by the factory. So if `my_other_module` declares an extension `other_module/other_service`, it will be applied after the extension `other_module/other_service` declared by `my_module`. In short: **later extensions extend previous extensions**. Continuing from the examples above, if something in the application requests the service `other_module/other_service`declared by `my_other_module`, this is what is going to happen: 1. The factory in `my_other_module` is invoked. 2. The extension in `my_module` is invoked, and receives the result of the above factory as `$previous`. 3. The extension in `my_other_module` is invoked, and receives the result of the above extension as `$previous` 4. The caller of `get('other_module/other_service')` receives the result of the above extension. Thus, any module can override and/or extend services from any other module. Below is an example of what an application's bootstrap code could look like. This example uses classes from [`dhii/containers`](https://packagist.org/packages/dhii/containers). ``` // bootstrap.php use Dhii\Modular\Module\ModuleInterface; use Interop\Container\ServiceProviderInterface; use Dhii\Container\CompositeCachingServiceProvider; use Dhii\Container\DelegatingContainer; use Dhii\Container\CachingContainer; (function ($file) { $baseDir = dirname($file); $modulesDir = "$baseDir/modules"; // Order is important! $moduleNames = [ 'me/my_module', 'me/my_other_module', ]; // Create and load all modules /* @var $modules ModuleInterface[] */ $modules = []; foreach ($moduleNames as $moduleName) { $moduleFactory = require_once("$modulesDir/$moduleName/module.php"); $module = $moduleFactory(); $modules[$moduleName] = $module; } // Retrieve all modules' service providers /* @var $providers ServiceProviderInterface[] */ $providers = []; foreach ($modules as $module) { $providers[] = $module->setup(); } // Group all service providers into one $provider = new CompositeCachingServiceProvider(); $container = new CachingContainer(new DelegatingContainer($provider, $parentContainer = null)); // Run all modules foreach ($modules as $module) { $module->run($container); } })(__FILE__); ``` The above will load, setup, and run modules `me/my_module` and `me/my_other_module`, in that order, from the `modules` directory, provided that conventions have been followed by those modules. What's important to note here: 1. First *all* modules are set up, and then *all* modules are run. If you set up and run modules in the same step, it will not work, because the bootstrap will not have the opportunity to configure the application's DI container with services from all modules. 2. The `CompositeCachingServiceProvider` is what is responsible for resolving services correctly. This relieves the application, as the process can seem complicated, and is quite re-usable. The usage of this class is recommended. 3. The `DelegatingContainer` optionally accepts a parent container. If your application is a module itself, and needs to be part of a larger application with its own DI container, supply it as the 2nd parameter. This will ensure that services will always be retrieved from the top-most container, regardless of where the definition is declared. 4. The `CachingContainer` ensures services are cached. Effectively, this means that all services are singletons, i.e. there will only be one instance of each service in the application. This is most commonly the desired behaviour. Without the `CachingContainer`, i.e. with just the `DelegatingContainer`, service definitions will get invoked every time `get()` is called, which is usually undesirable. 5. Conventions are important. If modules did not place the `module.php` file into their root directories, the bootstrap would not be able to load each module by just its package name. Modules which do not follow that convention must have their `module.php` file loaded separately, which would make the bootstrap code more complicated. ### Health Score 35 — LowBetter than 80% of packages Maintenance20 Infrequent updates — may be unmaintained Popularity36 Limited adoption so far Community17 Small or concentrated contributor base Maturity54 Maturing project, gaining track record Bus Factor1 Top contributor holds 75.6% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Every ~240 days Recently: every ~164 days Total 6 Last Release 1729d ago PHP version history (3 changes)v0.1-alpha1PHP ^5.3 | ^7.0 v0.2.0-alpha1PHP ^7.1 v0.3.0-alpha1PHP ^7.1 | ^8.0 ### Community Maintainers ![](https://www.gravatar.com/avatar/1894e91b32c9f80d8f30a42d360af6983a507f1cf2c621b7c9a0a0de14e011c5?d=identicon)[XedinUnknown](/maintainers/XedinUnknown) --- Top Contributors [![XedinUnknown](https://avatars.githubusercontent.com/u/1428973?v=4)](https://github.com/XedinUnknown "XedinUnknown (93 commits)")[![mecha](https://avatars.githubusercontent.com/u/5425482?v=4)](https://github.com/mecha "mecha (30 commits)") --- Tags modularitymodularizationservice-provider ### Code Quality TestsPHPUnit ### Embed Badge ![Health badge](/badges/dhii-module-interface/health.svg) ``` [![Health](https://phpackages.com/badges/dhii-module-interface/health.svg)](https://phpackages.com/packages/dhii-module-interface) ``` ### Alternatives [oomphinc/composer-installers-extender Extend the composer/installers plugin to accept any arbitrary package type. 23728.7M390](/packages/oomphinc-composer-installers-extender)[kelunik/certificate Access certificate details and transform between different formats. 10938.3M8](/packages/kelunik-certificate) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)