Anatomie d'un module et module.json

La structure du dossier, chaque champ du manifeste, et les méthodes du cycle de vie que le kernel appelle.

Un module est un répertoire autonome, chargeable à l'exécution et installable depuis un zip. Les modules fournis en standard utilisent exactement ce contrat.

Structure du dossier#

Code

modules/directory/
  module.json                 manifeste (obligatoire)
  src/
    DirectoryServiceProvider.php
    Models/
    Http/Controllers/
    Http/Requests/
    Support/
  database/
    migrations/               les tables du module
    seeders/
  resources/
    views/                    Blade, substituable par un thème
    lang/                     les traductions du module
    assets/                   css et js, DÉJÀ COMPILÉS
  routes/
    web.php
    admin.php
  config/directory.php

Le manifeste#

JSON

{
  "name": "Directory",
  "slug": "directory",
  "version": "1.2.0",
  "description": "A configurable catalogue.",
  "author": { "name": "You", "url": "https://example.com" },
  "requires": {
    "bondry": ">=1.0 <2.0",
    "php": ">=8.2",
    "extensions": ["gd"],
    "modules": { "payments": ">=1.0" }
  },
  "provider": "Modules\\Directory\\DirectoryServiceProvider",
  "provides": {
    "permissions": ["directory.view", "directory.manage"],
    "hooks": ["profile.tabs", "admin.menu", "search.sources"]
  },
  "settings": "admin.directory.settings",
  "assets": { "css": ["assets/directory.css"], "js": ["assets/directory.js"] },
  "parent": null,
  "tested_up_to": "1.4.0",
  "official": false,
  "licensing": { "product_slug": "your-directory" }
}

Champ	Signification
`slug`	L'identité. `[a-z0-9-]`, unique, et qui ne change jamais entre les versions.
`version`	Semver. C'est ce qui déclenche `onUpdate`.
`requires`	Des plages semver. Le kernel refuse d'installer quand elles ne sont pas respectées.
`provider`	La classe racine. Elle doit exister et étendre le fournisseur de services de base.
`provides.permissions`	Enregistrées dans la matrice des groupes à l'installation.
`settings`	Un nom de route. La liste des modules y renvoie quand le module est activé.
`parent`	Le slug du module que celui-ci étend. Son absence signifie qu'il étend le core.
`tested_up_to`	La version la plus récente du core contre laquelle vous avez testé.
`official`	Accepté uniquement pour les paquets que nous signons.
`licensing.product_slug`	Présent uniquement sur un module payant. Voir API de licence.

Le fournisseur de services#

Votre fournisseur de services étend Bondry\Kernel\Modules\ModuleServiceProvider et implémente le cycle de vie :

PHP

interface ModuleContract
{
    // À chaque requête, seulement tant que le module est activé :
    public function register(): void;   // liaisons du conteneur
    public function boot(): void;       // routes, vues, migrations, traductions, hooks

    // Appelées par l'installateur d'exécution, pas à chaque requête :
    public function onInstall(): void;
    public function onUninstall(bool $purge): void;
    public function onEnable(): void;
    public function onDisable(): void;
    public function onUpdate(string $from, string $to): void;
}

boot() est l'endroit où vous appelez loadRoutesFrom, loadViewsFrom avec votre namespace, loadMigrationsFrom, loadTranslationsFrom et où vous enregistrez vos hooks.

register() s'exécute avant que quoi que ce soit soit résolu : uniquement des liaisons, pas de base de données.

Avertissement boot() s'exécute à chaque requête. Tout ce qui y est coûteux est un coût que vos acheteurs paient à chaque vue de page, en hébergement mutualisé.

Les vues et le thème#

Enregistrez vos vues avec un namespace :

PHP

$this->loadViewsFrom(__DIR__.'/../resources/views', 'directory');

Le rendu de directory::item.show se résout d'abord via la chaîne de thèmes, donc un acheteur peut surcharger n'importe quel écran de votre module depuis son thème sans modifier vos fichiers. Voir Thèmes.

Flux d'installation#

Ce que le panneau fait avec votre zip, dans l'ordre :

l'ouvre dans un répertoire temporaire isolé ;
lit module.json et valide le schéma ;
vérifie requires et tout conflit de slug ou de version ;
vérifie la signature quand official est défini ;
le déplace vers modules/<slug>/ et exécute onInstall(), ou onUpdate() quand une version était déjà présente ;
publie les assets vers public/modules/<slug>/ ;
l'enregistre dans la table des modules ;
vide les caches de routes, de vues et de config.