Various small improvements

lib/AbstractPicoPlugin.php

@@ -154,7 +154,7 @@ abstract class AbstractPicoPlugin implements PicoPluginInterface
      *     config variable, null if the config variable doesn't exist or the
      *     plugin's config array if no config name was supplied
      */
-    protected function getPluginConfig($configName = null)
+    public function getPluginConfig($configName = null)
     {
         $pluginConfig = $this->getConfig(get_called_class());
         if ($pluginConfig) {
@@ -263,8 +263,8 @@ abstract class AbstractPicoPlugin implements PicoPluginInterface
                     }
                 }
             } else {
-                $dependantsList = 'plugin' . ((count($dependants) > 1) ? 's' : '') . ' ';
-                $dependantsList .= "'" . implode("', '", array_keys($dependants)) . "'";
+                $dependantsList = 'plugin' . ((count($dependants) > 1) ? 's' : '') . ' '
+                    . "'" . implode("', '", array_keys($dependants)) . "'";
                 throw new RuntimeException(
                     "Unable to disable plugin '" . get_called_class() . "': "
                     . "Required by " . $dependantsList

lib/Pico.php

@@ -274,7 +274,7 @@ class Pico
     /**
      * Constructs a new Pico instance
      *
-     * To carry out all the processing in Pico, call {@link Pico::run()}.
+     * To carry out all the processing in Pico, call {@see Pico::run()}.
      *
      * @param string $rootDir    root directory of this Pico instance
      * @param string $configDir  config directory of this Pico instance
@@ -677,8 +677,8 @@ class Pico
     /**
      * Returns the instance of a named plugin
      *
-     * Plugins SHOULD implement {@link PicoPluginInterface}, but you MUST NOT
-     * rely on it. For more information see {@link PicoPluginInterface}.
+     * Plugins SHOULD implement {@see PicoPluginInterface}, but you MUST NOT
+     * rely on it. For more information see {@see PicoPluginInterface}.
      *
      * @see    Pico::loadPlugins()
      * @see    Pico::getPlugins()
@@ -824,8 +824,8 @@ class Pico
      * {@path "config/config.yml"} or changing some of its variables before
      * Pico starts processing.
      *
-     * You can call this method between {@link Pico::__construct()} and
-     * {@link Pico::run()} only. Options set with this method cannot be
+     * You can call this method between {@see Pico::__construct()} and
+     * {@see Pico::run()} only. Options set with this method cannot be
      * overwritten by {@path "config/config.yml"}.
      *
      * @see    Pico::loadConfig()
@@ -1314,20 +1314,25 @@ class Pico
      *
      * The page data will be an array containing the following values:
      *
-     * | Array key      | Type   | Description                              |
-     * | -------------- | ------ | ---------------------------------------- |
-     * | id             | string | relative path to the content file        |
-     * | url            | string | URL to the page                          |
-     * | title          | string | title of the page (YAML header)          |
-     * | description    | string | description of the page (YAML header)    |
-     * | author         | string | author of the page (YAML header)         |
-     * | time           | string | timestamp derived from the Date header   |
-     * | date           | string | date of the page (YAML header)           |
-     * | date_formatted | string | formatted date of the page               |
-     * | raw_content    | string | raw, not yet parsed contents of the page |
-     * | meta           | string | parsed meta data of the page             |
-     * | previous_page  | &array | reference to the previous page           |
-     * | next_page      | &array | reference to the next page               |
+     * | Array key      | Type    | Description                                |
+     * | -------------- | ------- | ------------------------------------------ |
+     * | id             | string  | relative path to the content file          |
+     * | url            | string  | URL to the page                            |
+     * | title          | string  | title of the page (YAML header)            |
+     * | description    | string  | description of the page (YAML header)      |
+     * | author         | string  | author of the page (YAML header)           |
+     * | time           | string  | timestamp derived from the Date header     |
+     * | date           | string  | date of the page (YAML header)             |
+     * | date_formatted | string  | formatted date of the page                 |
+     * | hidden         | boolean | this page shouldn't be visible to the user |
+     * | raw_content    | string  | raw, not yet parsed contents of the page   |
+     * | meta           | string  | parsed meta data of the page               |
+     * | previous_page  | &array  | reference to the previous page             |
+     * | next_page      | &array  | reference to the next page                 |
+     *
+     * Please note that the `previous_page` and `next_page` keys won't be
+     * available until the `onPagesLoaded` event ({@see Pico::sortPages()})
+     * was triggered.
      *
      * @see    Pico::sortPages()
      * @see    Pico::discoverPageSiblings()
@@ -1578,10 +1583,10 @@ class Pico
     }
 
     /**
-     * Registers the twig template engine
+     * Registers the Twig template engine
      *
      * This method also registers Pico's core Twig filters `link` and `content`
-     * as well as Pico's {@link PicoTwigExtension} Twig extension.
+     * as well as Pico's {@see PicoTwigExtension} Twig extension.
      *
      * This method triggers the `onTwigRegistered` event when the Twig template
      * engine wasn't initiated yet.
@@ -1800,10 +1805,10 @@ class Pico
      * We assume that the themes folder is a arbitrary deep sub folder of the
      * script's base path (i.e. the directory {@path "index.php"} is in resp.
      * the `httpdocs` directory). Usually the script's base path is identical
-     * to {@link Pico::$rootDir}, but this may aberrate when Pico got installed
+     * to {@see Pico::$rootDir}, but this may aberrate when Pico got installed
      * as a composer dependency. However, ultimately it allows us to use
-     * {@link Pico::getBaseUrl()} as origin of the theme URL. Otherwise Pico
-     * falls back to the basename of {@link Pico::$themesDir} (i.e. assuming
+     * {@see Pico::getBaseUrl()} as origin of the theme URL. Otherwise Pico
+     * falls back to the basename of {@see Pico::$themesDir} (i.e. assuming
      * that `Pico::$themesDir` is `foo/bar/baz`, the base URL of the themes
      * folder will be `baz/`; this ensures BC to Pico < 2.0). Pico's base URL
      * always gets prepended appropriately.
@@ -1831,8 +1836,8 @@ class Pico
     /**
      * Filters a URL GET parameter with a specified filter
      *
-     * This method is just an alias for {@link Pico::filterVariable()}, see
-     * {@link Pico::filterVariable()} for a detailed description. It can be
+     * This method is just an alias for {@see Pico::filterVariable()}, see
+     * {@see Pico::filterVariable()} for a detailed description. It can be
      * used in Twig templates by calling the `url_param` function.
      *
      * @see    Pico::filterVariable()
@@ -1856,8 +1861,8 @@ class Pico
     /**
      * Filters a HTTP POST parameter with a specified filter
      *
-     * This method is just an alias for {@link Pico::filterVariable()}, see
-     * {@link Pico::filterVariable()} for a detailed description. It can be
+     * This method is just an alias for {@see Pico::filterVariable()}, see
+     * {@see Pico::filterVariable()} for a detailed description. It can be
      * used in Twig templates by calling the `form_param` function.
      *
      * @see    Pico::filterVariable()

lib/PicoPluginInterface.php

@@ -3,12 +3,12 @@
 /**
  * Common interface for Pico plugins
  *
- * For a list of supported events see {@link DummyPlugin}; you can use
- * {@link DummyPlugin} as template for new plugins. For a list of deprecated
- * events see {@link PicoDeprecated}.
+ * For a list of supported events see {@see DummyPlugin}; you can use
+ * {@see DummyPlugin} as template for new plugins. For a list of deprecated
+ * events see {@see PicoDeprecated}.
  *
  * You SHOULD NOT use deprecated events when implementing this interface.
- * Deprecated events are triggered by the {@link PicoDeprecated} plugin, if
+ * Deprecated events are triggered by the {@see PicoDeprecated} plugin, if
  * plugins which don't implement this interface are loaded. You can take
  * advantage from this behaviour if you want to do something only when old
  * plugins are loaded. Consequently the old events are never triggered when

plugins/DummyPlugin.php

@@ -122,38 +122,42 @@ class DummyPlugin extends AbstractPicoPlugin
     }
 
     /**
-     * Triggered after Pico has read the contents of the file to serve
+     * Triggered before Pico reads the contents of a 404 file
      *
-     * @see    Pico::getRawContent()
-     * @param  string &$rawContent raw file contents
+     * @see    Pico::load404Content()
+     * @see    DummyPlugin::on404ContentLoaded()
+     * @param  string &$file path to the file which contents were requested
      * @return void
      */
-    public function onContentLoaded(&$rawContent)
+    public function on404ContentLoading(&$file)
     {
         // your code
     }
 
     /**
-     * Triggered before Pico reads the contents of a 404 file
+     * Triggered after Pico has read the contents of the 404 file
      *
-     * @see    Pico::load404Content()
-     * @see    DummyPlugin::on404ContentLoaded()
-     * @param  string &$file path to the file which contents were requested
+     * @see    Pico::getRawContent()
+     * @param  string &$rawContent raw file contents
      * @return void
      */
-    public function on404ContentLoading(&$file)
+    public function on404ContentLoaded(&$rawContent)
     {
         // your code
     }
 
     /**
-     * Triggered after Pico has read the contents of the 404 file
+     * Triggered after Pico has read the contents of the file to serve
+     *
+     * If Pico serves a 404 file, this event is triggered with the raw contents
+     * of said 404 file. Use {@see Pico::is404Content()} to check for this
+     * case when necessary.
      *
      * @see    Pico::getRawContent()
      * @param  string &$rawContent raw file contents
      * @return void
      */
-    public function on404ContentLoaded(&$rawContent)
+    public function onContentLoaded(&$rawContent)
     {
         // your code
     }
@@ -273,18 +277,21 @@ class DummyPlugin extends AbstractPicoPlugin
      *
      * The `$pageData` parameter consists of the following values:
      *
-     * | Array key      | Type   | Description                              |
-     * | -------------- | ------ | ---------------------------------------- |
-     * | id             | string | relative path to the content file        |
-     * | url            | string | URL to the page                          |
-     * | title          | string | title of the page (YAML header)          |
-     * | description    | string | description of the page (YAML header)    |
-     * | author         | string | author of the page (YAML header)         |
-     * | time           | string | timestamp derived from the Date header   |
-     * | date           | string | date of the page (YAML header)           |
-     * | date_formatted | string | formatted date of the page               |
-     * | raw_content    | string | raw, not yet parsed contents of the page |
-     * | meta           | string | parsed meta data of the page             |
+     * | Array key      | Type    | Description                                |
+     * | -------------- | ------- | ------------------------------------------ |
+     * | id             | string  | relative path to the content file          |
+     * | url            | string  | URL to the page                            |
+     * | title          | string  | title of the page (YAML header)            |
+     * | description    | string  | description of the page (YAML header)      |
+     * | author         | string  | author of the page (YAML header)           |
+     * | time           | string  | timestamp derived from the Date header     |
+     * | date           | string  | date of the page (YAML header)             |
+     * | date_formatted | string  | formatted date of the page                 |
+     * | hidden         | boolean | this page shouldn't be visible to the user |
+     * | raw_content    | string  | raw, not yet parsed contents of the page   |
+     * | meta           | string  | parsed meta data of the page               |
+     * | previous_page  | &array  | reference to the previous page             |
+     * | next_page      | &array  | reference to the next page                 |
      *
      * Set `$pageData` to `null` to remove this page from the pages array.
      *
@@ -301,7 +308,7 @@ class DummyPlugin extends AbstractPicoPlugin
     /**
      * Triggered after Pico has discovered all known pages
      *
-     * See {@link DummyPlugin::onSinglePageLoaded()} for details about the
+     * See {@see DummyPlugin::onSinglePageLoaded()} for details about the
      * structure of the page data. Please note that the pages array isn't
      * sorted yet.
      *
@@ -318,7 +325,7 @@ class DummyPlugin extends AbstractPicoPlugin
     /**
      * Triggered after Pico has sorted the pages array
      *
-     * See {@link DummyPlugin::onSinglePageLoaded()} for details about the
+     * See {@see DummyPlugin::onSinglePageLoaded()} for details about the
      * structure of the page data.
      *
      * @see    Pico::getPages()
@@ -333,7 +340,7 @@ class DummyPlugin extends AbstractPicoPlugin
     /**
      * Triggered when Pico discovered the current, previous and next pages
      *
-     * See {@link DummyPlugin::onSinglePageLoaded()} for details about the
+     * See {@see DummyPlugin::onSinglePageLoaded()} for details about the
      * structure of the page data.
      *
      * @see    Pico::discoverPageSiblings()