SeaCMS
/
pico
6
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Add license/copyright file header; improve phpDoc class docs

Browse Source
pico-3.0-alpha
Daniel Rudolf 8 years ago
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 all changes Ignore whitespace when comparing lines Ignore changes in amount of whitespace Ignore changes in whitespace at EOL
Show Stats Download Patch File Download Diff File
  1. 7
      composer.json
  2. 65
      lib/AbstractPicoPlugin.php
  3. 398
      lib/Pico.php
  4. 51
      lib/PicoPluginInterface.php
  5. 61
      lib/PicoTwigExtension.php
  6. 258
      plugins/DummyPlugin.php

7
composer.json
Unescape 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
Unescape 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
Unescape 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
Unescape 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 bool plugin is enabled (TRUE) or disabled (FALSE)
* @return boolean 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
Unescape 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
Unescape 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)

Write Preview
Loading…
Cancel
Save