SeaCMS/pico
3
0
Fork 0
Code Issues Pull Requests Activity

Add license/copyright file header; improve phpDoc class docs

Browse Source
This commit is contained in:
Daniel Rudolf 2017-10-19 21:55:41 +02:00
parent d8a649e6f7
commit 61319b011e
No known key found for this signature in database
GPG Key ID: A061F02CD8DE4538
6 changed files with 518 additions and 322 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

7
composer.json
View File

@ -13,8 +13,11 @@
}, },
{ {
"name": "The Pico Community", "name": "The Pico Community",
"homepage": "https://github.com/picocms/Pico/graphs/contributors", "homepage": "http://picocms.org/"
"role": "Contributors" },
{
"name": "Contributors",
"homepage": "https://github.com/picocms/Pico/graphs/contributors"
} }
], ],
"support": { "support": {

65
lib/AbstractPicoPlugin.php
View File

@ -1,4 +1,14 @@
<?php <?php
/**
* This file is part of Pico. It's copyrighted by the contributors recorded
* in the version control history of the file, available from the following
* original location:
*
* <https://github.com/picocms/Pico/blob/master/lib/AbstractPicoPlugin.php>
*
* SPDX-License-Identifier: MIT
* License-Filename: LICENSE
*/
/** /**
* Abstract class to extend from when implementing a Pico plugin * Abstract class to extend from when implementing a Pico plugin
@ -24,11 +34,11 @@ abstract class AbstractPicoPlugin implements PicoPluginInterface
private $pico; private $pico;
/** /**
* Boolean indicating if this plugin is enabled (true) or disabled (false) * Boolean indicating if this plugin is enabled (TRUE) or disabled (FALSE)
* *
* @see PicoPluginInterface::isEnabled() * @see PicoPluginInterface::isEnabled()
* @see PicoPluginInterface::setEnabled() * @see PicoPluginInterface::setEnabled()
* @var boolean * @var bool
*/ */
protected $enabled = true; protected $enabled = true;
@ -36,7 +46,7 @@ abstract class AbstractPicoPlugin implements PicoPluginInterface
* Boolean indicating if this plugin was ever enabled/disabled manually * Boolean indicating if this plugin was ever enabled/disabled manually
* *
* @see PicoPluginInterface::isStatusChanged() * @see PicoPluginInterface::isStatusChanged()
* @var boolean * @var bool
*/ */
protected $statusChanged = false; protected $statusChanged = false;
@ -44,7 +54,7 @@ abstract class AbstractPicoPlugin implements PicoPluginInterface
* Boolean indicating whether this plugin matches Pico's API version * Boolean indicating whether this plugin matches Pico's API version
* *
* @see AbstractPicoPlugin::checkCompatibility() * @see AbstractPicoPlugin::checkCompatibility()
* @var boolean|null * @var bool|null
*/ */
protected $nativePlugin; protected $nativePlugin;
@ -152,14 +162,14 @@ abstract class AbstractPicoPlugin implements PicoPluginInterface
* Returns either the value of the specified plugin config variable or * Returns either the value of the specified plugin config variable or
* the config array * the config array
* *
* @param string $configName optional name of a config variable * @param string $configName optional name of a config variable
* @param mixed $default optional default value to return when the * @param mixed $default optional default value to return when the
* named config variable doesn't exist * named config variable doesn't exist
* @return mixed if no name of a config variable has been *
* supplied, the plugin's config array is returned; otherwise it * @return mixed if no name of a config variable has been supplied, the
* returns either the value of the named config variable, or, if the * plugin's config array is returned; otherwise it returns either the
* named config variable doesn't exist, the provided default value * value of the named config variable, or, if the named config variable
* or NULL * doesn't exist, the provided default value or NULL
*/ */
public function getPluginConfig($configName = null, $default = null) public function getPluginConfig($configName = null, $default = null)
{ {
@ -175,10 +185,12 @@ abstract class AbstractPicoPlugin implements PicoPluginInterface
/** /**
* Passes all not satisfiable method calls to Pico * Passes all not satisfiable method calls to Pico
* *
* @see Pico * @see Pico
* @param string $methodName name of the method to call *
* @param array $params parameters to pass * @param string $methodName name of the method to call
* @return mixed return value of the called method * @param array $params parameters to pass
*
* @return mixed return value of the called method
*/ */
public function __call($methodName, array $params) public function __call($methodName, array $params)
{ {
@ -195,10 +207,13 @@ abstract class AbstractPicoPlugin implements PicoPluginInterface
/** /**
* Enables all plugins which this plugin depends on * Enables all plugins which this plugin depends on
* *
* @see PicoPluginInterface::getDependencies() * @see PicoPluginInterface::getDependencies()
* @param boolean $recursive enable required plugins automatically *
* @param bool $recursive enable required plugins automatically
*
* @return void * @return void
* @throws RuntimeException thrown when a dependency fails *
* @throws RuntimeException thrown when a dependency fails
*/ */
protected function checkDependencies($recursive) protected function checkDependencies($recursive)
{ {
@ -244,10 +259,13 @@ abstract class AbstractPicoPlugin implements PicoPluginInterface
/** /**
* Disables all plugins which depend on this plugin * Disables all plugins which depend on this plugin
* *
* @see PicoPluginInterface::getDependants() * @see PicoPluginInterface::getDependants()
* @param boolean $recursive disabled dependant plugins automatically *
* @param bool $recursive disabled dependant plugins automatically
*
* @return void * @return void
* @throws RuntimeException thrown when a dependency fails *
* @throws RuntimeException thrown when a dependency fails
*/ */
protected function checkDependants($recursive) protected function checkDependants($recursive)
{ {
@ -308,8 +326,9 @@ abstract class AbstractPicoPlugin implements PicoPluginInterface
* newer API versions, what defaults to "no" by default. * newer API versions, what defaults to "no" by default.
* *
* @return void * @return void
* @throws RuntimeException thrown when the plugin's and Pico's API *
* aren't compatible * @throws RuntimeException thrown when the plugin's and Pico's API aren't
* compatible
*/ */
protected function checkCompatibility() protected function checkCompatibility()
{ {

398
lib/Pico.php
View File

@ -1,4 +1,20 @@
<?php <?php
/**
* This file is part of Pico. It's copyrighted by the contributors recorded
* in the version control history of the file, available from the following
* original location:
*
* <https://github.com/picocms/Pico/blob/master/lib/Pico.php>
*
* The file has been renamed in the past; the version control history of the
* original file applies accordingly, available from the following original
* location:
*
* <https://github.com/picocms/Pico/blob/adc356251ecd79689935ec1446c7c846db167d46/lib/pico.php>
*
* SPDX-License-Identifier: MIT
* License-Filename: LICENSE
*/
/** /**
* Pico * Pico
@ -116,7 +132,7 @@ class Pico
/** /**
* Boolean indicating whether Pico started processing yet * Boolean indicating whether Pico started processing yet
* *
* @var boolean * @var bool
*/ */
protected $locked = false; protected $locked = false;
@ -180,7 +196,7 @@ class Pico
* Boolean indicating whether Pico is serving a 404 page * Boolean indicating whether Pico is serving a 404 page
* *
* @see Pico::is404Content() * @see Pico::is404Content()
* @var boolean * @var bool
*/ */
protected $is404Content = false; protected $is404Content = false;
@ -359,8 +375,9 @@ class Pico
* meta headers, processes Markdown, does Twig processing and returns * meta headers, processes Markdown, does Twig processing and returns
* the rendered contents. * the rendered contents.
* *
* @return string rendered Pico contents * @return string rendered Pico contents
* @throws Exception thrown when a not recoverable error occurs *
* @throws Exception thrown when a irrecoverable error occurs
*/ */
public function run() public function run()
{ {
@ -470,10 +487,12 @@ class Pico
* incorporate plugin dependencies. See {@see Pico::sortPlugins()} for * incorporate plugin dependencies. See {@see Pico::sortPlugins()} for
* details. * details.
* *
* @see Pico::loadPlugin() * @see Pico::loadPlugin()
* @see Pico::getPlugin() * @see Pico::getPlugin()
* @see Pico::getPlugins() * @see Pico::getPlugins()
*
* @return void * @return void
*
* @throws RuntimeException thrown when a plugin couldn't be loaded * @throws RuntimeException thrown when a plugin couldn't be loaded
*/ */
protected function loadPlugins() protected function loadPlugins()
@ -492,10 +511,12 @@ class Pico
* `picocms/pico-installer` installer by reading the `pico-plugin.php` in * `picocms/pico-installer` installer by reading the `pico-plugin.php` in
* composer's `vendor` dir. * composer's `vendor` dir.
* *
* @see Pico::loadPlugins() * @see Pico::loadPlugins()
* @see Pico::loadLocalPlugins() * @see Pico::loadLocalPlugins()
* @param string[] $pluginBlacklist class names of plugins not to load *
* @return string[] installer names of the loaded plugins * @param string[] $pluginBlacklist class names of plugins not to load
*
* @return string[] installer names of the loaded plugins
*/ */
protected function loadComposerPlugins(array $pluginBlacklist = array()) protected function loadComposerPlugins(array $pluginBlacklist = array())
{ {
@ -558,10 +579,13 @@ class Pico
* - 60 to 79: Plugins hooking into template or markdown parsing * - 60 to 79: Plugins hooking into template or markdown parsing
* - 80 to 99: Plugins using the `onPageRendered` event * - 80 to 99: Plugins using the `onPageRendered` event
* *
* @see Pico::loadPlugins() * @see Pico::loadPlugins()
* @see Pico::loadComposerPlugins() * @see Pico::loadComposerPlugins()
* @param string[] $pluginBlacklist class names of plugins not to load *
* @param string[] $pluginBlacklist class names of plugins not to load
*
* @return void * @return void
*
* @throws RuntimeException thrown when a plugin couldn't be loaded * @throws RuntimeException thrown when a plugin couldn't be loaded
*/ */
protected function loadLocalPlugins(array $pluginBlacklist = array()) protected function loadLocalPlugins(array $pluginBlacklist = array())
@ -646,14 +670,16 @@ class Pico
* *
* This method triggers the `onPluginManuallyLoaded` event. * This method triggers the `onPluginManuallyLoaded` event.
* *
* @see Pico::loadPlugins() * @see Pico::loadPlugins()
* @see Pico::getPlugin() * @see Pico::getPlugin()
* @see Pico::getPlugins() * @see Pico::getPlugins()
* @param PicoPluginInterface|string $plugin either the class name of a *
* @param PicoPluginInterface|string $plugin either the class name of a
* plugin to instantiate or a plugin instance * plugin to instantiate or a plugin instance
* @return PicoPluginInterface instance of the loaded plugin *
* @throws RuntimeException thrown when a plugin couldn't * @return PicoPluginInterface instance of the loaded plugin
* be loaded *
* @throws RuntimeException thrown when a plugin couldn't be loaded
*/ */
public function loadPlugin($plugin) public function loadPlugin($plugin)
{ {
@ -708,12 +734,13 @@ class Pico
* version 1.1.0, licensed under the MIT license. It uses the `ArraySort` * version 1.1.0, licensed under the MIT license. It uses the `ArraySort`
* implementation (class `\MJS\TopSort\Implementations\ArraySort`). * implementation (class `\MJS\TopSort\Implementations\ArraySort`).
* *
* @see Pico::loadPlugins() * @see Pico::loadPlugins()
* @see Pico::getPlugins() * @see Pico::getPlugins()
* @see https://github.com/marcj/topsort.php * @see https://github.com/marcj/topsort.php
* Marc J. Schmidt's Topological Sort / Dependency resolver in PHP * Marc J. Schmidt's Topological Sort / Dependency resolver in PHP
* @see https://github.com/marcj/topsort.php/blob/1.1.0/src/Implementations/ArraySort.php * @see https://github.com/marcj/topsort.php/blob/1.1.0/src/Implementations/ArraySort.php
* \MJS\TopSort\Implementations\ArraySort class * \MJS\TopSort\Implementations\ArraySort class
*
* @return void * @return void
*/ */
protected function sortPlugins() protected function sortPlugins()
@ -773,11 +800,14 @@ class Pico
* Plugins SHOULD implement {@see PicoPluginInterface}, but you MUST NOT * Plugins SHOULD implement {@see PicoPluginInterface}, but you MUST NOT
* rely on it. For more information see {@see PicoPluginInterface}. * rely on it. For more information see {@see PicoPluginInterface}.
* *
* @see Pico::loadPlugins() * @see Pico::loadPlugins()
* @see Pico::getPlugins() * @see Pico::getPlugins()
* @param string $pluginName name of the plugin *
* @return object instance of the plugin * @param string $pluginName name of the plugin
* @throws RuntimeException thrown when the plugin wasn't found *
* @return object instance of the plugin
*
* @throws RuntimeException thrown when the plugin wasn't found
*/ */
public function getPlugin($pluginName) public function getPlugin($pluginName)
{ {
@ -791,8 +821,9 @@ class Pico
/** /**
* Returns all loaded plugins * Returns all loaded plugins
* *
* @see Pico::loadPlugins() * @see Pico::loadPlugins()
* @see Pico::getPlugin() * @see Pico::getPlugin()
*
* @return object[]|null * @return object[]|null
*/ */
public function getPlugins() public function getPlugins()
@ -811,8 +842,9 @@ class Pico
* `test: { baz: 42 }` in `config/b.yml`, `{{ config.test.baz }}` will be * `test: { baz: 42 }` in `config/b.yml`, `{{ config.test.baz }}` will be
* undefined! * undefined!
* *
* @see Pico::setConfig() * @see Pico::setConfig()
* @see Pico::getConfig() * @see Pico::getConfig()
*
* @return void * @return void
*/ */
protected function loadConfig() protected function loadConfig()
@ -921,10 +953,13 @@ class Pico
* {@see Pico::run()} only. Options set with this method cannot be * {@see Pico::run()} only. Options set with this method cannot be
* overwritten by {@path "config/config.yml"}. * overwritten by {@path "config/config.yml"}.
* *
* @see Pico::loadConfig() * @see Pico::loadConfig()
* @see Pico::getConfig() * @see Pico::getConfig()
* @param array $config array with config variables *
* @param array $config array with config variables
*
* @return void * @return void
*
* @throws LogicException thrown if Pico already started processing * @throws LogicException thrown if Pico already started processing
*/ */
public function setConfig(array $config) public function setConfig(array $config)
@ -940,15 +975,17 @@ class Pico
* Returns either the value of the specified config variable or * Returns either the value of the specified config variable or
* the config array * the config array
* *
* @see Pico::setConfig() * @see Pico::setConfig()
* @see Pico::loadConfig() * @see Pico::loadConfig()
* @param string $configName optional name of a config variable *
* @param mixed $default optional default value to return when the * @param string $configName optional name of a config variable
* @param mixed $default optional default value to return when the
* named config variable doesn't exist * named config variable doesn't exist
* @return mixed if no name of a config variable has been *
* supplied, the config array is returned; otherwise it returns either * @return mixed if no name of a config variable has been supplied, the
* the value of the named config variable, or, if the named config * config array is returned; otherwise it returns either the value of
* variable doesn't exist, the provided default value or NULL * the named config variable, or, if the named config variable doesn't
* exist, the provided default value or NULL
*/ */
public function getConfig($configName = null, $default = null) public function getConfig($configName = null, $default = null)
{ {
@ -994,7 +1031,8 @@ class Pico
* Pico interprets `someBooleanParam` as name of the requested page. Use * Pico interprets `someBooleanParam` as name of the requested page. Use
* `/pico/?someBooleanParam=` or `/pico/?index&someBooleanParam` instead. * `/pico/?someBooleanParam=` or `/pico/?index&someBooleanParam` instead.
* *
* @see Pico::getRequestUrl() * @see Pico::getRequestUrl()
*
* @return void * @return void
*/ */
protected function evaluateRequestUrl() protected function evaluateRequestUrl()
@ -1030,7 +1068,8 @@ class Pico
/** /**
* Returns the URL where a user requested the page * Returns the URL where a user requested the page
* *
* @see Pico::evaluateRequestUrl() * @see Pico::evaluateRequestUrl()
*
* @return string|null request URL * @return string|null request URL
*/ */
public function getRequestUrl() public function getRequestUrl()
@ -1048,9 +1087,11 @@ class Pico
* RECOMMENDED to use PHP's `open_basedir` feature - always, not just * RECOMMENDED to use PHP's `open_basedir` feature - always, not just
* with Pico! * with Pico!
* *
* @see Pico::getRequestFile() * @see Pico::getRequestFile()
* @param string $requestUrl path name (likely from a URL) to resolve *
* @return string path to the resolved content file * @param string $requestUrl path name (likely from a URL) to resolve
*
* @return string path to the resolved content file
*/ */
public function resolveFilePath($requestUrl) public function resolveFilePath($requestUrl)
{ {
@ -1099,8 +1140,9 @@ class Pico
/** /**
* Returns the absolute path to the content file to serve * Returns the absolute path to the content file to serve
* *
* @see Pico::resolveFilePath() * @see Pico::resolveFilePath()
* @return string|null file path *
* @return string|null file pat
*/ */
public function getRequestFile() public function getRequestFile()
{ {
@ -1110,9 +1152,11 @@ class Pico
/** /**
* Returns the raw contents of a file * Returns the raw contents of a file
* *
* @see Pico::getRawContent() * @see Pico::getRawContent()
* @param string $file file path *
* @return string raw contents of the file * @param string $file file path
*
* @return string raw contents of the file
*/ */
public function loadFileContent($file) public function loadFileContent($file)
{ {
@ -1125,9 +1169,11 @@ class Pico
* *
* If no suitable `404.md` is found, fallback to a built-in error message. * If no suitable `404.md` is found, fallback to a built-in error message.
* *
* @see Pico::getRawContent() * @see Pico::getRawContent()
* @param string $file path to requested (but not existing) file *
* @return string raw contents of the 404 file * @param string $file path to requested (but not existing) file
*
* @return string raw contents of the 404 file
*/ */
public function load404Content($file) public function load404Content($file)
{ {
@ -1165,8 +1211,9 @@ class Pico
/** /**
* Returns the raw contents, either of the requested or the 404 file * Returns the raw contents, either of the requested or the 404 file
* *
* @see Pico::loadFileContent() * @see Pico::loadFileContent()
* @see Pico::load404Content() * @see Pico::load404Content()
*
* @return string|null raw contents * @return string|null raw contents
*/ */
public function getRawContent() public function getRawContent()
@ -1177,8 +1224,9 @@ class Pico
/** /**
* Returns TRUE when Pico is serving a 404 page * Returns TRUE when Pico is serving a 404 page
* *
* @see Pico::load404Content() * @see Pico::load404Content()
* @return boolean TRUE if Pico is serving a 404 page, FALSE otherwise *
* @return bool TRUE if Pico is serving a 404 page, FALSE otherwise
*/ */
public function is404Content() public function is404Content()
{ {
@ -1191,8 +1239,8 @@ class Pico
* This method triggers the `onMetaHeaders` event when the known meta * This method triggers the `onMetaHeaders` event when the known meta
* headers weren't assembled yet. * headers weren't assembled yet.
* *
* @return string[] known meta headers; the array value specifies the * @return string[] known meta headers; the array key specifies the YAML
* YAML key to search for, the array key is later used to access the * key to search for, the array value is later used to access the
* found value * found value
*/ */
public function getMetaHeaders() public function getMetaHeaders()
@ -1241,10 +1289,13 @@ class Pico
* `onMetaHeaders` event first. The implicit availability of headers is * `onMetaHeaders` event first. The implicit availability of headers is
* for users and pure (!) theme developers ONLY. * for users and pure (!) theme developers ONLY.
* *
* @see Pico::getFileMeta() * @see Pico::getFileMeta()
* @param string $rawContent the raw file contents *
* @param string[] $headers known meta headers * @param string $rawContent the raw file contents
* @return array parsed meta data * @param string[] $headers known meta headers
*
* @return array parsed meta data
*
* @throws \Symfony\Component\Yaml\Exception\ParseException thrown when the * @throws \Symfony\Component\Yaml\Exception\ParseException thrown when the
* meta data is invalid * meta data is invalid
*/ */
@ -1305,7 +1356,8 @@ class Pico
/** /**
* Returns the parsed meta data of the requested page * Returns the parsed meta data of the requested page
* *
* @see Pico::parseFileMeta() * @see Pico::parseFileMeta()
*
* @return array|null parsed meta data * @return array|null parsed meta data
*/ */
public function getFileMeta() public function getFileMeta()
@ -1343,12 +1395,14 @@ class Pico
* *
* This method calls the {@see Pico::substituteFileContent()} method. * This method calls the {@see Pico::substituteFileContent()} method.
* *
* @see Pico::substituteFileContent() * @see Pico::substituteFileContent()
* @see Pico::parseFileContent() * @see Pico::parseFileContent()
* @see Pico::getFileContent() * @see Pico::getFileContent()
* @param string $rawContent raw contents of a page *
* @param array $meta meta data to use for %meta.*% replacement * @param string $rawContent raw contents of a page
* @return string prepared Markdown contents * @param array $meta meta data to use for %meta.*% replacement
*
* @return string prepared Markdown contents
*/ */
public function prepareFileContent($rawContent, array $meta) public function prepareFileContent($rawContent, array $meta)
{ {
@ -1366,9 +1420,10 @@ class Pico
/** /**
* Replaces all %...% placeholders in a page's contents * Replaces all %...% placeholders in a page's contents
* *
* @param string $markdown Markdown contents of a page * @param string $markdown Markdown contents of a page
* @param array $meta meta data to use for %meta.*% replacement * @param array $meta meta data to use for %meta.*% replacement
* @return string substituted Markdown contents *
* @return string substituted Markdown contents
*/ */
public function substituteFileContent($markdown, array $meta = array()) public function substituteFileContent($markdown, array $meta = array())
{ {
@ -1409,11 +1464,13 @@ class Pico
/** /**
* Parses the contents of a page using ParsedownExtra * Parses the contents of a page using ParsedownExtra
* *
* @see Pico::prepareFileContent() * @see Pico::prepareFileContent()
* @see Pico::substituteFileContent() * @see Pico::substituteFileContent()
* @see Pico::getFileContent() * @see Pico::getFileContent()
* @param string $markdown Markdown contents of a page *
* @return string parsed contents (HTML) * @param string $markdown Markdown contents of a page
*
* @return string parsed contents (HTML)
*/ */
public function parseFileContent($markdown) public function parseFileContent($markdown)
{ {
@ -1423,9 +1480,10 @@ class Pico
/** /**
* Returns the cached contents of the requested page * Returns the cached contents of the requested page
* *
* @see Pico::prepareFileContent() * @see Pico::prepareFileContent()
* @see Pico::substituteFileContent() * @see Pico::substituteFileContent()
* @see Pico::parseFileContent() * @see Pico::parseFileContent()
*
* @return string|null parsed contents * @return string|null parsed contents
*/ */
public function getFileContent() public function getFileContent()
@ -1448,19 +1506,20 @@ class Pico
* | time | string | timestamp derived from the Date header | * | time | string | timestamp derived from the Date header |
* | date | string | date of the page (YAML header) | * | date | string | date of the page (YAML header) |
* | date_formatted | string | formatted date of the page | * | date_formatted | string | formatted date of the page |
* | hidden | boolean | this page shouldn't be visible to the user | * | hidden | bool | this page shouldn't be visible to the user |
* | raw_content | string | raw, not yet parsed contents of the page | * | raw_content | string | raw, not yet parsed contents of the page |
* | meta | string | parsed meta data of the page | * | meta | string | parsed meta data of the page |
* | previous_page | &array | reference to the previous page | * | previous_page | &array | reference to the previous page |
* | next_page | &array | reference to the next page | * | next_page | &array | reference to the next page |
* *
* Please note that the `previous_page` and `next_page` keys won't be * Please note that the `previous_page` and `next_page` keys won't be
* available until the `onCurrentPageDiscovered` event * available until the `onCurrentPageDiscovered` event was triggered
* ({@see Pico::discoverPageSiblings()}) was triggered. * ({@see Pico::discoverPageSiblings()}).
*
* @see Pico::sortPages()
* @see Pico::discoverPageSiblings()
* @see Pico::getPages()
* *
* @see Pico::sortPages()
* @see Pico::discoverPageSiblings()
* @see Pico::getPages()
* @return void * @return void
*/ */
protected function readPages() protected function readPages()
@ -1545,8 +1604,9 @@ class Pico
/** /**
* Sorts all pages known to Pico * Sorts all pages known to Pico
* *
* @see Pico::readPages() * @see Pico::readPages()
* @see Pico::getPages() * @see Pico::getPages()
*
* @return void * @return void
*/ */
protected function sortPages() protected function sortPages()
@ -1625,8 +1685,9 @@ class Pico
* Walks through the list of all known pages and discovers the previous and * Walks through the list of all known pages and discovers the previous and
* next page respectively * next page respectively
* *
* @see Pico::readPages() * @see Pico::readPages()
* @see Pico::getPages() * @see Pico::getPages()
*
* @return void * @return void
*/ */
protected function discoverPageSiblings() protected function discoverPageSiblings()
@ -1661,7 +1722,8 @@ class Pico
/** /**
* Returns the list of known pages * Returns the list of known pages
* *
* @see Pico::readPages() * @see Pico::readPages()
*
* @return array[]|null the data of all pages * @return array[]|null the data of all pages
*/ */
public function getPages() public function getPages()
@ -1673,9 +1735,10 @@ class Pico
* Discovers the page data of the requested page as well as the previous * Discovers the page data of the requested page as well as the previous
* and next page relative to it * and next page relative to it
* *
* @see Pico::getCurrentPage() * @see Pico::getCurrentPage()
* @see Pico::getPreviousPage() * @see Pico::getPreviousPage()
* @see Pico::getNextPage() * @see Pico::getNextPage()
*
* @return void * @return void
*/ */
protected function discoverCurrentPage() protected function discoverCurrentPage()
@ -1691,7 +1754,8 @@ class Pico
/** /**
* Returns the data of the requested page * Returns the data of the requested page
* *
* @see Pico::discoverCurrentPage() * @see Pico::discoverCurrentPage()
*
* @return array|null page data * @return array|null page data
*/ */
public function getCurrentPage() public function getCurrentPage()
@ -1702,7 +1766,8 @@ class Pico
/** /**
* Returns the data of the previous page relative to the page being served * Returns the data of the previous page relative to the page being served
* *
* @see Pico::discoverCurrentPage() * @see Pico::discoverCurrentPage()
*
* @return array|null page data * @return array|null page data
*/ */
public function getPreviousPage() public function getPreviousPage()
@ -1713,7 +1778,8 @@ class Pico
/** /**
* Returns the data of the next page relative to the page being served * Returns the data of the next page relative to the page being served
* *
* @see Pico::discoverCurrentPage() * @see Pico::discoverCurrentPage()
*
* @return array|null page data * @return array|null page data
*/ */
public function getNextPage() public function getNextPage()
@ -1729,9 +1795,10 @@ class Pico
* registers Pico's core Twig filters `link` and `content` as well as * registers Pico's core Twig filters `link` and `content` as well as
* Pico's {@see PicoTwigExtension} Twig extension. * Pico's {@see PicoTwigExtension} Twig extension.
* *
* @see Pico::getTwig() * @see Pico::getTwig()
* @see http://twig.sensiolabs.org/ Twig website * @see http://twig.sensiolabs.org/ Twig website
* @see https://github.com/twigphp/Twig Twig on GitHub * @see https://github.com/twigphp/Twig Twig on GitHub
*
* @return Twig_Environment|null Twig template engine * @return Twig_Environment|null Twig template engine
*/ */
public function getTwig() public function getTwig()
@ -1857,7 +1924,7 @@ class Pico
/** /**
* Returns TRUE if URL rewriting is enabled * Returns TRUE if URL rewriting is enabled
* *
* @return boolean TRUE if URL rewriting is enabled, FALSE otherwise * @return bool TRUE if URL rewriting is enabled, FALSE otherwise
*/ */
public function isUrlRewritingEnabled() public function isUrlRewritingEnabled()
{ {
@ -1883,12 +1950,13 @@ class Pico
* This method can be used in Twig templates by applying the `link` filter * This method can be used in Twig templates by applying the `link` filter
* to a string representing a page identifier. * to a string representing a page identifier.
* *
* @param string $page identifier of the page to link to * @param string $page identifier of the page to link to
* @param array|string $queryData either an array containing properties to * @param array|string $queryData either an array containing properties to
* create a URL-encoded query string from, or a already encoded string * create a URL-encoded query string from, or a already encoded string
* @param boolean $dropIndex when the last path component is "index", * @param bool $dropIndex when the last path component is "index",
* then passing TRUE (default) leads to removing this path component * then passing TRUE (default) leads to removing this path component
* @return string URL *
* @return string URL
*/ */
public function getPageUrl($page, $queryData = null, $dropIndex = true) public function getPageUrl($page, $queryData = null, $dropIndex = true)
{ {
@ -1928,8 +1996,9 @@ class Pico
/** /**
* Returns the page ID of a given content file * Returns the page ID of a given content file
* *
* @param string $path path to the content file * @param string $path path to the content file
* @return string|null either the corresponding page ID or NULL *
* @return string|null either the corresponding page ID or NULL
*/ */
public function getPageId($path) public function getPageId($path)
{ {
@ -1991,17 +2060,19 @@ class Pico
* {@see Pico::filterVariable()} for a detailed description. It can be * {@see Pico::filterVariable()} for a detailed description. It can be
* used in Twig templates by calling the `url_param` function. * used in Twig templates by calling the `url_param` function.
* *
* @see Pico::filterVariable() * @see Pico::filterVariable()
* @param string $name name of the URL GET parameter *
* @param string $name name of the URL GET parameter
* to filter * to filter
* @param int|string $filter the filter to apply * @param int|string $filter the filter to apply
* @param mixed|array $options either a associative options * @param mixed|array $options either a associative options
* array to be used by the filter or a scalar default value * array to be used by the filter or a scalar default value
* @param int|string|int[]|string[] $flags flags and flag strings to * @param int|string|int[]|string[] $flags flags and flag strings to be
* be used by the filter * used by the filter
* @return mixed either the filtered data, *
* FALSE if the filter fails, or NULL if the URL GET parameter doesn't * @return mixed either the filtered data, FALSE if the filter fails, or
* exist and no default value is given * NULL if the URL GET parameter doesn't exist and no default value is
* given
*/ */
public function getUrlParameter($name, $filter = '', $options = null, $flags = null) public function getUrlParameter($name, $filter = '', $options = null, $flags = null)
{ {
@ -2016,17 +2087,19 @@ class Pico
* {@see Pico::filterVariable()} for a detailed description. It can be * {@see Pico::filterVariable()} for a detailed description. It can be
* used in Twig templates by calling the `form_param` function. * used in Twig templates by calling the `form_param` function.
* *
* @see Pico::filterVariable() * @see Pico::filterVariable()
* @param string $name name of the HTTP POST *
* @param string $name name of the HTTP POST
* parameter to filter * parameter to filter
* @param int|string $filter the filter to apply * @param int|string $filter the filter to apply
* @param mixed|array $options either a associative options * @param mixed|array $options either a associative options
* array to be used by the filter or a scalar default value * array to be used by the filter or a scalar default value
* @param int|string|int[]|string[] $flags flags and flag strings to * @param int|string|int[]|string[] $flags flags and flag strings to be
* be used by the filter * used by the filter
* @return mixed either the filtered data, *
* FALSE if the filter fails, or NULL if the HTTP POST parameter * @return mixed either the filtered data, FALSE if the filter fails, or
* doesn't exist and no default value is given * NULL if the HTTP POST parameter doesn't exist and no default value
* is given
*/ */
public function getFormParameter($name, $filter = '', $options = null, $flags = null) public function getFormParameter($name, $filter = '', $options = null, $flags = null)
{ {
@ -2051,30 +2124,31 @@ class Pico
* sanitization filters; be very careful with sanitization filters, you * sanitization filters; be very careful with sanitization filters, you
* might create cross-site scripting vulnerabilities! * might create cross-site scripting vulnerabilities!
* *
* @see https://secure.php.net/manual/en/function.filter-var.php * @see https://secure.php.net/manual/en/function.filter-var.php
* PHP's `filter_var()` function * PHP's `filter_var()` function
* @see https://secure.php.net/manual/en/filter.filters.validate.php * @see https://secure.php.net/manual/en/filter.filters.validate.php
* Validate filters * Validate filters
* @see https://secure.php.net/manual/en/filter.filters.sanitize.php * @see https://secure.php.net/manual/en/filter.filters.sanitize.php
* Sanitize filters * Sanitize filters
* @param mixed $variable value to filter *
* @param int|string $filter ID (int) or name (string) of * @param mixed $variable value to filter
* @param int|string $filter ID (int) or name (string) of
* the filter to apply; if omitted, the method will return FALSE * the filter to apply; if omitted, the method will return FALSE
* @param mixed|array $options either a associative array * @param mixed|array $options either a associative array
* of options to be used by the filter (e.g. `array('default' => 42)`), * of options to be used by the filter (e.g. `array('default' => 42)`),
* or a scalar default value that will be returned when the passed * or a scalar default value that will be returned when the passed
* value is NULL (optional) * value is NULL (optional)
* @param int|string|int[]|string[] $flags either a bitwise disjunction * @param int|string|int[]|string[] $flags either a bitwise disjunction
* of flags or a string with the significant part of a flag constant * of flags or a string with the significant part of a flag constant
* (the constant name is the result of "FILTER_FLAG_" and the given * (the constant name is the result of "FILTER_FLAG_" and the given
* string in ASCII-only uppercase); you may also pass an array of flags * string in ASCII-only uppercase); you may also pass an array of flags
* and flag strings (optional) * and flag strings (optional)
* @return mixed with a validation filter, *
* the method either returns the validated value or, provided that the * @return mixed with a validation filter, the method either returns the
* value wasn't valid, the given default value or FALSE; with a * validated value or, provided that the value wasn't valid, the given
* sanitization filter, the method returns the sanitized value; if no * default value or FALSE; with a sanitization filter, the method
* value (i.e. NULL) was given, the method always returns either the * returns the sanitized value; if no value (i.e. NULL) was given, the
* provided default value or NULL * method always returns either the provided default value or NULL
*/ */
protected function filterVariable($variable, $filter = '', $options = null, $flags = null) protected function filterVariable($variable, $filter = '', $options = null, $flags = null)
{ {
@ -2116,14 +2190,15 @@ class Pico
* Recursively walks through a directory and returns all containing files * Recursively walks through a directory and returns all containing files
* matching the specified file extension * matching the specified file extension
* *
* @param string $directory start directory * @param string $directory start directory
* @param string $fileExtension return files with the given file extension * @param string $fileExtension return files with the given file extension
* only (optional) * only (optional)
* @param int $order specify whether and how files should be * @param int $order specify whether and how files should be
* sorted; use Pico::SORT_ASC for a alphabetical ascending order (this * sorted; use Pico::SORT_ASC for a alphabetical ascending order (this
* is the default behaviour), Pico::SORT_DESC for a descending order * is the default behaviour), Pico::SORT_DESC for a descending order
* or Pico::SORT_NONE to leave the result unsorted * or Pico::SORT_NONE to leave the result unsorted
* @return array list of found files *
* @return array list of found files
*/ */
public function getFiles($directory, $fileExtension = '', $order = self::SORT_ASC) public function getFiles($directory, $fileExtension = '', $order = self::SORT_ASC)
{ {
@ -2156,15 +2231,17 @@ class Pico
/** /**
* Returns all files in a directory matching a libc glob() pattern * Returns all files in a directory matching a libc glob() pattern
* *
* @see https://secure.php.net/manual/en/function.glob.php * @see https://secure.php.net/manual/en/function.glob.php
* PHP's glob() function * PHP's glob() function
* @param string $pattern the pattern to search for; see PHP's glob() *
* @param string $pattern the pattern to search for; see PHP's glob()
* function for details * function for details
* @param int $order specify whether and how files should be sorted; * @param int $order specify whether and how files should be sorted;
* use Pico::SORT_ASC for a alphabetical ascending order (this is the * use Pico::SORT_ASC for a alphabetical ascending order (this is the
* default behaviour), Pico::SORT_DESC for a descending order or * default behaviour), Pico::SORT_DESC for a descending order or
* Pico::SORT_NONE to leave the result unsorted * Pico::SORT_NONE to leave the result unsorted
* @return array list of found files *
* @return array list of found files
*/ */
public function getFilesGlob($pattern, $order = self::SORT_ASC) public function getFilesGlob($pattern, $order = self::SORT_ASC)
{ {
@ -2191,8 +2268,9 @@ class Pico
* *
* This method also guarantees a trailing slash. * This method also guarantees a trailing slash.
* *
* @param string $path relative or absolute path * @param string $path relative or absolute path
* @return string absolute path *
* @return string absolute path
*/ */
public function getAbsolutePath($path) public function getAbsolutePath($path)
{ {
@ -2219,11 +2297,13 @@ class Pico
* *
* You MUST NOT trigger events of Pico's core with a plugin! * You MUST NOT trigger events of Pico's core with a plugin!
* *
* @see PicoPluginInterface * @see PicoPluginInterface
* @see AbstractPicoPlugin * @see AbstractPicoPlugin
* @see DummyPlugin * @see DummyPlugin
* @param string $eventName name of the event to trigger *
* @param array $params optional parameters to pass * @param string $eventName name of the event to trigger
* @param array $params optional parameters to pass
*
* @return void * @return void
*/ */
public function triggerEvent($eventName, array $params = array()) public function triggerEvent($eventName, array $params = array())

51
lib/PicoPluginInterface.php
View File

@ -1,4 +1,14 @@
<?php <?php
/**
* This file is part of Pico. It's copyrighted by the contributors recorded
* in the version control history of the file, available from the following
* original location:
*
* <https://github.com/picocms/Pico/blob/master/lib/PicoPluginInterface.php>
*
* SPDX-License-Identifier: MIT
* License-Filename: LICENSE
*/
/** /**
* Common interface for Pico plugins * Common interface for Pico plugins
@ -30,8 +40,9 @@ interface PicoPluginInterface
/** /**
* Handles a event that was triggered by Pico * Handles a event that was triggered by Pico
* *
* @param string $eventName name of the triggered event * @param string $eventName name of the triggered event
* @param array $params passed parameters * @param array $params passed parameters
*
* @return void * @return void
*/ */
public function handleEvent($eventName, array $params); public function handleEvent($eventName, array $params);
@ -39,35 +50,40 @@ interface PicoPluginInterface
/** /**
* Enables or disables this plugin * Enables or disables this plugin
* *
* @see PicoPluginInterface::isEnabled() * @see PicoPluginInterface::isEnabled()
* @see PicoPluginInterface::isStatusChanged() * @see PicoPluginInterface::isStatusChanged()
* @param boolean $enabled enable (true) or disable (false) this plugin *
* @param boolean $recursive when true, enable or disable recursively * @param bool $enabled enable (TRUE) or disable (FALSE) this plugin
* @param bool $recursive when TRUE, enable or disable recursively.
* In other words, if you enable a plugin, all required plugins are * In other words, if you enable a plugin, all required plugins are
* enabled, too. When disabling a plugin, all depending plugins are * enabled, too. When disabling a plugin, all depending plugins are
* disabled likewise. Recursive operations are only performed as long * disabled likewise. Recursive operations are only performed as long
* as a plugin wasn't enabled/disabled manually. This parameter is * as a plugin wasn't enabled/disabled manually. This parameter is
* optional and defaults to true. * optional and defaults to TRUE.
* @param boolean $auto enable or disable to fulfill a dependency * @param bool $auto enable or disable to fulfill a dependency. This
* This parameter is optional and defaults to false. * parameter is optional and defaults to FALSE.
*
* @return void * @return void
* @throws RuntimeException thrown when a dependency fails *
* @throws RuntimeException thrown when a dependency fails
*/ */
public function setEnabled($enabled, $recursive = true, $auto = false); public function setEnabled($enabled, $recursive = true, $auto = false);
/** /**
* Returns true if this plugin is enabled, false otherwise * Returns TRUE if this plugin is enabled, FALSE otherwise
* *
* @see PicoPluginInterface::setEnabled() * @see PicoPluginInterface::setEnabled()
* @return boolean plugin is enabled (true) or disabled (false) *
* @return bool plugin is enabled (TRUE) or disabled (FALSE)
*/ */
public function isEnabled(); public function isEnabled();
/** /**
* Returns true if the plugin was ever enabled/disabled manually * Returns TRUE if the plugin was ever enabled/disabled manually
* *
* @see PicoPluginInterface::setEnabled() * @see PicoPluginInterface::setEnabled()
* @return boolean plugin is in its default state (true), false otherwise *
* @return bool plugin is in its default state (TRUE), FALSE otherwise
*/ */
public function isStatusChanged(); public function isStatusChanged();
@ -88,7 +104,8 @@ interface PicoPluginInterface
/** /**
* Returns the plugins instance of Pico * Returns the plugins instance of Pico
* *
* @see Pico * @see Pico
*
* @return Pico the plugins instance of Pico * @return Pico the plugins instance of Pico
*/ */
public function getPico(); public function getPico();

61
lib/PicoTwigExtension.php
View File

@ -1,4 +1,14 @@
<?php <?php
/**
* This file is part of Pico. It's copyrighted by the contributors recorded
* in the version control history of the file, available from the following
* original location:
*
* <https://github.com/picocms/Pico/blob/master/lib/PicoTwigExtension.php>
*
* SPDX-License-Identifier: MIT
* License-Filename: LICENSE
*/
/** /**
* Pico's Twig extension to implement additional filters * Pico's Twig extension to implement additional filters
@ -31,8 +41,9 @@ class PicoTwigExtension extends Twig_Extension
/** /**
* Returns the extensions instance of Pico * Returns the extensions instance of Pico
* *
* @see Pico * @see Pico
* @return Pico the extensions instance of Pico *
* @return Pico the extension's instance of Pico
*/ */
public function getPico() public function getPico()
{ {
@ -42,7 +53,8 @@ class PicoTwigExtension extends Twig_Extension
/** /**
* Returns the name of the extension * Returns the name of the extension
* *
* @see Twig_ExtensionInterface::getName() * @see Twig_ExtensionInterface::getName()
*
* @return string the extension name * @return string the extension name
*/ */
public function getName() public function getName()
@ -53,7 +65,8 @@ class PicoTwigExtension extends Twig_Extension
/** /**
* Returns a list of Pico-specific Twig filters * Returns a list of Pico-specific Twig filters
* *
* @see Twig_ExtensionInterface::getFilters() * @see Twig_ExtensionInterface::getFilters()
*
* @return Twig_SimpleFilter[] array of Pico's Twig filters * @return Twig_SimpleFilter[] array of Pico's Twig filters
*/ */
public function getFilters() public function getFilters()
@ -69,7 +82,8 @@ class PicoTwigExtension extends Twig_Extension
/** /**
* Returns a list of Pico-specific Twig functions * Returns a list of Pico-specific Twig functions
* *
* @see Twig_ExtensionInterface::getFunctions() * @see Twig_ExtensionInterface::getFunctions()
*
* @return Twig_SimpleFunction[] array of Pico's Twig functions * @return Twig_SimpleFunction[] array of Pico's Twig functions
*/ */
public function getFunctions() public function getFunctions()
@ -88,11 +102,13 @@ class PicoTwigExtension extends Twig_Extension
* Don't use it to parse the contents of a page, use the `content` filter * Don't use it to parse the contents of a page, use the `content` filter
* instead, what ensures the proper preparation of the contents. * instead, what ensures the proper preparation of the contents.
* *
* @see Pico::substituteFileContent() * @see Pico::substituteFileContent()
* @see Pico::parseFileContent() * @see Pico::parseFileContent()
* @param string $markdown markdown to parse *
* @param array $meta meta data to use for %meta.*% replacement * @param string $markdown markdown to parse
* @return string parsed HTML * @param array $meta meta data to use for %meta.*% replacement
*
* @return string parsed HTML
*/ */
public function markdownFilter($markdown, array $meta = array()) public function markdownFilter($markdown, array $meta = array())
{ {
@ -106,11 +122,12 @@ class PicoTwigExtension extends Twig_Extension
* This method is registered as the Twig `map` filter. You can use this * This method is registered as the Twig `map` filter. You can use this
* filter to e.g. get all page titles (`{{ pages|map("title") }}`). * filter to e.g. get all page titles (`{{ pages|map("title") }}`).
* *
* @param array|Traversable $var variable to map * @param array|Traversable $var variable to map
* @param mixed $mapKeyPath key to map; either a scalar or a * @param mixed $mapKeyPath key to map; either a scalar or a
* array interpreted as key path (i.e. ['foo', 'bar'] will return all * array interpreted as key path (i.e. ['foo', 'bar'] will return all
* $item['foo']['bar'] values) * $item['foo']['bar'] values)
* @return array mapped values *
* @return array mapped values
*/ */
public function mapFilter($var, $mapKeyPath) public function mapFilter($var, $mapKeyPath)
{ {
@ -140,16 +157,17 @@ class PicoTwigExtension extends Twig_Extension
* always sorted in ascending order, apply Twigs `reverse` filter to * always sorted in ascending order, apply Twigs `reverse` filter to
* achieve a descending order. * achieve a descending order.
* *
* @param array|Traversable $var variable to sort * @param array|Traversable $var variable to sort
* @param mixed $sortKeyPath key to use for sorting; either * @param mixed $sortKeyPath key to use for sorting; either
* a scalar or a array interpreted as key path (i.e. ['foo', 'bar'] * a scalar or a array interpreted as key path (i.e. ['foo', 'bar']
* will sort $var by $item['foo']['bar']) * will sort $var by $item['foo']['bar'])
* @param string $fallback specify what to do with items * @param string $fallback specify what to do with items
* which don't contain the specified sort key; use "bottom" (default) * which don't contain the specified sort key; use "bottom" (default)
* to move these items to the end of the sorted array, "top" to rank * to move these items to the end of the sorted array, "top" to rank
* them first, "keep" to keep the original order, or "remove" to remove * them first, "keep" to keep the original order, or "remove" to remove
* these items * these items
* @return array sorted array *
* @return array sorted array
*/ */
public function sortByFilter($var, $sortKeyPath, $fallback = 'bottom') public function sortByFilter($var, $sortKeyPath, $fallback = 'bottom')
{ {
@ -214,12 +232,13 @@ class PicoTwigExtension extends Twig_Extension
* Returns the value of a variable item specified by a scalar key or a * Returns the value of a variable item specified by a scalar key or a
* arbitrary deep sub-key using a key path * arbitrary deep sub-key using a key path
* *
* @param array|Traversable|ArrayAccess|object $var base variable * @param array|Traversable|ArrayAccess|object $var base variable
* @param mixed $keyPath scalar key or a * @param mixed $keyPath scalar key or a
* array interpreted as key path (when passing e.g. ['foo', 'bar'], * array interpreted as key path (when passing e.g. ['foo', 'bar'],
* the method will return $var['foo']['bar']) specifying the value * the method will return $var['foo']['bar']) specifying the value
* @return mixed the requested *
* value or NULL when the given key or key path didn't match * @return mixed the requested value or NULL when the given key or key path
* didn't match
*/ */
public static function getKeyOfVar($var, $keyPath) public static function getKeyOfVar($var, $keyPath)
{ {

258
plugins/DummyPlugin.php
View File

@ -1,4 +1,14 @@
<?php <?php
/**
* This file is part of Pico. It's copyrighted by the contributors recorded
* in the version control history of the file, available from the following
* original location:
*
* <https://github.com/picocms/Pico/blob/master/plugins/DummyPlugin.php>
*
* SPDX-License-Identifier: MIT
* License-Filename: LICENSE
*/
/** /**
* Pico dummy plugin - a template for plugins * Pico dummy plugin - a template for plugins
@ -27,7 +37,7 @@ class DummyPlugin extends AbstractPicoPlugin
* property. * property.
* *
* @see AbstractPicoPlugin::$enabled * @see AbstractPicoPlugin::$enabled
* @var boolean * @var bool
*/ */
protected $enabled = false; protected $enabled = false;
@ -48,9 +58,11 @@ class DummyPlugin extends AbstractPicoPlugin
* This event is triggered nevertheless the plugin is enabled or not. * This event is triggered nevertheless the plugin is enabled or not.
* It is NOT guaranteed that plugin dependencies are fulfilled! * It is NOT guaranteed that plugin dependencies are fulfilled!
* *
* @see Pico::getPlugin() * @see Pico::getPlugin()
* @see Pico::getPlugins() * @see Pico::getPlugins()
* @param object[] $plugins loaded plugin instances *
* @param object[] $plugins loaded plugin instances
*
* @return void * @return void
*/ */
public function onPluginsLoaded(array $plugins) public function onPluginsLoaded(array $plugins)
@ -61,9 +73,11 @@ class DummyPlugin extends AbstractPicoPlugin
/** /**
* Triggered when Pico manually loads a plugin * Triggered when Pico manually loads a plugin
* *
* @see Pico::getPlugin() * @see Pico::getPlugin()
* @see Pico::getPlugins() * @see Pico::getPlugins()
* @param object $plugin loaded plugin instance *
* @param object $plugin loaded plugin instance
*
* @return void * @return void
*/ */
public function onPluginManuallyLoaded($plugin) public function onPluginManuallyLoaded($plugin)
@ -74,8 +88,10 @@ class DummyPlugin extends AbstractPicoPlugin
/** /**
* Triggered after Pico has read its configuration * Triggered after Pico has read its configuration
* *
* @see Pico::getConfig() * @see Pico::getConfig()
* @param array &$config array of config variables *
* @param array &$config array of config variables
*
* @return void * @return void
*/ */
public function onConfigLoaded(array &$config) public function onConfigLoaded(array &$config)
@ -86,8 +102,10 @@ class DummyPlugin extends AbstractPicoPlugin
/** /**
* Triggered after Pico has evaluated the request URL * Triggered after Pico has evaluated the request URL
* *
* @see Pico::getRequestUrl() * @see Pico::getRequestUrl()
* @param string &$url part of the URL describing the requested contents *
* @param string &$url part of the URL describing the requested contents
*
* @return void * @return void
*/ */
public function onRequestUrl(&$url) public function onRequestUrl(&$url)
@ -98,9 +116,11 @@ class DummyPlugin extends AbstractPicoPlugin
/** /**
* Triggered after Pico has discovered the content file to serve * Triggered after Pico has discovered the content file to serve
* *
* @see Pico::getBaseUrl() * @see Pico::getBaseUrl()
* @see Pico::getRequestFile() * @see Pico::getRequestFile()
* @param string &$file absolute path to the content file to serve *
* @param string &$file absolute path to the content file to serve
*
* @return void * @return void
*/ */
public function onRequestFile(&$file) public function onRequestFile(&$file)
@ -111,8 +131,9 @@ class DummyPlugin extends AbstractPicoPlugin
/** /**
* Triggered before Pico reads the contents of the file to serve * Triggered before Pico reads the contents of the file to serve
* *
* @see Pico::loadFileContent() * @see Pico::loadFileContent()
* @see DummyPlugin::onContentLoaded() * @see DummyPlugin::onContentLoaded()
*
* @return void * @return void
*/ */
public function onContentLoading() public function onContentLoading()
@ -123,8 +144,9 @@ class DummyPlugin extends AbstractPicoPlugin
/** /**
* Triggered before Pico reads the contents of a 404 file * Triggered before Pico reads the contents of a 404 file
* *
* @see Pico::load404Content() * @see Pico::load404Content()
* @see DummyPlugin::on404ContentLoaded() * @see DummyPlugin::on404ContentLoaded()
*
* @return void * @return void
*/ */
public function on404ContentLoading() public function on404ContentLoading()
@ -135,8 +157,10 @@ class DummyPlugin extends AbstractPicoPlugin
/** /**
* Triggered after Pico has read the contents of the 404 file * Triggered after Pico has read the contents of the 404 file
* *
* @see Pico::getRawContent() * @see Pico::getRawContent()
* @param string &$rawContent raw file contents *
* @param string &$rawContent raw file contents
*
* @return void * @return void
*/ */
public function on404ContentLoaded(&$rawContent) public function on404ContentLoaded(&$rawContent)
@ -151,8 +175,10 @@ class DummyPlugin extends AbstractPicoPlugin
* of said 404 file. Use {@see Pico::is404Content()} to check for this * of said 404 file. Use {@see Pico::is404Content()} to check for this
* case when necessary. * case when necessary.
* *
* @see Pico::getRawContent() * @see Pico::getRawContent()
* @param string &$rawContent raw file contents *
* @param string &$rawContent raw file contents
*
* @return void * @return void
*/ */
public function onContentLoaded(&$rawContent) public function onContentLoaded(&$rawContent)
@ -163,8 +189,9 @@ class DummyPlugin extends AbstractPicoPlugin
/** /**
* Triggered before Pico parses the meta header * Triggered before Pico parses the meta header
* *
* @see Pico::parseFileMeta() * @see Pico::parseFileMeta()
* @see DummyPlugin::onMetaParsed() * @see DummyPlugin::onMetaParsed()
*
* @return void * @return void
*/ */
public function onMetaParsing() public function onMetaParsing()
@ -175,8 +202,10 @@ class DummyPlugin extends AbstractPicoPlugin
/** /**
* Triggered after Pico has parsed the meta header * Triggered after Pico has parsed the meta header
* *
* @see Pico::getFileMeta() * @see Pico::getFileMeta()
* @param string[] &$meta parsed meta data *
* @param string[] &$meta parsed meta data
*
* @return void * @return void
*/ */
public function onMetaParsed(array &$meta) public function onMetaParsed(array &$meta)
@ -187,9 +216,10 @@ class DummyPlugin extends AbstractPicoPlugin
/** /**
* Triggered before Pico parses the pages content * Triggered before Pico parses the pages content
* *
* @see Pico::prepareFileContent() * @see Pico::prepareFileContent()
* @see DummyPlugin::prepareFileContent() * @see DummyPlugin::prepareFileContent()
* @see DummyPlugin::onContentParsed() * @see DummyPlugin::onContentParsed()
*
* @return void * @return void
*/ */
public function onContentParsing() public function onContentParsing()
@ -200,9 +230,11 @@ class DummyPlugin extends AbstractPicoPlugin
/** /**
* Triggered after Pico has prepared the raw file contents for parsing * Triggered after Pico has prepared the raw file contents for parsing
* *
* @see Pico::parseFileContent() * @see Pico::parseFileContent()
* @see DummyPlugin::onContentParsed() * @see DummyPlugin::onContentParsed()
* @param string &$markdown Markdown contents of the requested page *
* @param string &$markdown Markdown contents of the requested page
*
* @return void * @return void
*/ */
public function onContentPrepared(&$markdown) public function onContentPrepared(&$markdown)
@ -213,8 +245,10 @@ class DummyPlugin extends AbstractPicoPlugin
/** /**
* Triggered after Pico has parsed the contents of the file to serve * Triggered after Pico has parsed the contents of the file to serve
* *
* @see Pico::getFileContent() * @see Pico::getFileContent()
* @param string &$content parsed contents (HTML) of the requested page *
* @param string &$content parsed contents (HTML) of the requested page
*
* @return void * @return void
*/ */
public function onContentParsed(&$content) public function onContentParsed(&$content)
@ -225,12 +259,13 @@ class DummyPlugin extends AbstractPicoPlugin
/** /**
* Triggered before Pico reads all known pages * Triggered before Pico reads all known pages
* *
* @see Pico::readPages() * @see Pico::readPages()
* @see DummyPlugin::onSinglePageLoading() * @see DummyPlugin::onSinglePageLoading()
* @see DummyPlugin::onSinglePageContent() * @see DummyPlugin::onSinglePageContent()
* @see DummyPlugin::onSinglePageLoaded() * @see DummyPlugin::onSinglePageLoaded()
* @see DummyPlugin::onPagesDiscovered() * @see DummyPlugin::onPagesDiscovered()
* @see DummyPlugin::onPagesLoaded() * @see DummyPlugin::onPagesLoaded()
*
* @return void * @return void
*/ */
public function onPagesLoading() public function onPagesLoading()
@ -247,13 +282,15 @@ class DummyPlugin extends AbstractPicoPlugin
* then it passes TRUE. Don't change this value incautiously if it isn't * then it passes TRUE. Don't change this value incautiously if it isn't
* NULL! Someone likely set it to TRUE or FALSE on purpose... * NULL! Someone likely set it to TRUE or FALSE on purpose...
* *
* @see DummyPlugin::onSinglePageContent() * @see DummyPlugin::onSinglePageContent()
* @see DummyPlugin::onSinglePageLoaded() * @see DummyPlugin::onSinglePageLoaded()
* @see DummyPlugin::onPagesDiscovered() * @see DummyPlugin::onPagesDiscovered()
* @see DummyPlugin::onPagesLoaded() * @see DummyPlugin::onPagesLoaded()
* @param string $id relative path to the content file *
* @param bool|null $skipPage set this to TRUE to remove this page from * @param string $id relative path to the content file
* the pages array, otherwise leave it unchanged * @param bool|null $skipPage set this to TRUE to remove this page from the
* pages array, otherwise leave it unchanged
*
* @return void * @return void
*/ */
public function onSinglePageLoading($id, &$skipPage) public function onSinglePageLoading($id, &$skipPage)
@ -268,11 +305,13 @@ class DummyPlugin extends AbstractPicoPlugin
* page is the requested page. The reason for this exception is that the * page is the requested page. The reason for this exception is that the
* raw contents of this page were loaded already. * raw contents of this page were loaded already.
* *
* @see DummyPlugin::onSinglePageLoaded() * @see DummyPlugin::onSinglePageLoaded()
* @see DummyPlugin::onPagesDiscovered() * @see DummyPlugin::onPagesDiscovered()
* @see DummyPlugin::onPagesLoaded() * @see DummyPlugin::onPagesLoaded()
* @param string $id relative path to the content file *
* @param string &$rawContent raw file contents * @param string $id relative path to the content file
* @param string &$rawContent raw file contents
*
* @return void * @return void
*/ */
public function onSinglePageContent($id, &$rawContent) public function onSinglePageContent($id, &$rawContent)
@ -285,30 +324,32 @@ class DummyPlugin extends AbstractPicoPlugin
* *
* The `$pageData` parameter consists of the following values: * The `$pageData` parameter consists of the following values:
* *
* | Array key | Type | Description | * | Array key | Type | Description |
* | -------------- | ------- | ------------------------------------------ | * | -------------- | ------ | ------------------------------------------ |
* | id | string | relative path to the content file | * | id | string | relative path to the content file |
* | url | string | URL to the page | * | url | string | URL to the page |
* | title | string | title of the page (YAML header) | * | title | string | title of the page (YAML header) |
* | description | string | description of the page (YAML header) | * | description | string | description of the page (YAML header) |
* | author | string | author of the page (YAML header) | * | author | string | author of the page (YAML header) |
* | time | string | timestamp derived from the Date header | * | time | string | timestamp derived from the Date header |
* | date | string | date of the page (YAML header) | * | date | string | date of the page (YAML header) |
* | date_formatted | string | formatted date of the page | * | date_formatted | string | formatted date of the page |
* | hidden | boolean | this page shouldn't be visible to the user | * | hidden | bool | this page shouldn't be visible to the user |
* | raw_content | string | raw, not yet parsed contents of the page | * | raw_content | string | raw, not yet parsed contents of the page |
* | meta | string | parsed meta data of the page | * | meta | string | parsed meta data of the page |
* | previous_page | &array | reference to the previous page | * | previous_page | &array | reference to the previous page |
* | next_page | &array | reference to the next page | * | next_page | &array | reference to the next page |
* *
* Please note that the `previous_page` and `next_page` keys won't be * Please note that the `previous_page` and `next_page` keys won't be
* available until the `onCurrentPageDiscovered` event was triggered. * available until the `onCurrentPageDiscovered` event was triggered.
* *
* Set `$pageData` to `null` to remove this page from the pages array. * 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
* *
* @see DummyPlugin::onPagesDiscovered()
* @see DummyPlugin::onPagesLoaded()
* @param array &$pageData data of the loaded page
* @return void * @return void
*/ */
public function onSinglePageLoaded(array &$pageData) public function onSinglePageLoaded(array &$pageData)
@ -323,9 +364,11 @@ class DummyPlugin extends AbstractPicoPlugin
* structure of the page data. Please note that the pages array isn't * structure of the page data. Please note that the pages array isn't
* sorted yet. * sorted yet.
* *
* @see Pico::sortPages() * @see Pico::sortPages()
* @see DummyPlugin::onPagesLoaded() * @see DummyPlugin::onPagesLoaded()
* @param array[] &$pages data of all known pages *
* @param array[] &$pages data of all known pages
*
* @return void * @return void
*/ */
public function onPagesDiscovered(array &$pages) public function onPagesDiscovered(array &$pages)
@ -339,8 +382,10 @@ class DummyPlugin extends AbstractPicoPlugin
* See {@see DummyPlugin::onSinglePageLoaded()} for details about the * See {@see DummyPlugin::onSinglePageLoaded()} for details about the
* structure of the page data. * structure of the page data.
* *
* @see Pico::getPages() * @see Pico::getPages()
* @param array[] &$pages data of all known pages *
* @param array[] &$pages data of all known pages
*
* @return void * @return void
*/ */
public function onPagesLoaded(array &$pages) public function onPagesLoaded(array &$pages)
@ -354,14 +399,16 @@ class DummyPlugin extends AbstractPicoPlugin
* See {@see DummyPlugin::onSinglePageLoaded()} for details about the * See {@see DummyPlugin::onSinglePageLoaded()} for details about the
* structure of the page data. * structure of the page data.
* *
* @see Pico::discoverPageSiblings() * @see Pico::discoverPageSiblings()
* @see Pico::discoverCurrentPage() * @see Pico::discoverCurrentPage()
* @see Pico::getCurrentPage() * @see Pico::getCurrentPage()
* @see Pico::getPreviousPage() * @see Pico::getPreviousPage()
* @see Pico::getNextPage() * @see Pico::getNextPage()
* @param array|null &$currentPage data of the page being served *
* @param array|null &$previousPage data of the previous page * @param array|null &$currentPage data of the page being served
* @param array|null &$nextPage data of the next page * @param array|null &$previousPage data of the previous page
* @param array|null &$nextPage data of the next page
*
* @return void * @return void
*/ */
public function onCurrentPageDiscovered( public function onCurrentPageDiscovered(
@ -375,11 +422,13 @@ class DummyPlugin extends AbstractPicoPlugin
/** /**
* Triggered before Pico renders the page * Triggered before Pico renders the page
* *
* @see Pico::getTwigTemplate() * @see Pico::getTwigTemplate()
* @see Pico::getTwigVariables() * @see Pico::getTwigVariables()
* @see DummyPlugin::onPageRendered() * @see DummyPlugin::onPageRendered()
* @param string &$templateName file name of the template *
* @param array &$twigVariables template variables * @param string &$templateName file name of the template
* @param array &$twigVariables template variables
*
* @return void * @return void
*/ */
public function onPageRendering(&$templateName, array &$twigVariables) public function onPageRendering(&$templateName, array &$twigVariables)
@ -390,7 +439,8 @@ class DummyPlugin extends AbstractPicoPlugin
/** /**
* Triggered after Pico has rendered the page * Triggered after Pico has rendered the page
* *
* @param string &$output contents which will be sent to the user * @param string &$output contents which will be sent to the user
*
* @return void * @return void
*/ */
public function onPageRendered(&$output) public function onPageRendered(&$output)
@ -401,10 +451,12 @@ class DummyPlugin extends AbstractPicoPlugin
/** /**
* Triggered when Pico reads its known meta header fields * Triggered when Pico reads its known meta header fields
* *
* @see Pico::getMetaHeaders() * @see Pico::getMetaHeaders()
* @param string[] &$headers list of known meta header *
* fields; the array key specifies the YAML key to search for, the * @param string[] &$headers list of known meta header fields; the array
* array value is later used to access the found value * key specifies the YAML key to search for, the array value is later
* used to access the found value
*
* @return void * @return void
*/ */
public function onMetaHeaders(array &$headers) public function onMetaHeaders(array &$headers)
@ -415,8 +467,10 @@ class DummyPlugin extends AbstractPicoPlugin
/** /**
* Triggered when Pico registers the YAML parser * Triggered when Pico registers the YAML parser
* *
* @see Pico::getYamlParser() * @see Pico::getYamlParser()
* @param \Symfony\Component\Yaml\Parser &$yamlParser YAML parser instance *
* @param \Symfony\Component\Yaml\Parser &$yamlParser YAML parser instance
*
* @return void * @return void
*/ */
public function onYamlParserRegistered(\Symfony\Component\Yaml\Parser &$yamlParser) public function onYamlParserRegistered(\Symfony\Component\Yaml\Parser &$yamlParser)
@ -427,8 +481,10 @@ class DummyPlugin extends AbstractPicoPlugin
/** /**
* Triggered when Pico registers the Parsedown parser * Triggered when Pico registers the Parsedown parser
* *
* @see Pico::getParsedown() * @see Pico::getParsedown()
* @param Parsedown &$parsedown Parsedown instance *
* @param Parsedown &$parsedown Parsedown instance
*
* @return void * @return void
*/ */
public function onParsedownRegistered(Parsedown &$parsedown) public function onParsedownRegistered(Parsedown &$parsedown)
@ -439,8 +495,10 @@ class DummyPlugin extends AbstractPicoPlugin
/** /**
* Triggered when Pico registers the twig template engine * Triggered when Pico registers the twig template engine
* *
* @see Pico::getTwig() * @see Pico::getTwig()
* @param Twig_Environment &$twig Twig instance *
* @param Twig_Environment &$twig Twig instance
*
* @return void * @return void
*/ */
public function onTwigRegistered(Twig_Environment &$twig) public function onTwigRegistered(Twig_Environment &$twig)