Add license/copyright file header; improve phpDoc class docs
This commit is contained in:
Daniel Rudolf
parent
d8a649e6f7
commit
61319b011e
6 changed files with 518 additions and 322 deletions
|
|
@ -13,8 +13,11 @@
|
|||
},
|
||||
{
|
||||
"name": "The Pico Community",
|
||||
"homepage": "https://github.com/picocms/Pico/graphs/contributors",
|
||||
"role": "Contributors"
|
||||
"homepage": "http://picocms.org/"
|
||||
},
|
||||
{
|
||||
"name": "Contributors",
|
||||
"homepage": "https://github.com/picocms/Pico/graphs/contributors"
|
||||
}
|
||||
],
|
||||
"support": {
|
||||
|
|
|
|||
|
|
@ -1,4 +1,14 @@
|
|||
<?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
|
||||
|
|
@ -24,11 +34,11 @@ abstract class AbstractPicoPlugin implements PicoPluginInterface
|
|||
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::setEnabled()
|
||||
* @var boolean
|
||||
* @var bool
|
||||
*/
|
||||
protected $enabled = true;
|
||||
|
||||
|
|
@ -36,7 +46,7 @@ abstract class AbstractPicoPlugin implements PicoPluginInterface
|
|||
* Boolean indicating if this plugin was ever enabled/disabled manually
|
||||
*
|
||||
* @see PicoPluginInterface::isStatusChanged()
|
||||
* @var boolean
|
||||
* @var bool
|
||||
*/
|
||||
protected $statusChanged = false;
|
||||
|
||||
|
|
@ -44,7 +54,7 @@ abstract class AbstractPicoPlugin implements PicoPluginInterface
|
|||
* Boolean indicating whether this plugin matches Pico's API version
|
||||
*
|
||||
* @see AbstractPicoPlugin::checkCompatibility()
|
||||
* @var boolean|null
|
||||
* @var bool|null
|
||||
*/
|
||||
protected $nativePlugin;
|
||||
|
||||
|
|
@ -152,14 +162,14 @@ abstract class AbstractPicoPlugin implements PicoPluginInterface
|
|||
* Returns either the value of the specified plugin config variable or
|
||||
* the config array
|
||||
*
|
||||
* @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
|
||||
* @return mixed if no name of a config variable has been
|
||||
* supplied, the plugin's config array is returned; otherwise it
|
||||
* returns either the value of the named config variable, or, if the
|
||||
* named config variable doesn't exist, the provided default value
|
||||
* or NULL
|
||||
*
|
||||
* @return mixed if no name of a config variable has been supplied, the
|
||||
* plugin's config array is returned; otherwise it returns either the
|
||||
* value of the named config variable, or, if the named config variable
|
||||
* doesn't exist, the provided default value or 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
|
||||
*
|
||||
* @see Pico
|
||||
* @param string $methodName name of the method to call
|
||||
* @param array $params parameters to pass
|
||||
* @return mixed return value of the called method
|
||||
* @see Pico
|
||||
*
|
||||
* @param string $methodName name of the method to call
|
||||
* @param array $params parameters to pass
|
||||
*
|
||||
* @return mixed return value of the called method
|
||||
*/
|
||||
public function __call($methodName, array $params)
|
||||
{
|
||||
|
|
@ -195,10 +207,13 @@ abstract class AbstractPicoPlugin implements PicoPluginInterface
|
|||
/**
|
||||
* Enables all plugins which this plugin depends on
|
||||
*
|
||||
* @see PicoPluginInterface::getDependencies()
|
||||
* @param boolean $recursive enable required plugins automatically
|
||||
* @see PicoPluginInterface::getDependencies()
|
||||
*
|
||||
* @param bool $recursive enable required plugins automatically
|
||||
*
|
||||
* @return void
|
||||
* @throws RuntimeException thrown when a dependency fails
|
||||
*
|
||||
* @throws RuntimeException thrown when a dependency fails
|
||||
*/
|
||||
protected function checkDependencies($recursive)
|
||||
{
|
||||
|
|
@ -244,10 +259,13 @@ abstract class AbstractPicoPlugin implements PicoPluginInterface
|
|||
/**
|
||||
* Disables all plugins which depend on this plugin
|
||||
*
|
||||
* @see PicoPluginInterface::getDependants()
|
||||
* @param boolean $recursive disabled dependant plugins automatically
|
||||
* @see PicoPluginInterface::getDependants()
|
||||
*
|
||||
* @param bool $recursive disabled dependant plugins automatically
|
||||
*
|
||||
* @return void
|
||||
* @throws RuntimeException thrown when a dependency fails
|
||||
*
|
||||
* @throws RuntimeException thrown when a dependency fails
|
||||
*/
|
||||
protected function checkDependants($recursive)
|
||||
{
|
||||
|
|
@ -308,8 +326,9 @@ abstract class AbstractPicoPlugin implements PicoPluginInterface
|
|||
* newer API versions, what defaults to "no" by default.
|
||||
*
|
||||
* @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()
|
||||
{
|
||||
|
|
|
|||
398
lib/Pico.php
398
lib/Pico.php
|
|
@ -1,4 +1,20 @@
|
|||
<?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
|
||||
|
|
@ -116,7 +132,7 @@ class Pico
|
|||
/**
|
||||
* Boolean indicating whether Pico started processing yet
|
||||
*
|
||||
* @var boolean
|
||||
* @var bool
|
||||
*/
|
||||
protected $locked = false;
|
||||
|
||||
|
|
@ -180,7 +196,7 @@ class Pico
|
|||
* Boolean indicating whether Pico is serving a 404 page
|
||||
*
|
||||
* @see Pico::is404Content()
|
||||
* @var boolean
|
||||
* @var bool
|
||||
*/
|
||||
protected $is404Content = false;
|
||||
|
||||
|
|
@ -359,8 +375,9 @@ class Pico
|
|||
* meta headers, processes Markdown, does Twig processing and returns
|
||||
* the rendered contents.
|
||||
*
|
||||
* @return string rendered Pico contents
|
||||
* @throws Exception thrown when a not recoverable error occurs
|
||||
* @return string rendered Pico contents
|
||||
*
|
||||
* @throws Exception thrown when a irrecoverable error occurs
|
||||
*/
|
||||
public function run()
|
||||
{
|
||||
|
|
@ -470,10 +487,12 @@ class Pico
|
|||
* incorporate plugin dependencies. See {@see Pico::sortPlugins()} for
|
||||
* details.
|
||||
*
|
||||
* @see Pico::loadPlugin()
|
||||
* @see Pico::getPlugin()
|
||||
* @see Pico::getPlugins()
|
||||
* @see Pico::loadPlugin()
|
||||
* @see Pico::getPlugin()
|
||||
* @see Pico::getPlugins()
|
||||
*
|
||||
* @return void
|
||||
*
|
||||
* @throws RuntimeException thrown when a plugin couldn't be loaded
|
||||
*/
|
||||
protected function loadPlugins()
|
||||
|
|
@ -492,10 +511,12 @@ class Pico
|
|||
* `picocms/pico-installer` installer by reading the `pico-plugin.php` in
|
||||
* composer's `vendor` dir.
|
||||
*
|
||||
* @see Pico::loadPlugins()
|
||||
* @see Pico::loadLocalPlugins()
|
||||
* @param string[] $pluginBlacklist class names of plugins not to load
|
||||
* @return string[] installer names of the loaded plugins
|
||||
* @see Pico::loadPlugins()
|
||||
* @see Pico::loadLocalPlugins()
|
||||
*
|
||||
* @param string[] $pluginBlacklist class names of plugins not to load
|
||||
*
|
||||
* @return string[] installer names of the loaded plugins
|
||||
*/
|
||||
protected function loadComposerPlugins(array $pluginBlacklist = array())
|
||||
{
|
||||
|
|
@ -558,10 +579,13 @@ class Pico
|
|||
* - 60 to 79: Plugins hooking into template or markdown parsing
|
||||
* - 80 to 99: Plugins using the `onPageRendered` event
|
||||
*
|
||||
* @see Pico::loadPlugins()
|
||||
* @see Pico::loadComposerPlugins()
|
||||
* @param string[] $pluginBlacklist class names of plugins not to load
|
||||
* @see Pico::loadPlugins()
|
||||
* @see Pico::loadComposerPlugins()
|
||||
*
|
||||
* @param string[] $pluginBlacklist class names of plugins not to load
|
||||
*
|
||||
* @return void
|
||||
*
|
||||
* @throws RuntimeException thrown when a plugin couldn't be loaded
|
||||
*/
|
||||
protected function loadLocalPlugins(array $pluginBlacklist = array())
|
||||
|
|
@ -646,14 +670,16 @@ class Pico
|
|||
*
|
||||
* This method triggers the `onPluginManuallyLoaded` event.
|
||||
*
|
||||
* @see Pico::loadPlugins()
|
||||
* @see Pico::getPlugin()
|
||||
* @see Pico::getPlugins()
|
||||
* @param PicoPluginInterface|string $plugin either the class name of a
|
||||
* @see Pico::loadPlugins()
|
||||
* @see Pico::getPlugin()
|
||||
* @see Pico::getPlugins()
|
||||
*
|
||||
* @param PicoPluginInterface|string $plugin either the class name of a
|
||||
* plugin to instantiate or a plugin instance
|
||||
* @return PicoPluginInterface instance of the loaded plugin
|
||||
* @throws RuntimeException thrown when a plugin couldn't
|
||||
* be loaded
|
||||
*
|
||||
* @return PicoPluginInterface instance of the loaded plugin
|
||||
*
|
||||
* @throws RuntimeException thrown when a plugin couldn't be loaded
|
||||
*/
|
||||
public function loadPlugin($plugin)
|
||||
{
|
||||
|
|
@ -708,12 +734,13 @@ class Pico
|
|||
* version 1.1.0, licensed under the MIT license. It uses the `ArraySort`
|
||||
* implementation (class `\MJS\TopSort\Implementations\ArraySort`).
|
||||
*
|
||||
* @see Pico::loadPlugins()
|
||||
* @see Pico::getPlugins()
|
||||
* @see https://github.com/marcj/topsort.php
|
||||
* @see Pico::loadPlugins()
|
||||
* @see Pico::getPlugins()
|
||||
* @see https://github.com/marcj/topsort.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
|
||||
*
|
||||
* @return void
|
||||
*/
|
||||
protected function sortPlugins()
|
||||
|
|
@ -773,11 +800,14 @@ class Pico
|
|||
* Plugins SHOULD implement {@see PicoPluginInterface}, but you MUST NOT
|
||||
* rely on it. For more information see {@see PicoPluginInterface}.
|
||||
*
|
||||
* @see Pico::loadPlugins()
|
||||
* @see Pico::getPlugins()
|
||||
* @param string $pluginName name of the plugin
|
||||
* @return object instance of the plugin
|
||||
* @throws RuntimeException thrown when the plugin wasn't found
|
||||
* @see Pico::loadPlugins()
|
||||
* @see Pico::getPlugins()
|
||||
*
|
||||
* @param string $pluginName name of the plugin
|
||||
*
|
||||
* @return object instance of the plugin
|
||||
*
|
||||
* @throws RuntimeException thrown when the plugin wasn't found
|
||||
*/
|
||||
public function getPlugin($pluginName)
|
||||
{
|
||||
|
|
@ -791,8 +821,9 @@ class Pico
|
|||
/**
|
||||
* Returns all loaded plugins
|
||||
*
|
||||
* @see Pico::loadPlugins()
|
||||
* @see Pico::getPlugin()
|
||||
* @see Pico::loadPlugins()
|
||||
* @see Pico::getPlugin()
|
||||
*
|
||||
* @return object[]|null
|
||||
*/
|
||||
public function getPlugins()
|
||||
|
|
@ -811,8 +842,9 @@ class Pico
|
|||
* `test: { baz: 42 }` in `config/b.yml`, `{{ config.test.baz }}` will be
|
||||
* undefined!
|
||||
*
|
||||
* @see Pico::setConfig()
|
||||
* @see Pico::getConfig()
|
||||
* @see Pico::setConfig()
|
||||
* @see Pico::getConfig()
|
||||
*
|
||||
* @return void
|
||||
*/
|
||||
protected function loadConfig()
|
||||
|
|
@ -921,10 +953,13 @@ class Pico
|
|||
* {@see Pico::run()} only. Options set with this method cannot be
|
||||
* overwritten by {@path "config/config.yml"}.
|
||||
*
|
||||
* @see Pico::loadConfig()
|
||||
* @see Pico::getConfig()
|
||||
* @param array $config array with config variables
|
||||
* @see Pico::loadConfig()
|
||||
* @see Pico::getConfig()
|
||||
*
|
||||
* @param array $config array with config variables
|
||||
*
|
||||
* @return void
|
||||
*
|
||||
* @throws LogicException thrown if Pico already started processing
|
||||
*/
|
||||
public function setConfig(array $config)
|
||||
|
|
@ -940,15 +975,17 @@ class Pico
|
|||
* Returns either the value of the specified config variable or
|
||||
* the config array
|
||||
*
|
||||
* @see Pico::setConfig()
|
||||
* @see Pico::loadConfig()
|
||||
* @param string $configName optional name of a config variable
|
||||
* @param mixed $default optional default value to return when the
|
||||
* @see Pico::setConfig()
|
||||
* @see Pico::loadConfig()
|
||||
*
|
||||
* @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
|
||||
* @return mixed if no name of a config variable has been
|
||||
* supplied, the config array is returned; otherwise it returns either
|
||||
* the value of the named config variable, or, if the named config
|
||||
* variable doesn't exist, the provided default value or NULL
|
||||
*
|
||||
* @return mixed if no name of a config variable has been supplied, the
|
||||
* config array is returned; otherwise it returns either the value of
|
||||
* 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)
|
||||
{
|
||||
|
|
@ -994,7 +1031,8 @@ class Pico
|
|||
* Pico interprets `someBooleanParam` as name of the requested page. Use
|
||||
* `/pico/?someBooleanParam=` or `/pico/?index&someBooleanParam` instead.
|
||||
*
|
||||
* @see Pico::getRequestUrl()
|
||||
* @see Pico::getRequestUrl()
|
||||
*
|
||||
* @return void
|
||||
*/
|
||||
protected function evaluateRequestUrl()
|
||||
|
|
@ -1030,7 +1068,8 @@ class Pico
|
|||
/**
|
||||
* Returns the URL where a user requested the page
|
||||
*
|
||||
* @see Pico::evaluateRequestUrl()
|
||||
* @see Pico::evaluateRequestUrl()
|
||||
*
|
||||
* @return string|null request URL
|
||||
*/
|
||||
public function getRequestUrl()
|
||||
|
|
@ -1048,9 +1087,11 @@ class Pico
|
|||
* RECOMMENDED to use PHP's `open_basedir` feature - always, not just
|
||||
* with Pico!
|
||||
*
|
||||
* @see Pico::getRequestFile()
|
||||
* @param string $requestUrl path name (likely from a URL) to resolve
|
||||
* @return string path to the resolved content file
|
||||
* @see Pico::getRequestFile()
|
||||
*
|
||||
* @param string $requestUrl path name (likely from a URL) to resolve
|
||||
*
|
||||
* @return string path to the resolved content file
|
||||
*/
|
||||
public function resolveFilePath($requestUrl)
|
||||
{
|
||||
|
|
@ -1099,8 +1140,9 @@ class Pico
|
|||
/**
|
||||
* Returns the absolute path to the content file to serve
|
||||
*
|
||||
* @see Pico::resolveFilePath()
|
||||
* @return string|null file path
|
||||
* @see Pico::resolveFilePath()
|
||||
*
|
||||
* @return string|null file pat
|
||||
*/
|
||||
public function getRequestFile()
|
||||
{
|
||||
|
|
@ -1110,9 +1152,11 @@ class Pico
|
|||
/**
|
||||
* Returns the raw contents of a file
|
||||
*
|
||||
* @see Pico::getRawContent()
|
||||
* @param string $file file path
|
||||
* @return string raw contents of the file
|
||||
* @see Pico::getRawContent()
|
||||
*
|
||||
* @param string $file file path
|
||||
*
|
||||
* @return string raw contents of the 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.
|
||||
*
|
||||
* @see Pico::getRawContent()
|
||||
* @param string $file path to requested (but not existing) file
|
||||
* @return string raw contents of the 404 file
|
||||
* @see Pico::getRawContent()
|
||||
*
|
||||
* @param string $file path to requested (but not existing) file
|
||||
*
|
||||
* @return string raw contents of the 404 file
|
||||
*/
|
||||
public function load404Content($file)
|
||||
{
|
||||
|
|
@ -1165,8 +1211,9 @@ class Pico
|
|||
/**
|
||||
* Returns the raw contents, either of the requested or the 404 file
|
||||
*
|
||||
* @see Pico::loadFileContent()
|
||||
* @see Pico::load404Content()
|
||||
* @see Pico::loadFileContent()
|
||||
* @see Pico::load404Content()
|
||||
*
|
||||
* @return string|null raw contents
|
||||
*/
|
||||
public function getRawContent()
|
||||
|
|
@ -1177,8 +1224,9 @@ class Pico
|
|||
/**
|
||||
* Returns TRUE when Pico is serving a 404 page
|
||||
*
|
||||
* @see Pico::load404Content()
|
||||
* @return boolean TRUE if Pico is serving a 404 page, FALSE otherwise
|
||||
* @see Pico::load404Content()
|
||||
*
|
||||
* @return bool TRUE if Pico is serving a 404 page, FALSE otherwise
|
||||
*/
|
||||
public function is404Content()
|
||||
{
|
||||
|
|
@ -1191,8 +1239,8 @@ class Pico
|
|||
* This method triggers the `onMetaHeaders` event when the known meta
|
||||
* headers weren't assembled yet.
|
||||
*
|
||||
* @return string[] known meta headers; the array value specifies the
|
||||
* YAML key to search for, the array key is later used to access the
|
||||
* @return string[] known meta headers; the array key specifies the YAML
|
||||
* key to search for, the array value is later used to access the
|
||||
* found value
|
||||
*/
|
||||
public function getMetaHeaders()
|
||||
|
|
@ -1241,10 +1289,13 @@ class Pico
|
|||
* `onMetaHeaders` event first. The implicit availability of headers is
|
||||
* for users and pure (!) theme developers ONLY.
|
||||
*
|
||||
* @see Pico::getFileMeta()
|
||||
* @param string $rawContent the raw file contents
|
||||
* @param string[] $headers known meta headers
|
||||
* @return array parsed meta data
|
||||
* @see Pico::getFileMeta()
|
||||
*
|
||||
* @param string $rawContent the raw file contents
|
||||
* @param string[] $headers known meta headers
|
||||
*
|
||||
* @return array parsed meta data
|
||||
*
|
||||
* @throws \Symfony\Component\Yaml\Exception\ParseException thrown when the
|
||||
* meta data is invalid
|
||||
*/
|
||||
|
|
@ -1305,7 +1356,8 @@ class Pico
|
|||
/**
|
||||
* Returns the parsed meta data of the requested page
|
||||
*
|
||||
* @see Pico::parseFileMeta()
|
||||
* @see Pico::parseFileMeta()
|
||||
*
|
||||
* @return array|null parsed meta data
|
||||
*/
|
||||
public function getFileMeta()
|
||||
|
|
@ -1343,12 +1395,14 @@ class Pico
|
|||
*
|
||||
* This method calls the {@see Pico::substituteFileContent()} method.
|
||||
*
|
||||
* @see Pico::substituteFileContent()
|
||||
* @see Pico::parseFileContent()
|
||||
* @see Pico::getFileContent()
|
||||
* @param string $rawContent raw contents of a page
|
||||
* @param array $meta meta data to use for %meta.*% replacement
|
||||
* @return string prepared Markdown contents
|
||||
* @see Pico::substituteFileContent()
|
||||
* @see Pico::parseFileContent()
|
||||
* @see Pico::getFileContent()
|
||||
*
|
||||
* @param string $rawContent raw contents of a page
|
||||
* @param array $meta meta data to use for %meta.*% replacement
|
||||
*
|
||||
* @return string prepared Markdown contents
|
||||
*/
|
||||
public function prepareFileContent($rawContent, array $meta)
|
||||
{
|
||||
|
|
@ -1366,9 +1420,10 @@ class Pico
|
|||
/**
|
||||
* Replaces all %...% placeholders in a page's contents
|
||||
*
|
||||
* @param string $markdown Markdown contents of a page
|
||||
* @param array $meta meta data to use for %meta.*% replacement
|
||||
* @return string substituted Markdown contents
|
||||
* @param string $markdown Markdown contents of a page
|
||||
* @param array $meta meta data to use for %meta.*% replacement
|
||||
*
|
||||
* @return string substituted Markdown contents
|
||||
*/
|
||||
public function substituteFileContent($markdown, array $meta = array())
|
||||
{
|
||||
|
|
@ -1409,11 +1464,13 @@ class Pico
|
|||
/**
|
||||
* Parses the contents of a page using ParsedownExtra
|
||||
*
|
||||
* @see Pico::prepareFileContent()
|
||||
* @see Pico::substituteFileContent()
|
||||
* @see Pico::getFileContent()
|
||||
* @param string $markdown Markdown contents of a page
|
||||
* @return string parsed contents (HTML)
|
||||
* @see Pico::prepareFileContent()
|
||||
* @see Pico::substituteFileContent()
|
||||
* @see Pico::getFileContent()
|
||||
*
|
||||
* @param string $markdown Markdown contents of a page
|
||||
*
|
||||
* @return string parsed contents (HTML)
|
||||
*/
|
||||
public function parseFileContent($markdown)
|
||||
{
|
||||
|
|
@ -1423,9 +1480,10 @@ class Pico
|
|||
/**
|
||||
* Returns the cached contents of the requested page
|
||||
*
|
||||
* @see Pico::prepareFileContent()
|
||||
* @see Pico::substituteFileContent()
|
||||
* @see Pico::parseFileContent()
|
||||
* @see Pico::prepareFileContent()
|
||||
* @see Pico::substituteFileContent()
|
||||
* @see Pico::parseFileContent()
|
||||
*
|
||||
* @return string|null parsed contents
|
||||
*/
|
||||
public function getFileContent()
|
||||
|
|
@ -1448,19 +1506,20 @@ class Pico
|
|||
* | time | string | timestamp derived from the Date header |
|
||||
* | date | string | date of the page (YAML header) |
|
||||
* | date_formatted | string | formatted date of the page |
|
||||
* | hidden | boolean | this page shouldn't be visible to the user |
|
||||
* | hidden | bool | this page shouldn't be visible to the user |
|
||||
* | raw_content | string | raw, not yet parsed contents of the page |
|
||||
* | meta | string | parsed meta data of the page |
|
||||
* | previous_page | &array | reference to the previous page |
|
||||
* | next_page | &array | reference to the next page |
|
||||
*
|
||||
* Please note that the `previous_page` and `next_page` keys won't be
|
||||
* available until the `onCurrentPageDiscovered` event
|
||||
* ({@see Pico::discoverPageSiblings()}) was triggered.
|
||||
* available until the `onCurrentPageDiscovered` event 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
|
||||
*/
|
||||
protected function readPages()
|
||||
|
|
@ -1545,8 +1604,9 @@ class Pico
|
|||
/**
|
||||
* Sorts all pages known to Pico
|
||||
*
|
||||
* @see Pico::readPages()
|
||||
* @see Pico::getPages()
|
||||
* @see Pico::readPages()
|
||||
* @see Pico::getPages()
|
||||
*
|
||||
* @return void
|
||||
*/
|
||||
protected function sortPages()
|
||||
|
|
@ -1625,8 +1685,9 @@ class Pico
|
|||
* Walks through the list of all known pages and discovers the previous and
|
||||
* next page respectively
|
||||
*
|
||||
* @see Pico::readPages()
|
||||
* @see Pico::getPages()
|
||||
* @see Pico::readPages()
|
||||
* @see Pico::getPages()
|
||||
*
|
||||
* @return void
|
||||
*/
|
||||
protected function discoverPageSiblings()
|
||||
|
|
@ -1661,7 +1722,8 @@ class Pico
|
|||
/**
|
||||
* Returns the list of known pages
|
||||
*
|
||||
* @see Pico::readPages()
|
||||
* @see Pico::readPages()
|
||||
*
|
||||
* @return array[]|null the data of all pages
|
||||
*/
|
||||
public function getPages()
|
||||
|
|
@ -1673,9 +1735,10 @@ class Pico
|
|||
* Discovers the page data of the requested page as well as the previous
|
||||
* and next page relative to it
|
||||
*
|
||||
* @see Pico::getCurrentPage()
|
||||
* @see Pico::getPreviousPage()
|
||||
* @see Pico::getNextPage()
|
||||
* @see Pico::getCurrentPage()
|
||||
* @see Pico::getPreviousPage()
|
||||
* @see Pico::getNextPage()
|
||||
*
|
||||
* @return void
|
||||
*/
|
||||
protected function discoverCurrentPage()
|
||||
|
|
@ -1691,7 +1754,8 @@ class Pico
|
|||
/**
|
||||
* Returns the data of the requested page
|
||||
*
|
||||
* @see Pico::discoverCurrentPage()
|
||||
* @see Pico::discoverCurrentPage()
|
||||
*
|
||||
* @return array|null page data
|
||||
*/
|
||||
public function getCurrentPage()
|
||||
|
|
@ -1702,7 +1766,8 @@ class Pico
|
|||
/**
|
||||
* Returns the data of the previous page relative to the page being served
|
||||
*
|
||||
* @see Pico::discoverCurrentPage()
|
||||
* @see Pico::discoverCurrentPage()
|
||||
*
|
||||
* @return array|null page data
|
||||
*/
|
||||
public function getPreviousPage()
|
||||
|
|
@ -1713,7 +1778,8 @@ class Pico
|
|||
/**
|
||||
* Returns the data of the next page relative to the page being served
|
||||
*
|
||||
* @see Pico::discoverCurrentPage()
|
||||
* @see Pico::discoverCurrentPage()
|
||||
*
|
||||
* @return array|null page data
|
||||
*/
|
||||
public function getNextPage()
|
||||
|
|
@ -1729,9 +1795,10 @@ class Pico
|
|||
* registers Pico's core Twig filters `link` and `content` as well as
|
||||
* Pico's {@see PicoTwigExtension} Twig extension.
|
||||
*
|
||||
* @see Pico::getTwig()
|
||||
* @see http://twig.sensiolabs.org/ Twig website
|
||||
* @see https://github.com/twigphp/Twig Twig on GitHub
|
||||
* @see Pico::getTwig()
|
||||
* @see http://twig.sensiolabs.org/ Twig website
|
||||
* @see https://github.com/twigphp/Twig Twig on GitHub
|
||||
*
|
||||
* @return Twig_Environment|null Twig template engine
|
||||
*/
|
||||
public function getTwig()
|
||||
|
|
@ -1857,7 +1924,7 @@ class Pico
|
|||
/**
|
||||
* 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()
|
||||
{
|
||||
|
|
@ -1883,12 +1950,13 @@ class Pico
|
|||
* This method can be used in Twig templates by applying the `link` filter
|
||||
* to a string representing a page identifier.
|
||||
*
|
||||
* @param string $page identifier of the page to link to
|
||||
* @param array|string $queryData either an array containing properties to
|
||||
* @param string $page identifier of the page to link to
|
||||
* @param array|string $queryData either an array containing properties to
|
||||
* 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
|
||||
* @return string URL
|
||||
*
|
||||
* @return string URL
|
||||
*/
|
||||
public function getPageUrl($page, $queryData = null, $dropIndex = true)
|
||||
{
|
||||
|
|
@ -1928,8 +1996,9 @@ class Pico
|
|||
/**
|
||||
* Returns the page ID of a given content file
|
||||
*
|
||||
* @param string $path path to the content file
|
||||
* @return string|null either the corresponding page ID or NULL
|
||||
* @param string $path path to the content file
|
||||
*
|
||||
* @return string|null either the corresponding page ID or NULL
|
||||
*/
|
||||
public function getPageId($path)
|
||||
{
|
||||
|
|
@ -1991,17 +2060,19 @@ class Pico
|
|||
* {@see Pico::filterVariable()} for a detailed description. It can be
|
||||
* used in Twig templates by calling the `url_param` function.
|
||||
*
|
||||
* @see Pico::filterVariable()
|
||||
* @param string $name name of the URL GET parameter
|
||||
* @see Pico::filterVariable()
|
||||
*
|
||||
* @param string $name name of the URL GET parameter
|
||||
* to filter
|
||||
* @param int|string $filter the filter to apply
|
||||
* @param mixed|array $options either a associative options
|
||||
* @param int|string $filter the filter to apply
|
||||
* @param mixed|array $options either a associative options
|
||||
* array to be used by the filter or a scalar default value
|
||||
* @param int|string|int[]|string[] $flags flags and flag strings to
|
||||
* be used by the filter
|
||||
* @return mixed either the filtered data,
|
||||
* FALSE if the filter fails, or NULL if the URL GET parameter doesn't
|
||||
* exist and no default value is given
|
||||
* @param int|string|int[]|string[] $flags flags and flag strings to be
|
||||
* used by the filter
|
||||
*
|
||||
* @return mixed either the filtered data, FALSE if the filter fails, or
|
||||
* NULL if the URL GET parameter doesn't exist and no default value is
|
||||
* given
|
||||
*/
|
||||
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
|
||||
* used in Twig templates by calling the `form_param` function.
|
||||
*
|
||||
* @see Pico::filterVariable()
|
||||
* @param string $name name of the HTTP POST
|
||||
* @see Pico::filterVariable()
|
||||
*
|
||||
* @param string $name name of the HTTP POST
|
||||
* parameter to filter
|
||||
* @param int|string $filter the filter to apply
|
||||
* @param mixed|array $options either a associative options
|
||||
* @param int|string $filter the filter to apply
|
||||
* @param mixed|array $options either a associative options
|
||||
* array to be used by the filter or a scalar default value
|
||||
* @param int|string|int[]|string[] $flags flags and flag strings to
|
||||
* be used by the filter
|
||||
* @return mixed either the filtered data,
|
||||
* FALSE if the filter fails, or NULL if the HTTP POST parameter
|
||||
* doesn't exist and no default value is given
|
||||
* @param int|string|int[]|string[] $flags flags and flag strings to be
|
||||
* used by the filter
|
||||
*
|
||||
* @return mixed either the filtered data, FALSE if the filter fails, or
|
||||
* NULL if the HTTP POST parameter doesn't exist and no default value
|
||||
* is given
|
||||
*/
|
||||
public function getFormParameter($name, $filter = '', $options = null, $flags = null)
|
||||
{
|
||||
|
|
@ -2051,30 +2124,31 @@ class Pico
|
|||
* sanitization filters; be very careful with sanitization filters, you
|
||||
* 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
|
||||
* @see https://secure.php.net/manual/en/filter.filters.validate.php
|
||||
* @see https://secure.php.net/manual/en/filter.filters.validate.php
|
||||
* 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
|
||||
* @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
|
||||
* @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)`),
|
||||
* or a scalar default value that will be returned when the passed
|
||||
* 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
|
||||
* (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
|
||||
* and flag strings (optional)
|
||||
* @return mixed with a validation filter,
|
||||
* the method either returns the validated value or, provided that the
|
||||
* value wasn't valid, the given default value or FALSE; with a
|
||||
* sanitization filter, the method returns the sanitized value; if no
|
||||
* value (i.e. NULL) was given, the method always returns either the
|
||||
* provided default value or NULL
|
||||
*
|
||||
* @return mixed with a validation filter, the method either returns the
|
||||
* validated value or, provided that the value wasn't valid, the given
|
||||
* default value or FALSE; with a sanitization filter, the method
|
||||
* returns the sanitized value; if no value (i.e. NULL) was given, the
|
||||
* method always returns either the provided default value or 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
|
||||
* matching the specified file extension
|
||||
*
|
||||
* @param string $directory start directory
|
||||
* @param string $fileExtension return files with the given file extension
|
||||
* @param string $directory start directory
|
||||
* @param string $fileExtension return files with the given file extension
|
||||
* 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
|
||||
* is the default behaviour), Pico::SORT_DESC for a descending order
|
||||
* 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)
|
||||
{
|
||||
|
|
@ -2156,15 +2231,17 @@ class Pico
|
|||
/**
|
||||
* 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
|
||||
* @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
|
||||
* @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
|
||||
* default behaviour), Pico::SORT_DESC for a descending order or
|
||||
* 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)
|
||||
{
|
||||
|
|
@ -2191,8 +2268,9 @@ class Pico
|
|||
*
|
||||
* This method also guarantees a trailing slash.
|
||||
*
|
||||
* @param string $path relative or absolute path
|
||||
* @return string absolute path
|
||||
* @param string $path relative or absolute path
|
||||
*
|
||||
* @return string absolute path
|
||||
*/
|
||||
public function getAbsolutePath($path)
|
||||
{
|
||||
|
|
@ -2219,11 +2297,13 @@ class Pico
|
|||
*
|
||||
* You MUST NOT trigger events of Pico's core with a plugin!
|
||||
*
|
||||
* @see PicoPluginInterface
|
||||
* @see AbstractPicoPlugin
|
||||
* @see DummyPlugin
|
||||
* @param string $eventName name of the event to trigger
|
||||
* @param array $params optional parameters to pass
|
||||
* @see PicoPluginInterface
|
||||
* @see AbstractPicoPlugin
|
||||
* @see DummyPlugin
|
||||
*
|
||||
* @param string $eventName name of the event to trigger
|
||||
* @param array $params optional parameters to pass
|
||||
*
|
||||
* @return void
|
||||
*/
|
||||
public function triggerEvent($eventName, array $params = array())
|
||||
|
|
|
|||
|
|
@ -1,4 +1,14 @@
|
|||
<?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
|
||||
|
|
@ -30,8 +40,9 @@ interface PicoPluginInterface
|
|||
/**
|
||||
* Handles a event that was triggered by Pico
|
||||
*
|
||||
* @param string $eventName name of the triggered event
|
||||
* @param array $params passed parameters
|
||||
* @param string $eventName name of the triggered event
|
||||
* @param array $params passed parameters
|
||||
*
|
||||
* @return void
|
||||
*/
|
||||
public function handleEvent($eventName, array $params);
|
||||
|
|
@ -39,35 +50,40 @@ interface PicoPluginInterface
|
|||
/**
|
||||
* Enables or disables this plugin
|
||||
*
|
||||
* @see PicoPluginInterface::isEnabled()
|
||||
* @see PicoPluginInterface::isStatusChanged()
|
||||
* @param boolean $enabled enable (true) or disable (false) this plugin
|
||||
* @param boolean $recursive when true, enable or disable recursively
|
||||
* @see PicoPluginInterface::isEnabled()
|
||||
* @see PicoPluginInterface::isStatusChanged()
|
||||
*
|
||||
* @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
|
||||
* enabled, too. When disabling a plugin, all depending plugins are
|
||||
* disabled likewise. Recursive operations are only performed as long
|
||||
* as a plugin wasn't enabled/disabled manually. This parameter is
|
||||
* optional and defaults to true.
|
||||
* @param boolean $auto enable or disable to fulfill a dependency
|
||||
* This parameter is optional and defaults to false.
|
||||
* optional and defaults to TRUE.
|
||||
* @param bool $auto enable or disable to fulfill a dependency. This
|
||||
* parameter is optional and defaults to FALSE.
|
||||
*
|
||||
* @return void
|
||||
* @throws RuntimeException thrown when a dependency fails
|
||||
*
|
||||
* @throws RuntimeException thrown when a dependency fails
|
||||
*/
|
||||
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()
|
||||
* @return boolean plugin is enabled (true) or disabled (false)
|
||||
* @see PicoPluginInterface::setEnabled()
|
||||
*
|
||||
* @return bool plugin is enabled (TRUE) or disabled (FALSE)
|
||||
*/
|
||||
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()
|
||||
* @return boolean plugin is in its default state (true), false otherwise
|
||||
* @see PicoPluginInterface::setEnabled()
|
||||
*
|
||||
* @return bool plugin is in its default state (TRUE), FALSE otherwise
|
||||
*/
|
||||
public function isStatusChanged();
|
||||
|
||||
|
|
@ -88,7 +104,8 @@ interface PicoPluginInterface
|
|||
/**
|
||||
* Returns the plugins instance of Pico
|
||||
*
|
||||
* @see Pico
|
||||
* @see Pico
|
||||
*
|
||||
* @return Pico the plugins instance of Pico
|
||||
*/
|
||||
public function getPico();
|
||||
|
|
|
|||
|
|
@ -1,4 +1,14 @@
|
|||
<?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
|
||||
|
|
@ -31,8 +41,9 @@ class PicoTwigExtension extends Twig_Extension
|
|||
/**
|
||||
* Returns the extensions instance of Pico
|
||||
*
|
||||
* @see Pico
|
||||
* @return Pico the extensions instance of Pico
|
||||
* @see Pico
|
||||
*
|
||||
* @return Pico the extension's instance of Pico
|
||||
*/
|
||||
public function getPico()
|
||||
{
|
||||
|
|
@ -42,7 +53,8 @@ class PicoTwigExtension extends Twig_Extension
|
|||
/**
|
||||
* Returns the name of the extension
|
||||
*
|
||||
* @see Twig_ExtensionInterface::getName()
|
||||
* @see Twig_ExtensionInterface::getName()
|
||||
*
|
||||
* @return string the extension name
|
||||
*/
|
||||
public function getName()
|
||||
|
|
@ -53,7 +65,8 @@ class PicoTwigExtension extends Twig_Extension
|
|||
/**
|
||||
* 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
|
||||
*/
|
||||
public function getFilters()
|
||||
|
|
@ -69,7 +82,8 @@ class PicoTwigExtension extends Twig_Extension
|
|||
/**
|
||||
* 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
|
||||
*/
|
||||
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
|
||||
* instead, what ensures the proper preparation of the contents.
|
||||
*
|
||||
* @see Pico::substituteFileContent()
|
||||
* @see Pico::parseFileContent()
|
||||
* @param string $markdown markdown to parse
|
||||
* @param array $meta meta data to use for %meta.*% replacement
|
||||
* @return string parsed HTML
|
||||
* @see Pico::substituteFileContent()
|
||||
* @see Pico::parseFileContent()
|
||||
*
|
||||
* @param string $markdown markdown to parse
|
||||
* @param array $meta meta data to use for %meta.*% replacement
|
||||
*
|
||||
* @return string parsed HTML
|
||||
*/
|
||||
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
|
||||
* filter to e.g. get all page titles (`{{ pages|map("title") }}`).
|
||||
*
|
||||
* @param array|Traversable $var variable to map
|
||||
* @param mixed $mapKeyPath key to map; either a scalar or a
|
||||
* @param array|Traversable $var variable to map
|
||||
* @param mixed $mapKeyPath key to map; either a scalar or a
|
||||
* array interpreted as key path (i.e. ['foo', 'bar'] will return all
|
||||
* $item['foo']['bar'] values)
|
||||
* @return array mapped values
|
||||
*
|
||||
* @return array mapped values
|
||||
*/
|
||||
public function mapFilter($var, $mapKeyPath)
|
||||
{
|
||||
|
|
@ -140,16 +157,17 @@ class PicoTwigExtension extends Twig_Extension
|
|||
* always sorted in ascending order, apply Twigs `reverse` filter to
|
||||
* achieve a descending order.
|
||||
*
|
||||
* @param array|Traversable $var variable to sort
|
||||
* @param mixed $sortKeyPath key to use for sorting; either
|
||||
* @param array|Traversable $var variable to sort
|
||||
* @param mixed $sortKeyPath key to use for sorting; either
|
||||
* a scalar or a array interpreted as key path (i.e. ['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)
|
||||
* 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
|
||||
* these items
|
||||
* @return array sorted array
|
||||
*
|
||||
* @return array sorted array
|
||||
*/
|
||||
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
|
||||
* arbitrary deep sub-key using a key path
|
||||
*
|
||||
* @param array|Traversable|ArrayAccess|object $var base variable
|
||||
* @param mixed $keyPath scalar key or a
|
||||
* @param array|Traversable|ArrayAccess|object $var base variable
|
||||
* @param mixed $keyPath scalar key or a
|
||||
* array interpreted as key path (when passing e.g. ['foo', 'bar'],
|
||||
* 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)
|
||||
{
|
||||
|
|
|
|||
|
|
@ -1,4 +1,14 @@
|
|||
<?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
|
||||
|
|
@ -27,7 +37,7 @@ class DummyPlugin extends AbstractPicoPlugin
|
|||
* property.
|
||||
*
|
||||
* @see AbstractPicoPlugin::$enabled
|
||||
* @var boolean
|
||||
* @var bool
|
||||
*/
|
||||
protected $enabled = false;
|
||||
|
||||
|
|
@ -48,9 +58,11 @@ class DummyPlugin extends AbstractPicoPlugin
|
|||
* This event is triggered nevertheless the plugin is enabled or not.
|
||||
* It is NOT guaranteed that plugin dependencies are fulfilled!
|
||||
*
|
||||
* @see Pico::getPlugin()
|
||||
* @see Pico::getPlugins()
|
||||
* @param object[] $plugins loaded plugin instances
|
||||
* @see Pico::getPlugin()
|
||||
* @see Pico::getPlugins()
|
||||
*
|
||||
* @param object[] $plugins loaded plugin instances
|
||||
*
|
||||
* @return void
|
||||
*/
|
||||
public function onPluginsLoaded(array $plugins)
|
||||
|
|
@ -61,9 +73,11 @@ class DummyPlugin extends AbstractPicoPlugin
|
|||
/**
|
||||
* Triggered when Pico manually loads a plugin
|
||||
*
|
||||
* @see Pico::getPlugin()
|
||||
* @see Pico::getPlugins()
|
||||
* @param object $plugin loaded plugin instance
|
||||
* @see Pico::getPlugin()
|
||||
* @see Pico::getPlugins()
|
||||
*
|
||||
* @param object $plugin loaded plugin instance
|
||||
*
|
||||
* @return void
|
||||
*/
|
||||
public function onPluginManuallyLoaded($plugin)
|
||||
|
|
@ -74,8 +88,10 @@ class DummyPlugin extends AbstractPicoPlugin
|
|||
/**
|
||||
* Triggered after Pico has read its configuration
|
||||
*
|
||||
* @see Pico::getConfig()
|
||||
* @param array &$config array of config variables
|
||||
* @see Pico::getConfig()
|
||||
*
|
||||
* @param array &$config array of config variables
|
||||
*
|
||||
* @return void
|
||||
*/
|
||||
public function onConfigLoaded(array &$config)
|
||||
|
|
@ -86,8 +102,10 @@ class DummyPlugin extends AbstractPicoPlugin
|
|||
/**
|
||||
* Triggered after Pico has evaluated the request URL
|
||||
*
|
||||
* @see Pico::getRequestUrl()
|
||||
* @param string &$url part of the URL describing the requested contents
|
||||
* @see Pico::getRequestUrl()
|
||||
*
|
||||
* @param string &$url part of the URL describing the requested contents
|
||||
*
|
||||
* @return void
|
||||
*/
|
||||
public function onRequestUrl(&$url)
|
||||
|
|
@ -98,9 +116,11 @@ class DummyPlugin extends AbstractPicoPlugin
|
|||
/**
|
||||
* Triggered after Pico has discovered the content file to serve
|
||||
*
|
||||
* @see Pico::getBaseUrl()
|
||||
* @see Pico::getRequestFile()
|
||||
* @param string &$file absolute path to the content file to serve
|
||||
* @see Pico::getBaseUrl()
|
||||
* @see Pico::getRequestFile()
|
||||
*
|
||||
* @param string &$file absolute path to the content file to serve
|
||||
*
|
||||
* @return void
|
||||
*/
|
||||
public function onRequestFile(&$file)
|
||||
|
|
@ -111,8 +131,9 @@ class DummyPlugin extends AbstractPicoPlugin
|
|||
/**
|
||||
* Triggered before Pico reads the contents of the file to serve
|
||||
*
|
||||
* @see Pico::loadFileContent()
|
||||
* @see DummyPlugin::onContentLoaded()
|
||||
* @see Pico::loadFileContent()
|
||||
* @see DummyPlugin::onContentLoaded()
|
||||
*
|
||||
* @return void
|
||||
*/
|
||||
public function onContentLoading()
|
||||
|
|
@ -123,8 +144,9 @@ class DummyPlugin extends AbstractPicoPlugin
|
|||
/**
|
||||
* Triggered before Pico reads the contents of a 404 file
|
||||
*
|
||||
* @see Pico::load404Content()
|
||||
* @see DummyPlugin::on404ContentLoaded()
|
||||
* @see Pico::load404Content()
|
||||
* @see DummyPlugin::on404ContentLoaded()
|
||||
*
|
||||
* @return void
|
||||
*/
|
||||
public function on404ContentLoading()
|
||||
|
|
@ -135,8 +157,10 @@ class DummyPlugin extends AbstractPicoPlugin
|
|||
/**
|
||||
* Triggered after Pico has read the contents of the 404 file
|
||||
*
|
||||
* @see Pico::getRawContent()
|
||||
* @param string &$rawContent raw file contents
|
||||
* @see Pico::getRawContent()
|
||||
*
|
||||
* @param string &$rawContent raw file contents
|
||||
*
|
||||
* @return void
|
||||
*/
|
||||
public function on404ContentLoaded(&$rawContent)
|
||||
|
|
@ -151,8 +175,10 @@ class DummyPlugin extends AbstractPicoPlugin
|
|||
* of said 404 file. Use {@see Pico::is404Content()} to check for this
|
||||
* case when necessary.
|
||||
*
|
||||
* @see Pico::getRawContent()
|
||||
* @param string &$rawContent raw file contents
|
||||
* @see Pico::getRawContent()
|
||||
*
|
||||
* @param string &$rawContent raw file contents
|
||||
*
|
||||
* @return void
|
||||
*/
|
||||
public function onContentLoaded(&$rawContent)
|
||||
|
|
@ -163,8 +189,9 @@ class DummyPlugin extends AbstractPicoPlugin
|
|||
/**
|
||||
* Triggered before Pico parses the meta header
|
||||
*
|
||||
* @see Pico::parseFileMeta()
|
||||
* @see DummyPlugin::onMetaParsed()
|
||||
* @see Pico::parseFileMeta()
|
||||
* @see DummyPlugin::onMetaParsed()
|
||||
*
|
||||
* @return void
|
||||
*/
|
||||
public function onMetaParsing()
|
||||
|
|
@ -175,8 +202,10 @@ class DummyPlugin extends AbstractPicoPlugin
|
|||
/**
|
||||
* Triggered after Pico has parsed the meta header
|
||||
*
|
||||
* @see Pico::getFileMeta()
|
||||
* @param string[] &$meta parsed meta data
|
||||
* @see Pico::getFileMeta()
|
||||
*
|
||||
* @param string[] &$meta parsed meta data
|
||||
*
|
||||
* @return void
|
||||
*/
|
||||
public function onMetaParsed(array &$meta)
|
||||
|
|
@ -187,9 +216,10 @@ class DummyPlugin extends AbstractPicoPlugin
|
|||
/**
|
||||
* Triggered before Pico parses the pages content
|
||||
*
|
||||
* @see Pico::prepareFileContent()
|
||||
* @see DummyPlugin::prepareFileContent()
|
||||
* @see DummyPlugin::onContentParsed()
|
||||
* @see Pico::prepareFileContent()
|
||||
* @see DummyPlugin::prepareFileContent()
|
||||
* @see DummyPlugin::onContentParsed()
|
||||
*
|
||||
* @return void
|
||||
*/
|
||||
public function onContentParsing()
|
||||
|
|
@ -200,9 +230,11 @@ class DummyPlugin extends AbstractPicoPlugin
|
|||
/**
|
||||
* Triggered after Pico has prepared the raw file contents for parsing
|
||||
*
|
||||
* @see Pico::parseFileContent()
|
||||
* @see DummyPlugin::onContentParsed()
|
||||
* @param string &$markdown Markdown contents of the requested page
|
||||
* @see Pico::parseFileContent()
|
||||
* @see DummyPlugin::onContentParsed()
|
||||
*
|
||||
* @param string &$markdown Markdown contents of the requested page
|
||||
*
|
||||
* @return void
|
||||
*/
|
||||
public function onContentPrepared(&$markdown)
|
||||
|
|
@ -213,8 +245,10 @@ class DummyPlugin extends AbstractPicoPlugin
|
|||
/**
|
||||
* Triggered after Pico has parsed the contents of the file to serve
|
||||
*
|
||||
* @see Pico::getFileContent()
|
||||
* @param string &$content parsed contents (HTML) of the requested page
|
||||
* @see Pico::getFileContent()
|
||||
*
|
||||
* @param string &$content parsed contents (HTML) of the requested page
|
||||
*
|
||||
* @return void
|
||||
*/
|
||||
public function onContentParsed(&$content)
|
||||
|
|
@ -225,12 +259,13 @@ class DummyPlugin extends AbstractPicoPlugin
|
|||
/**
|
||||
* Triggered before Pico reads all known pages
|
||||
*
|
||||
* @see Pico::readPages()
|
||||
* @see DummyPlugin::onSinglePageLoading()
|
||||
* @see DummyPlugin::onSinglePageContent()
|
||||
* @see DummyPlugin::onSinglePageLoaded()
|
||||
* @see DummyPlugin::onPagesDiscovered()
|
||||
* @see DummyPlugin::onPagesLoaded()
|
||||
* @see Pico::readPages()
|
||||
* @see DummyPlugin::onSinglePageLoading()
|
||||
* @see DummyPlugin::onSinglePageContent()
|
||||
* @see DummyPlugin::onSinglePageLoaded()
|
||||
* @see DummyPlugin::onPagesDiscovered()
|
||||
* @see DummyPlugin::onPagesLoaded()
|
||||
*
|
||||
* @return void
|
||||
*/
|
||||
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
|
||||
* NULL! Someone likely set it to TRUE or FALSE on purpose...
|
||||
*
|
||||
* @see DummyPlugin::onSinglePageContent()
|
||||
* @see DummyPlugin::onSinglePageLoaded()
|
||||
* @see DummyPlugin::onPagesDiscovered()
|
||||
* @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
|
||||
* the pages array, otherwise leave it unchanged
|
||||
* @see DummyPlugin::onSinglePageContent()
|
||||
* @see DummyPlugin::onSinglePageLoaded()
|
||||
* @see DummyPlugin::onPagesDiscovered()
|
||||
* @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 the
|
||||
* pages array, otherwise leave it unchanged
|
||||
*
|
||||
* @return void
|
||||
*/
|
||||
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
|
||||
* raw contents of this page were loaded already.
|
||||
*
|
||||
* @see DummyPlugin::onSinglePageLoaded()
|
||||
* @see DummyPlugin::onPagesDiscovered()
|
||||
* @see DummyPlugin::onPagesLoaded()
|
||||
* @param string $id relative path to the content file
|
||||
* @param string &$rawContent raw file contents
|
||||
* @see DummyPlugin::onSinglePageLoaded()
|
||||
* @see DummyPlugin::onPagesDiscovered()
|
||||
* @see DummyPlugin::onPagesLoaded()
|
||||
*
|
||||
* @param string $id relative path to the content file
|
||||
* @param string &$rawContent raw file contents
|
||||
*
|
||||
* @return void
|
||||
*/
|
||||
public function onSinglePageContent($id, &$rawContent)
|
||||
|
|
@ -285,30 +324,32 @@ class DummyPlugin extends AbstractPicoPlugin
|
|||
*
|
||||
* The `$pageData` parameter consists of the following values:
|
||||
*
|
||||
* | Array key | Type | Description |
|
||||
* | -------------- | ------- | ------------------------------------------ |
|
||||
* | id | string | relative path to the content file |
|
||||
* | url | string | URL to the page |
|
||||
* | title | string | title of the page (YAML header) |
|
||||
* | description | string | description of the page (YAML header) |
|
||||
* | author | string | author of the page (YAML header) |
|
||||
* | time | string | timestamp derived from the Date header |
|
||||
* | date | string | date of the page (YAML header) |
|
||||
* | date_formatted | string | formatted date of the page |
|
||||
* | hidden | boolean | this page shouldn't be visible to the user |
|
||||
* | raw_content | string | raw, not yet parsed contents of the page |
|
||||
* | meta | string | parsed meta data of the page |
|
||||
* | previous_page | &array | reference to the previous page |
|
||||
* | next_page | &array | reference to the next page |
|
||||
* | Array key | Type | Description |
|
||||
* | -------------- | ------ | ------------------------------------------ |
|
||||
* | id | string | relative path to the content file |
|
||||
* | url | string | URL to the page |
|
||||
* | title | string | title of the page (YAML header) |
|
||||
* | description | string | description of the page (YAML header) |
|
||||
* | author | string | author of the page (YAML header) |
|
||||
* | time | string | timestamp derived from the Date header |
|
||||
* | date | string | date of the page (YAML header) |
|
||||
* | date_formatted | string | formatted date of the page |
|
||||
* | hidden | bool | this page shouldn't be visible to the user |
|
||||
* | raw_content | string | raw, not yet parsed contents of the page |
|
||||
* | meta | string | parsed meta data of the page |
|
||||
* | previous_page | &array | reference to the previous page |
|
||||
* | next_page | &array | reference to the next page |
|
||||
*
|
||||
* Please note that the `previous_page` and `next_page` keys won't be
|
||||
* available until the `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
|
||||
*/
|
||||
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
|
||||
* sorted yet.
|
||||
*
|
||||
* @see Pico::sortPages()
|
||||
* @see DummyPlugin::onPagesLoaded()
|
||||
* @param array[] &$pages data of all known pages
|
||||
* @see Pico::sortPages()
|
||||
* @see DummyPlugin::onPagesLoaded()
|
||||
*
|
||||
* @param array[] &$pages data of all known pages
|
||||
*
|
||||
* @return void
|
||||
*/
|
||||
public function onPagesDiscovered(array &$pages)
|
||||
|
|
@ -339,8 +382,10 @@ class DummyPlugin extends AbstractPicoPlugin
|
|||
* See {@see DummyPlugin::onSinglePageLoaded()} for details about the
|
||||
* structure of the page data.
|
||||
*
|
||||
* @see Pico::getPages()
|
||||
* @param array[] &$pages data of all known pages
|
||||
* @see Pico::getPages()
|
||||
*
|
||||
* @param array[] &$pages data of all known pages
|
||||
*
|
||||
* @return void
|
||||
*/
|
||||
public function onPagesLoaded(array &$pages)
|
||||
|
|
@ -354,14 +399,16 @@ class DummyPlugin extends AbstractPicoPlugin
|
|||
* See {@see DummyPlugin::onSinglePageLoaded()} for details about the
|
||||
* structure of the page data.
|
||||
*
|
||||
* @see Pico::discoverPageSiblings()
|
||||
* @see Pico::discoverCurrentPage()
|
||||
* @see Pico::getCurrentPage()
|
||||
* @see Pico::getPreviousPage()
|
||||
* @see Pico::getNextPage()
|
||||
* @param array|null &$currentPage data of the page being served
|
||||
* @param array|null &$previousPage data of the previous page
|
||||
* @param array|null &$nextPage data of the next page
|
||||
* @see Pico::discoverPageSiblings()
|
||||
* @see Pico::discoverCurrentPage()
|
||||
* @see Pico::getCurrentPage()
|
||||
* @see Pico::getPreviousPage()
|
||||
* @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 &$nextPage data of the next page
|
||||
*
|
||||
* @return void
|
||||
*/
|
||||
public function onCurrentPageDiscovered(
|
||||
|
|
@ -375,11 +422,13 @@ class DummyPlugin extends AbstractPicoPlugin
|
|||
/**
|
||||
* Triggered before Pico renders the page
|
||||
*
|
||||
* @see Pico::getTwigTemplate()
|
||||
* @see Pico::getTwigVariables()
|
||||
* @see DummyPlugin::onPageRendered()
|
||||
* @param string &$templateName file name of the template
|
||||
* @param array &$twigVariables template variables
|
||||
* @see Pico::getTwigTemplate()
|
||||
* @see Pico::getTwigVariables()
|
||||
* @see DummyPlugin::onPageRendered()
|
||||
*
|
||||
* @param string &$templateName file name of the template
|
||||
* @param array &$twigVariables template variables
|
||||
*
|
||||
* @return void
|
||||
*/
|
||||
public function onPageRendering(&$templateName, array &$twigVariables)
|
||||
|
|
@ -390,7 +439,8 @@ class DummyPlugin extends AbstractPicoPlugin
|
|||
/**
|
||||
* 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
|
||||
*/
|
||||
public function onPageRendered(&$output)
|
||||
|
|
@ -401,10 +451,12 @@ class DummyPlugin extends AbstractPicoPlugin
|
|||
/**
|
||||
* Triggered when Pico reads its known meta header fields
|
||||
*
|
||||
* @see Pico::getMetaHeaders()
|
||||
* @param string[] &$headers list of known meta header
|
||||
* fields; the array key specifies the YAML key to search for, the
|
||||
* array value is later used to access the found value
|
||||
* @see Pico::getMetaHeaders()
|
||||
*
|
||||
* @param string[] &$headers list of known meta header fields; the array
|
||||
* key specifies the YAML key to search for, the array value is later
|
||||
* used to access the found value
|
||||
*
|
||||
* @return void
|
||||
*/
|
||||
public function onMetaHeaders(array &$headers)
|
||||
|
|
@ -415,8 +467,10 @@ class DummyPlugin extends AbstractPicoPlugin
|
|||
/**
|
||||
* Triggered when Pico registers the YAML parser
|
||||
*
|
||||
* @see Pico::getYamlParser()
|
||||
* @param \Symfony\Component\Yaml\Parser &$yamlParser YAML parser instance
|
||||
* @see Pico::getYamlParser()
|
||||
*
|
||||
* @param \Symfony\Component\Yaml\Parser &$yamlParser YAML parser instance
|
||||
*
|
||||
* @return void
|
||||
*/
|
||||
public function onYamlParserRegistered(\Symfony\Component\Yaml\Parser &$yamlParser)
|
||||
|
|
@ -427,8 +481,10 @@ class DummyPlugin extends AbstractPicoPlugin
|
|||
/**
|
||||
* Triggered when Pico registers the Parsedown parser
|
||||
*
|
||||
* @see Pico::getParsedown()
|
||||
* @param Parsedown &$parsedown Parsedown instance
|
||||
* @see Pico::getParsedown()
|
||||
*
|
||||
* @param Parsedown &$parsedown Parsedown instance
|
||||
*
|
||||
* @return void
|
||||
*/
|
||||
public function onParsedownRegistered(Parsedown &$parsedown)
|
||||
|
|
@ -439,8 +495,10 @@ class DummyPlugin extends AbstractPicoPlugin
|
|||
/**
|
||||
* Triggered when Pico registers the twig template engine
|
||||
*
|
||||
* @see Pico::getTwig()
|
||||
* @param Twig_Environment &$twig Twig instance
|
||||
* @see Pico::getTwig()
|
||||
*
|
||||
* @param Twig_Environment &$twig Twig instance
|
||||
*
|
||||
* @return void
|
||||
*/
|
||||
public function onTwigRegistered(Twig_Environment &$twig)
|
||||
|
|
|
|||
Loading…
Reference in a new issue