Skip to content

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.

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.

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.

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.

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.

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).

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.

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.

  1. Copy the folder to modules/ and make the web server user its owner.
  2. Go to Extensions, find Hello and select Activate.
  3. Open Extensions → Hello.

To react to orders, payments and tickets, see Listen to events.