Write your own module
A module adds your own features to ClientFence: admin pages, API methods, event listeners and
widgets on existing pages. The built-in modules in modules/ work the same way, so you can copy
from them.
The folder
Section titled “The folder”Each module is one folder in modules/ of the ClientFence directory. Its name is the module ID
with a capital first letter, letters and digits only (where everything else lives:
file structure). This example is called Hello:
| File | What it is |
|---|---|
manifest.json |
The name, description and version shown under Extensions. Required. |
Service.php |
The module’s logic, event listeners and widgets. |
Api/Admin.php |
API methods for staff. Api/Client.php and Api/Guest.php are for clients and visitors. |
Controller/Admin.php |
Admin pages and the menu entry. Controller/Client.php adds client area pages. |
templates/admin/, templates/client/ |
Twig templates for those pages. |
Pick an ID no built-in module uses, such as examplehostingtools. An update replaces the built-in
modules’ files but never touches a folder of your own.
A module can also carry its own payment gateways,
registrars and control panels
in Payment/Adapter/, Registrar/Adapter/ and Server/Manager/, and its own translations in
locale/. They count only while the module is active, so ClientFence refuses to deactivate a
module while one of its gateways, registrars or servers is still installed. A file with the name of
a built-in gateway, registrar or control panel is ignored: give yours a name of its own.
{ "id": "hello", "type": "mod", "name": "Hello", "description": "An example module: an admin page, an API method and a note in the activity log for each new order.", "version": "1.0.0", "author": "Example Hosting", "author_url": "https://example.com/"}Add "minimum_clientfence_version": "1.0.34" when the module needs a ClientFence release: older
sites then refuse to activate it, with a message that names the version.
The service
Section titled “The service”Classes use the namespace ClientFence\Mod\<Folder>. ClientFence gives the service its
container with setDi(); $this->di then reaches the database (em, db), the logger and other
modules (mod_service).
<?php
declare(strict_types=1);
namespace ClientFence\Mod\Hello;
class Service implements \ClientFence\InjectionAwareInterface{ protected ?\Pimple\Container $di = null;
public function setDi(\Pimple\Container $di): void { $this->di = $di; }
public function getDi(): ?\Pimple\Container { return $this->di; }
public function greeting(): string { return 'Hello from your own module.'; }}Add install() and uninstall() methods to create and remove your own database tables. ClientFence
calls them when the module is activated and uninstalled.
An API method
Section titled “An API method”Each public method of Api/Admin.php becomes a staff API call named <module>_<method>:
hello_greeting here, or POST /api/admin/hello/greeting over HTTP with a
staff API key.
<?php
declare(strict_types=1);
namespace ClientFence\Mod\Hello\Api;
class Admin extends \ClientFence\Api\AbstractApi{ public function greeting(): string { return $this->getService()->greeting(); }}Staff other than Super Administrators need access to the module in their group’s
permissions. For finer control, return your own permissions
from getModulePermissions() in the service and check them with $this->checkPermissions(), as
modules/Redirect does.
An admin page
Section titled “An admin page”fetchNavigation() adds the page to the Extensions menu and register() gives it its address.
<?php
declare(strict_types=1);
namespace ClientFence\Mod\Hello\Controller;
class Admin implements \ClientFence\InjectionAwareInterface{ protected ?\Pimple\Container $di = null;
public function setDi(\Pimple\Container $di): void { $this->di = $di; }
public function getDi(): ?\Pimple\Container { return $this->di; }
public function fetchNavigation(): array { return [ 'subpages' => [ [ 'location' => 'extensions', 'label' => 'Hello', 'index' => 3000, 'uri' => $this->di['url']->adminLink('hello'), 'class' => '', ], ], ]; }
public function register(\ClientFence\App &$app): void { $app->get('/hello', 'get_index', [], static::class); }
public function get_index(\ClientFence\App $app): string { $this->di['is_admin_logged'];
return $app->render('mod_hello_index'); }}The template, templates/admin/mod_hello_index.html.twig, calls the API method as
admin.hello_greeting:
{% extends request.ajax ? "layout_blank.html.twig" : "layout_default.html.twig" %}
{% block meta_title %}Hello{% endblock %}
{% set active_menu = 'extensions' %}
{% block content %} <div class="card"> <div class="card-header"> <h3 class="card-title">Hello</h3> </div> <div class="card-body">{{ admin.hello_greeting }}</div> </div>{% endblock %}A settings page is a template named templates/admin/mod_<id>_settings.html.twig: the
Extensions list then shows a Settings link for the module.
Add a widget
Section titled “Add a widget”Widgets put your own template into a slot on an existing page. Implement
\ClientFence\Interfaces\WidgetProviderInterface in the service and list them:
public function getWidgets(): array{ return [ ['slot' => 'client.index.dashboard.content.before', 'template' => 'mod_hello_dashboard'], ];}The template goes in a widgets/ folder: templates/client/widgets/mod_hello_dashboard.html.twig.
<div class="card mb-3"> <div class="card-body">Hello, {{ client.profile_get.first_name }}.</div></div>To add a link to the client area menu, use the slot client.theme.menu.end. Its template gets
active_menu, the current page’s menu key, so the link can show as active:
<li> <a href="{{ 'hello'|url }}" title="{{ 'Hello'|trans }}"{% if active_menu == 'hello' %} class="active" aria-current="page"{% endif %}> <svg class="icon" aria-hidden="true"><use href="#link"/></svg> <span class="sidebar-text">{{ 'Hello'|trans }}</span> </a></li>A page of your module sets {% set active_menu = 'hello' %} in its template.
If a widget’s template fails, its place shows an error box and the rest of the page keeps working.
Extensions → Widgets lists every slot. Select Rediscover Widgets after you add or rename a widget (see Inspect widgets and event hooks).
Translate it
Section titled “Translate it”Write your texts in English with __trans('...') in PHP and |trans in templates. Put a gettext
catalogue for each language in locale/<language>/LC_MESSAGES/messages.mo, for example
locale/ar_SA/LC_MESSAGES/messages.mo, or locale/ar/LC_MESSAGES/messages.mo for every kind of
Arabic; the folder names are those in the ClientFence locale/ folder. Make the .mo file from a .po file with msgfmt or any gettext editor. ClientFence’s
own translation wins when both translate the same text.
Update a module
Section titled “Update a module”Raise version in manifest.json when you ship new files. On its next run, cron sees that the
files are newer than the installed version, calls the service’s upgrade() once with the old
version, and records the new one:
public function upgrade(string $from): void{ if (version_compare($from, '1.1.0', '<')) { // Add the table or column that 1.1.0 needs. }}If upgrade() throws an exception, the installed version stays and cron tries again on its next
run; the error shows in Activity → System Activity.
Activate it
Section titled “Activate it”- Copy the folder to
modules/and make the web server user its owner. - Go to Extensions, find Hello and select Activate.
- Open Extensions → Hello.
To react to orders, payments and tickets, see Listen to events.

