Refactor onPages… and onPage… core events

Add new onPagesDiscovered event passing the unsorted pages array, move the $currentPage, $previousPage and $nextPage arguments from the onPagesLoaded event to the new onCurrentPageDiscovered event, remove the $twig argument from the onPageRendering event and rather trigger the new onTwigRegistered event for this. Also add the new onYamlParserRegistered and onParsedownRegistered events passing the YAML parser resp. the Parsedown instance. Allow plugin's to skip a page by setting the $id argument of the onSinglePageLoading event to NULL.

lib/Pico.php

@@ -400,9 +400,6 @@ class Pico
 
         $this->triggerEvent('onContentLoaded', array(&$this->rawContent));
 
-        // register YAML parser
-        $this->triggerEvent('onYamlParserRegistration');
-
         // parse file meta
         $this->metaHeaders = $this->getMetaHeaders();
         $this->triggerEvent('onMetaHeaders', array(&$this->metaHeaders));
@@ -411,9 +408,6 @@ class Pico
         $this->meta = $this->parseFileMeta($this->rawContent, $this->metaHeaders);
         $this->triggerEvent('onMetaParsed', array(&$this->meta));
 
-        // register parsedown
-        $this->triggerEvent('onParsedownRegistration');
-
         // parse file content
         $this->triggerEvent('onContentParsing', array(&$this->rawContent));
 
@@ -427,25 +421,24 @@ class Pico
         $this->triggerEvent('onPagesLoading');
 
         $this->readPages();
+        $this->triggerEvent('onPagesDiscovered', array(&$this->pages));
+
         $this->sortPages();
+        $this->triggerEvent('onPagesLoaded', array(&$this->pages));
+
         $this->discoverPageSiblings();
         $this->discoverCurrentPage();
+        $this->triggerEvent(
+            'onCurrentPageDiscovered',
+            array(&$this->currentPage, &$this->previousPage, &$this->nextPage)
+        );
 
-        $this->triggerEvent('onPagesLoaded', array(
-            &$this->pages,
-            &$this->currentPage,
-            &$this->previousPage,
-            &$this->nextPage
-        ));
-
-        // register twig
-        $this->triggerEvent('onTwigRegistration');
+        // render template
         $this->registerTwig();
 
-        // render template
         $this->twigVariables = $this->getTwigVariables();
         $this->twigTemplate = $this->getTwigTemplate();
-        $this->triggerEvent('onPageRendering', array(&$this->twig, &$this->twigVariables, &$this->twigTemplate));
+        $this->triggerEvent('onPageRendering', array(&$this->twigTemplate, &$this->twigVariables));
 
         $output = $this->twig->render($this->twigTemplate, $this->twigVariables);
         $this->triggerEvent('onPageRendered', array(&$output));
@@ -1097,12 +1090,16 @@ class Pico
     /**
      * Returns the Symfony YAML parser
      *
+     * This method triggers the `onYamlParserRegistered` event when the Symfony
+     * YAML parser wasn't initiated yet.
+     *
      * @return \Symfony\Component\Yaml\Parser Symfony YAML parser
      */
     public function getYamlParser()
     {
         if ($this->yamlParser === null) {
             $this->yamlParser = new \Symfony\Component\Yaml\Parser();
+            $this->triggerEvent('onYamlParserRegistered', array(&$this->yamlParser));
         }
 
         return $this->yamlParser;
@@ -1194,6 +1191,9 @@ class Pico
     /**
      * Returns the Parsedown Extra markdown parser
      *
+     * This method triggers the `onParsedownRegistered` event when the
+     * Parsedown Extra parser wasn't initiated yet.
+     *
      * @return ParsedownExtra Parsedown Extra markdown parser
      */
     public function getParsedown()
@@ -1205,6 +1205,8 @@ class Pico
             $this->parsedown->setBreaksEnabled((bool) $this->config['content_config']['breaks']);
             $this->parsedown->setMarkupEscaped((bool) $this->config['content_config']['escape']);
             $this->parsedown->setUrlsLinked((bool) $this->config['content_config']['auto_urls']);
+
+            $this->triggerEvent('onParsedownRegistered', array(&$this->parsedown));
         }
 
         return $this->parsedown;
@@ -1333,6 +1335,10 @@ class Pico
             // trigger onSinglePageLoading event
             $this->triggerEvent('onSinglePageLoading', array(&$id));
 
+            if ($id === null) {
+                continue;
+            }
+
             // drop inaccessible pages (e.g. drop "sub.md" if "sub/index.md" exists)
             $conflictFile = $contentDir . $id . '/index' . $contentExt;
             if (in_array($conflictFile, $files, true)) {
@@ -1557,6 +1563,9 @@ class Pico
      * This method also registers Pico's core Twig filters `link` and `content`
      * as well as Pico's {@link PicoTwigExtension} Twig extension.
      *
+     * This method triggers the `onTwigRegistered` event when the Twig template
+     * engine wasn't initiated yet.
+     *
      * @see    Pico::getTwig()
      * @see    http://twig.sensiolabs.org/ Twig website
      * @see    https://github.com/twigphp/Twig Twig on GitHub
@@ -1590,6 +1599,9 @@ class Pico
             }
             return null;
         }));
