From 624310bbe704ac0ca4bbb53479f01640fe5666a0 Mon Sep 17 00:00:00 2001 From: Daniel Rudolf Date: Sat, 13 May 2017 18:17:58 +0200 Subject: [PATCH] Various small improvements --- lib/AbstractPicoPlugin.php | 6 ++-- lib/Pico.php | 61 ++++++++++++++++++++----------------- lib/PicoPluginInterface.php | 8 ++--- plugins/DummyPlugin.php | 61 +++++++++++++++++++++---------------- 4 files changed, 74 insertions(+), 62 deletions(-) diff --git a/lib/AbstractPicoPlugin.php b/lib/AbstractPicoPlugin.php index d767579..7c8b5f8 100644 --- a/lib/AbstractPicoPlugin.php +++ b/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 diff --git a/lib/Pico.php b/lib/Pico.php index 7d54f9a..69be0bd 100644 --- a/lib/Pico.php +++ b/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() diff --git a/lib/PicoPluginInterface.php b/lib/PicoPluginInterface.php index 337a8ba..1bba28e 100644 --- a/lib/PicoPluginInterface.php +++ b/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 diff --git a/plugins/DummyPlugin.php b/plugins/DummyPlugin.php index d2e76e8..d06d17f 100644 --- a/plugins/DummyPlugin.php +++ b/plugins/DummyPlugin.php @@ -121,18 +121,6 @@ class DummyPlugin extends AbstractPicoPlugin // your code } - /** - * Triggered after Pico has read the contents of the file to serve - * - * @see Pico::getRawContent() - * @param string &$rawContent raw file contents - * @return void - */ - public function onContentLoaded(&$rawContent) - { - // your code - } - /** * Triggered before Pico reads the contents of a 404 file * @@ -158,6 +146,22 @@ class DummyPlugin extends AbstractPicoPlugin // your code } + /** + * 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 onContentLoaded(&$rawContent) + { + // your code + } + /** * Triggered when Pico reads its known meta header fields * @@ -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()