Cecil 9.25.0 : des plugins et un mécanisme d’extension repensé

Cecil 9.25.0 revoit la façon d’étendre Cecil en PHP : les extensions se déclarent toutes de la même manière, peuvent être regroupées dans un plugin, réagir aux événements de build, et sont plus simples à distribuer avec un thème.

Configuration unifiée

Les générateurs de pages, extensions Twig, post-processeurs de sortie, abonnés aux événements et plugins sont désormais déclarés de la même manière, sous la forme d’un tableau associatif indexé par nom :

pages:
  generators:
    Database: { class: MySite\Generator\Database, priority: 35 }
    Redirect: false # désactive un générateur intégré
output:
  postprocessors:
    MyProcessor: MySite\PostProcessor\MyProcessor # priorité par défaut (100)

Les extensions intégrées sont elles aussi nommées : elles peuvent être désactivées, ou déplacées avec une nouvelle priorité, par leur nom.

Une extension qui ne peut pas être chargée (classe inconnue, mauvaise interface, option invalide) est ignorée et l’erreur est journalisée. Pour faire échouer le build à la place, activez le mode strict :

extensions:
  strict: true

Plugins

Un plugin est un point d’entrée unique qui enregistre un ensemble d’extensions (générateurs, extensions Twig, post-processeurs, abonnés et écouteurs d’événements) ainsi que des options par défaut :

class ExamplePlugin extends AbstractPlugin
{
    public function register(Registry $registry): void
    {
        $registry
            ->config(['example' => ['feed' => ['limit' => 10]]])
            ->twigExtension(Twig\ExampleExtension::class)
            ->generator(Generator\Feed::class, priority: 35)
            ->subscriber(SearchIndex::class);
    }
}

extensions:
  plugins:
    Example: Example\ExamplePlugin

C’est la façon recommandée de distribuer des extensions avec un thème : déclaré dans le config.yml du thème, le plugin est activé avec le thème, sans autre configuration. La configuration du site peut toujours surcharger ses options, et désactiver ou déplacer ses extensions par leur nom.

Événements de build

Cecil émet désormais des événements pendant le build : avant et après le build et chaque étape, ainsi qu’à chaque étape du cycle de vie d’une page (page.created, page.converted, page.rendered et page.saved). Écoutez-les avec un abonné pour créer un index de recherche, notifier un service ou modifier le rendu des pages :

extensions:
  subscribers:
    SearchIndex: MySite\SearchIndex

Chargement automatique

Les classes personnalisées sont chargées automatiquement depuis le répertoire extensions du site ou d’un thème, le chemin du fichier correspondant au namespace (ex. : MySite\Generator\Database → extensions/MySite/Generator/Database.php). Vous pouvez également :

déclarer des correspondances PSR-4 avec extensions.autoload ;
installer des bibliothèques tierces avec Composer dans le répertoire extensions : extensions/vendor/autoload.php est chargé automatiquement, même avec le phar de Cecil.

Convertisseur et analyseur Markdown

Le convertisseur (pages.converter) et l’analyseur (pages.body.parser) Markdown peuvent désormais être remplacés par vos propres classes, par exemple pour ajouter votre propre syntaxe Markdown.

Nouvelle commande `new:extension`

La commande new:extension crée le squelette d’une extension (générateur, extension Twig, post-processeur, abonné aux événements ou plugin), et affiche la configuration permettant de l’activer :

cecil new:extension --type=plugin --name=Plugin --namespace=MySite

Exemples

Le thème Paper enregistre désormais son extension Twig avec un plugin.
Le thème d’exemple embarque un petit plugin : un filtre Twig de temps de lecture.
L’exemple de plugin est un thème composant qui embarque un plugin avec un générateur, une extension Twig, un post-processeur et un abonné aux événements.

Dépréciations

Les configurations existantes fonctionnent toujours, avec un avertissement de dépréciation. Elles ne seront plus prises en charge dans Cecil 10 :

Indexer les extensions par priorité (ex. : 35: MySite\Generator\Database) ou par position (une liste) : utilisez un nom à la place (Database: { class: MySite\Generator\Database, priority: 35 }).
Utiliser le namespace Cecil\ pour des classes personnalisées : il est désormais réservé, utilisez votre propre namespace (ex. : MySite\ ou le nom de votre thème).
Dans Cecil 10, le mode strict sera activé par défaut.

Consultez la documentation « Étendre Cecil » pour plus de détails, et mettez à jour Cecil pour profiter de cette version.