+
+        // trigger onTwigRegistration event
+        $this->triggerEvent('onTwigRegistered', array(&$this->twig));
     }
 
     /**

plugins/DummyPlugin.php

@@ -230,6 +230,7 @@ class DummyPlugin extends AbstractPicoPlugin
      * @see    Pico::readPages()
      * @see    DummyPlugin::onSinglePageLoading()
      * @see    DummyPlugin::onSinglePageLoaded()
+     * @see    DummyPlugin::onPagesDiscovered()
      * @see    DummyPlugin::onPagesLoaded()
      * @return void
      */
@@ -241,8 +242,10 @@ class DummyPlugin extends AbstractPicoPlugin
     /**
      * Triggered before Pico loads a single page
      *
-     * @see    Pico::readPages()
+     * Set `$id` to `null` to remove this page from the pages array.
+     *
      * @see    DummyPlugin::onSinglePageLoaded()
+     * @see    DummyPlugin::onPagesDiscovered()
      * @see    DummyPlugin::onPagesLoaded()
      * @param  string &$id relative path to the content file
      * @return void
@@ -272,6 +275,7 @@ class DummyPlugin extends AbstractPicoPlugin
      *
      * Set `$pageData` to `null` to remove this page from the pages array.
      *
+     * @see    DummyPlugin::onPagesDiscovered()
      * @see    DummyPlugin::onPagesLoaded()
      * @param  array &$pageData data of the loaded page
      * @return void
@@ -282,23 +286,54 @@ class DummyPlugin extends AbstractPicoPlugin
     }
 
     /**
-     * Triggered after Pico has read all known pages
+     * Triggered after Pico has discovered all known pages
+     *
+     * See {@link DummyPlugin::onSinglePageLoaded()} for details about the
+     * structure of the page data. Please note that the pages array isn't
+     * sorted yet.
+     *
+     * @see    Pico::sortPages()
+     * @see    DummyPlugin::onPagesLoaded()
+     * @param  array[]    &$pages        data of all known pages
+     * @return void
+     */
+    public function onPagesDiscovered(array &$pages)
+    {
+        // your code
+    }
+
+    /**
+     * Triggered after Pico has sorted the pages array
      *
      * See {@link DummyPlugin::onSinglePageLoaded()} for details about the
      * structure of the page data.
      *
      * @see    Pico::getPages()
+     * @param  array[]    &$pages        data of all known pages
+     * @return void
+     */
+    public function onPagesLoaded(array &$pages)
+    {
+        // your code
+    }
+
+    /**
+     * Triggered when Pico discovered the current, previous and next pages
+     *
+     * See {@link DummyPlugin::onSinglePageLoaded()} for details about the
+     * structure of the page data.
+     *
+     * @see    Pico::discoverPageSiblings()
+     * @see    Pico::discoverCurrentPage()
      * @see    Pico::getCurrentPage()
      * @see    Pico::getPreviousPage()
      * @see    Pico::getNextPage()
-     * @param  array[]    &$pages        data of all known pages
      * @param  array|null &$currentPage  data of the page being served
      * @param  array|null &$previousPage data of the previous page
      * @param  array|null &$nextPage     data of the next page
      * @return void
      */
-    public function onPagesLoaded(
-        array &$pages,
+    public function onCurrentPageDiscovered(
         array &$currentPage = null,
         array &$previousPage = null,
         array &$nextPage = null
@@ -307,37 +342,63 @@ class DummyPlugin extends AbstractPicoPlugin
     }
 
     /**
-     * Triggered before Pico registers the twig template engine
+     * Triggered before Pico renders the page
      *
+     * @see    Pico::getTwigTemplate()
+     * @see    Pico::getTwigVariables()
+     * @see    DummyPlugin::onPageRendered()
+     * @param  string           &$templateName  file name of the template
+     * @param  array            &$twigVariables template variables
      * @return void
      */
-    public function onTwigRegistration()
+    public function onPageRendering(&$templateName, array &$twigVariables)
     {
         // your code
     }
 
     /**
-     * Triggered before Pico renders the page
+     * Triggered after Pico has rendered the page
      *
-     * @see    Pico::getTwig()
-     * @see    DummyPlugin::onPageRendered()
-     * @param  Twig_Environment $twig           twig template engine
-     * @param  array            &$twigVariables template variables
-     * @param  string           &$templateName  file name of the template
+     * @param  string &$output contents which will be sent to the user
      * @return void
      */
-    public function onPageRendering(Twig_Environment $twig, array &$twigVariables, &$templateName)
+    public function onPageRendered(&$output)
     {
         // your code
     }
 
     /**
-     * Triggered after Pico has rendered the page
+     * Triggered when Pico registers the YAML parser
      *
-     * @param  string &$output contents which will be sent to the user
+     * @see    Pico::getYamlParser()
+     * @param  \Symfony\Component\Yaml\Parser &$yamlParser YAML parser instance
      * @return void
      */
-    public function onPageRendered(&$output)
+    public function onYamlParserRegistered(\Symfony\Component\Yaml\Parser &$yamlParser)
+    {
+        // your code
+    }
+
+    /**
+     * Triggered when Pico registers the Parsedown parser
+     *
+     * @see    Pico::getParsedown()
+     * @param  Parsedown &$parsedown Parsedown instance
+     * @return void
+     */
+    public function onParsedownRegistered(Parsedown &$parsedown)
+    {
+        // your code
+    }
+
+    /**
+     * Triggered when Pico registers the twig template engine
+     *
+     * @see    Pico::getTwig()
+     * @param  Twig_Environment &$twig Twig instance
+     * @return void
+     */
+    public function onTwigRegistered(Twig_Environment &$twig)
     {
         // your code
     }