refactor: autoload extensions (#1877)

Cecilapp · Jan 11, 2024 · 8b908f2 · 8b908f2
1 parent 0aa432f
commit 8b908f2
Show file tree

Hide file tree

Showing 12 changed files with 53 additions and 43 deletions.
diff --git a/config/default.php b/config/default.php
@@ -118,7 +118,7 @@
                 'capture'   => 'before', // part to capture, `before` or `after` the separator (`before` by default)
             ],
         ],
-        'generators' => [ // list of pages generators, ordered by weight
+        'generators' => [ // list of pages generators class, ordered by weight
             10 => 'Cecil\Generator\DefaultPages',
             20 => 'Cecil\Generator\VirtualPages',
             30 => 'Cecil\Generator\ExternalBody',
@@ -258,7 +258,9 @@
                 'dir' => 'resources/translations', // internal translations directory
             ],
         ],
-        'extensions' => [], // Twig extensions
+        'extensions' => [ // list of Twig extensions class
+            //'Name' => 'Cecil\Renderer\Extension\Class',
+        ],
     ],
     // themes
     'themes' => [
@@ -369,10 +371,10 @@
             'vocabulary' => ['html'],
             'term'       => ['html', 'atom'],
         ],
-        'postprocessors' => [ // list of output post processors
-            -1 => 'Cecil\Renderer\PostProcessor\GeneratorMetaTag',
-            -2 => 'Cecil\Renderer\PostProcessor\HtmlExcerpt',
-            -3 => 'Cecil\Renderer\PostProcessor\MarkdownLink',
+        'postprocessors' => [ // list of output post processors class
+            'GeneratorMetaTag' => 'Cecil\Renderer\PostProcessor\GeneratorMetaTag',
+            'HtmlExcerpt'      => 'Cecil\Renderer\PostProcessor\HtmlExcerpt',
+            'MarkdownLink'     => 'Cecil\Renderer\PostProcessor\MarkdownLink',
         ],
     ],
     'cache' => [

diff --git a/docs/1-Quick Start.fr.md b/docs/1-Quick Start.fr.md
@@ -42,7 +42,9 @@ curl -LO https://cecil.app/cecil.phar
 
 Vous pouvez également [télécharger Cecil](https://cecil.app/download/) manuellement.
 
-> [PHP](https://php.net/manual/fr/install.php) 8.1+ est requis.
+:::important
+[PHP](https://php.net/manual/fr/install.php) 8.1+ est requis.
+:::
 
 ### Créer un nouveau site
 

diff --git a/docs/1-Quick Start.md b/docs/1-Quick Start.md
@@ -36,7 +36,9 @@ curl -LO https://cecil.app/cecil.phar
 
 You can also [download Cecil](https://cecil.app/download/) manually.
 
-> [PHP](https://php.net/manual/en/install.php) 8.1+ is required.
+:::important
+[PHP](https://php.net/manual/en/install.php) 8.1+ is required.
+:::
 
 ### Create a new website
 

diff --git a/docs/7-Extend.md b/docs/7-Extend.md
@@ -1,23 +1,31 @@
 <!--
 description: "Extend Cecil."
 date: 2023-04-17
-updated: 2023-12-11
+updated: 2024-01-11
 -->
 # Extend
 
-There is several way to extend Cecil:
-
 [toc]
 
 ## Pages Generator
 
-A Generator help you to create pages without Markdown files (with data from a database or an API for example) or alter existing pages.
+A Generator help you to create pages without Markdown files (with data from an API or a database for example) or alter existing pages.
 
-Just add your Generator to the [`pages.generators`](4-Configuration.md#generators) list, and create a new class in the `Cecil\Generator` namespace.
+Just add your Generator PHP class name to the [`pages.generators`](4-Configuration.md#generators) list, and create a new class in the `Cecil\Generator` namespace.
 
 **Example:**
 
-_/generators/Cecil/Generator/DummyPage.php_
+_configuration_
+
+```yaml
+pages:
+  generators:
+    # priority: class name
+    35: Cecil\Generator\Database
+    99: Cecil\Generator\DummyPage
+```
+
+_/extensions/Cecil/Generator/DummyPage.php_
 
 ```php
 <?php
@@ -44,7 +52,7 @@ class DummyPage extends AbstractGenerator implements GeneratorInterface
 }
 ```
 
-_/generators/Cecil/Generator/Database.php_
+_/extensions/Cecil/Generator/Database.php_
 
 ```php
 <?php
@@ -75,16 +83,7 @@ class Database extends AbstractGenerator implements GeneratorInterface
 }
 ```
 
-_configuration_
-
-```yaml
-pages:
-  generators:
-    35: Cecil\Generator\Database
-    99: Cecil\Generator\DummyPage
-```
-
-## Renderer extension
+## Renderer (Twig) extension
 
 You can add custom [functions](3-Templates.md#functions) and [filters](3-Templates.md#filters):
 
@@ -119,15 +118,15 @@ layouts:
     MyExtension: Cecil\Renderer\Extension\MyExtension
 ```
 
-## Output post processor
+## Output Post Processor
 
 You can post process page output.
 
-Just add your post processor to the `output.postprocessors` list, and create a new class in the `Cecil\Renderer\PostProcessor` namespace.
+Just add your Post Processor PHP class name to the `output.postprocessors` list, and create a new class in the `Cecil\Renderer\PostProcessor` namespace.
 
 **Example:**
 
-_/postprocessors/Cecil/Renderer/PostProcessor/MyProcessor.php_
+_/extensions/Cecil/Renderer/PostProcessor/MyProcessor.php_
 
 ```php
 <?php
@@ -151,5 +150,5 @@ _configuration_
 ```yaml
 output:
   postprocessors:
-    - Cecil\Renderer\PostProcessor\MyProcessor
+    MyProcessor: Cecil\Renderer\PostProcessor\MyProcessor
 ```
diff --git a/src/Builder.php b/src/Builder.php
@@ -111,6 +111,8 @@ public function __construct($config = null, LoggerInterface $logger = null)
         if (getenv('CECIL_DEBUG') == 'true' || (bool) $this->getConfig()->get('debug')) {
             $this->debug = true;
         }
+        // autoloads local extensions
+        Util::autoload($this, 'extensions');
     }
 
     /**

diff --git a/src/Renderer/Twig.php b/src/Renderer/Twig.php
@@ -14,6 +14,7 @@
 namespace Cecil\Renderer;
 
 use Cecil\Builder;
+use Cecil\Exception\RuntimeException;
 use Cecil\Renderer\Extension\Core as CoreExtension;
 use Cecil\Util;
 use Symfony\Bridge\Twig\Extension\TranslationExtension;
@@ -108,7 +109,7 @@ public function __construct(Builder $builder, $templatesPath)
         // intl
         $this->twig->addExtension(new IntlExtension());
         if (\extension_loaded('intl')) {
-            $this->builder->getLogger()->debug('Intl extension is loaded');
+            $this->builder->getLogger()->debug('PHP Intl extension is loaded');
         }
         // filters fallback
         $this->twig->registerUndefinedFilterCallback(function ($name) {
@@ -131,10 +132,13 @@ public function __construct(Builder $builder, $templatesPath)
         }
         // loads custom extensions
         if ($this->builder->getConfig()->has('layouts.extensions')) {
-            Util::autoload($builder, 'extensions');
             foreach ((array) $this->builder->getConfig()->get('layouts.extensions') as $name => $class) {
-                $this->twig->addExtension(new $class($this->builder));
-                $this->builder->getLogger()->debug(sprintf('Extension "%s" (%s) added', $name, $class));
+                try {
+                    $this->twig->addExtension(new $class($this->builder));
+                    $this->builder->getLogger()->debug(sprintf('Twig extension "%s" added', $name));
+                } catch (\Exception | \Error $e) {
+                    $this->builder->getLogger()->error(sprintf('Unable to add Twig extension "%s": %s', $class, $e->getMessage()));
+                }
             }
         }
     }

diff --git a/src/Step/Pages/Generate.php b/src/Step/Pages/Generate.php
@@ -46,11 +46,10 @@ public function init(array $options): void
     public function process(): void
     {
         $generatorManager = new GeneratorManager($this->builder);
-        Util::autoload($this->builder, 'generators'); // loads custom generators
         $generators = (array) $this->config->get('pages.generators');
         array_walk($generators, function ($generator, $priority) use ($generatorManager) {
             if (!class_exists($generator)) {
-                $message = sprintf('Unable to load generator "%s".', $generator);
+                $message = sprintf('Unable to load generator "%s" (priority: %s).', $generator, $priority);
                 $this->builder->getLogger()->error($message);
 
                 return;

diff --git a/src/Step/Pages/Render.php b/src/Step/Pages/Render.php
@@ -85,15 +85,14 @@ public function process(): void
 
         // renders each page
         $count = 0;
-        Util::autoload($this->builder, 'postprocessors');
         $postprocessors = [];
-        foreach ($this->config->get('output.postprocessors') as $postprocessor) {
+        foreach ($this->config->get('output.postprocessors') as $name => $postprocessor) {
             if (!class_exists($postprocessor)) {
-                $this->builder->getLogger()->error(sprintf('Can\'t load output post processor "%s"', $postprocessor));
+                $this->builder->getLogger()->error(sprintf('Unable to load output post processor "%s"', $postprocessor));
                 break;
             }
             $postprocessors[] = new $postprocessor($this->builder);
-            $this->builder->getLogger()->debug(sprintf('Output post processor "%s" loaded', $postprocessor));
+            $this->builder->getLogger()->debug(sprintf('Output post processor "%s" loaded', $name));
         }
         /** @var Page $page */
         foreach ($pages as $page) {

diff --git a/src/Util.php b/src/Util.php
@@ -119,14 +119,14 @@ public static function autoload(Builder $builder, string $dir): void
     {
         spl_autoload_register(function ($className) use ($builder, $dir) {
             $classFile = Util::joinFile($builder->getConfig()->getSourceDir(), $dir, "$className.php");
-            if (file_exists($classFile)) {
+            if (is_readable($classFile)) {
                 require $classFile;
                 return;
             }
             // in themes
             foreach ($builder->getConfig()->getTheme() ?? [] as $theme) {
                 $classFile = Util::joinFile($builder->getConfig()->getThemeDirPath($theme, $dir), "$className.php");
-                if (file_exists($classFile)) {
+                if (is_readable($classFile)) {
                     require $classFile;
                     return;
                 }

diff --git a/tests/fixtures/website/config.php b/tests/fixtures/website/config.php
@@ -98,7 +98,7 @@
     ],
     'pages' => [
         'generators' => [
-            99  => 'Cecil\Generator\Test',
+            99  => 'Cecil\Generator\TestError',
             100 => 'Cecil\Generator\TitleReplace',
         ],
         'default'    => [
@@ -226,7 +226,8 @@
     ],
     'layouts' => [
         'extensions' => [
-            'Test' => 'Cecil\Renderer\Extension\Test',
+            'Test'       => 'Cecil\Renderer\Extension\Test',
+            'Test error' => 'Cecil\Renderer\Extension\TestError',
         ],
     ],
     'cache' => [

diff --git a/...nerators/Cecil/Generator/TitleReplace.php → ...tensions/Cecil/Generator/TitleReplace.php b/...nerators/Cecil/Generator/TitleReplace.php → ...tensions/Cecil/Generator/TitleReplace.php
diff --git a/...ors/Cecil/Renderer/PostProcessor/Test.php → ...ons/Cecil/Renderer/PostProcessor/Test.php b/...ors/Cecil/Renderer/PostProcessor/Test.php → ...ons/Cecil/Renderer/PostProcessor/Test.php