Constants

API_VERSION

API_VERSION

API version used by this plugin

Properties

$enabled

$enabled : boolean|null

This plugin is disabled by default

Usually you should remove this class property (or set it to NULL) to leave the decision whether this plugin should be enabled or disabled by default up to Pico. If all the plugin's dependenies are fulfilled (see \self::$dependsOn), Pico enables the plugin by default. Otherwise the plugin is silently disabled.

If this plugin should never be disabled silently (e.g. when dealing with security-relevant stuff like access control, or similar), set this to TRUE. If Pico can't fulfill all the plugin's dependencies, it will throw an RuntimeException.

If this plugin rather does some "crazy stuff" a user should really be aware of before using it, you can set this to FALSE. The user will then have to enable the plugin manually. However, if another plugin depends on this plugin, it might get enabled silently nevertheless.

No matter what, the user can always explicitly enable or disable this plugin in Pico's config.

Type

boolean|null

$statusChanged

$statusChanged : boolean

Boolean indicating if this plugin was ever enabled/disabled manually

Type

boolean

$nativePlugin

$nativePlugin : boolean|null

Boolean indicating whether this plugin matches Pico's API version

Type

boolean|null

$dependsOn

$dependsOn : array<mixed,string>

This plugin depends on .

..

If your plugin doesn't depend on any other plugin, remove this class property.

Type

array<mixed,string>

$pico

$pico : \Pico

Current instance of Pico

Type

\Pico

$dependants

$dependants : array<mixed,object>

List of plugin which depend on this plugin

Type

array<mixed,object>

Methods

__construct()

__construct(\Pico  $pico) 

Constructs a new instance of a Pico plugin

Parameters

\Pico $pico

current instance of Pico

handleEvent()

handleEvent(string  $eventName, array  $params) : void

Handles a event that was triggered by Pico

Parameters

string $eventName

name of the triggered event

array $params

passed parameters

setEnabled()

setEnabled(boolean  $enabled, boolean  $recursive = true, boolean  $auto = false) : void

Enables or disables this plugin

Parameters

boolean $enabled

enable (TRUE) or disable (FALSE) this plugin

boolean $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.

boolean $auto

enable or disable to fulfill a dependency. This parameter is optional and defaults to FALSE.

isEnabled()

isEnabled() : boolean|null

Returns a boolean indicating whether this plugin is enabled or not

You musn't rely on the return value when Pico's onConfigLoaded event wasn't triggered on all plugins yet. This method might even return NULL then. The plugin's status might change later.

Returns

boolean|null —

plugin is enabled (TRUE) or disabled (FALSE)

isStatusChanged()

isStatusChanged() : boolean

Returns TRUE if the plugin was ever enabled/disabled manually

Returns

boolean —

plugin is in its default state (TRUE), FALSE otherwise

getPico()

getPico() : \Pico

Returns the plugins instance of Pico

Returns

\Pico

the plugins instance of Pico

getPluginConfig()

getPluginConfig(string  $configName = null, mixed  $default = null) : mixed

Returns either the value of the specified plugin config variable or the config array

Parameters

string $configName

optional name of a config variable

mixed $default

optional default value to return when the named config variable doesn't exist

Returns

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

__call()

__call(string  $methodName, array  $params) : mixed

Passes all not satisfiable method calls to Pico

Parameters

string $methodName

name of the method to call

array $params

parameters to pass

Returns

mixed —

return value of the called method

getDependencies()

getDependencies() : array<mixed,string>

Returns a list of names of plugins required by this plugin

Returns

array<mixed,string> —

required plugins

getDependants()

getDependants() : array<mixed,object>

Returns a list of plugins which depend on this plugin

Returns

array<mixed,object> —

dependant plugins

onPluginsLoaded()

onPluginsLoaded(array<mixed,object>  $plugins) : void

Triggered after Pico has loaded all available plugins

This event is triggered nevertheless the plugin is enabled or not. It is NOT guaranteed that plugin dependencies are fulfilled!

Parameters

array<mixed,object> $plugins

loaded plugin instances

onPluginManuallyLoaded()

onPluginManuallyLoaded(object  $plugin) : void

Triggered when Pico manually loads a plugin

Parameters

object $plugin

loaded plugin instance

onConfigLoaded()

onConfigLoaded(array  $config) : void

Triggered after Pico has read its configuration

Parameters

array $config

onRequestUrl()

onRequestUrl(  $url) : void

Triggered after Pico has evaluated the request URL

Parameters

$url

onRequestFile()

onRequestFile(  $file) : void

Triggered after Pico has discovered the content file to serve

Parameters

$file

onContentLoading()

onContentLoading() : void

Triggered before Pico reads the contents of the file to serve

on404ContentLoading()

on404ContentLoading() : void

Triggered before Pico reads the contents of a 404 file

on404ContentLoaded()

on404ContentLoaded(  $rawContent) : void

Triggered after Pico has read the contents of the 404 file

Parameters

$rawContent

onContentLoaded()

onContentLoaded(  $rawContent) : void

Triggered after Pico has read the contents of the file to serve

If Pico serves a 404 file, this event is triggered with the raw contents of said 404 file. Use \Pico::is404Content() to check for this case when necessary.

Parameters

$rawContent

onMetaParsing()

onMetaParsing() : void

Triggered before Pico parses the meta header

onMetaParsed()

onMetaParsed(array  $meta) : void

Triggered after Pico has parsed the meta header

Parameters

array $meta

onContentParsing()

onContentParsing() : void

Triggered before Pico parses the pages content

onContentPrepared()

onContentPrepared(  $markdown) : void

Triggered after Pico has prepared the raw file contents for parsing

Parameters

$markdown

onContentParsed()

onContentParsed(  $content) : void

Triggered after Pico has parsed the contents of the file to serve

Parameters

$content

onPagesLoading()

onPagesLoading() : void

Triggered before Pico reads all known pages

onSinglePageLoading()

onSinglePageLoading(string  $id, boolean|null  $skipPage) : void

Triggered before Pico loads a single page

Set the $skipFile parameter to TRUE to remove this page from the pages array. Pico usually passes NULL by default, unless it is a conflicting page (i.e. content/sub.md, but there's also a content/sub/index.md), 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...

Parameters

string $id

relative path to the content file

boolean|null $skipPage

set this to TRUE to remove this page from the pages array, otherwise leave it unchanged

onSinglePageContent()

onSinglePageContent(string  $id,   $rawContent) : void

Triggered when Pico loads the raw contents of a single page

Please note that this event isn't triggered when the currently processed page is the requested page. The reason for this exception is that the raw contents of this page were loaded already.

Parameters

string $id

relative path to the content file

$rawContent

onSinglePageLoaded()

onSinglePageLoaded(array  $pageData) : void

Triggered when Pico loads a single page

Please refer to \Pico::readPages() for information about the structure of a single page's data.

Parameters

array $pageData

onPagesDiscovered()

onPagesDiscovered(array  $pages) : void

Triggered after Pico has discovered all known pages

Pico's pages array isn't sorted until the onPagesLoaded event is triggered. Please refer to \Pico::readPages() for information about the structure of Pico's pages array and the structure of a single page's data.

Parameters

array $pages

onPagesLoaded()

onPagesLoaded(array  $pages) : void

Triggered after Pico has sorted the pages array

Please refer to \Pico::readPages() for information about the structure of Pico's pages array and the structure of a single page's data.

Parameters

array $pages

onCurrentPageDiscovered()

onCurrentPageDiscovered(array  $currentPage = null, array  $previousPage = null, array  $nextPage = null) : void

Triggered when Pico discovered the current, previous and next pages

If Pico isn't serving a regular page, but a plugin's virtual page, there will neither be a current, nor previous or next pages. Please refer to \Pico::readPages() for information about the structure of a single page's data.

Parameters

array $currentPage
array $previousPage
array $nextPage

onPageTreeBuilt()

onPageTreeBuilt(array  $pageTree) : void

Triggered after Pico built the page tree

Please refer to \Pico::buildPageTree() for information about the structure of Pico's page tree array.

Parameters

array $pageTree

onPageRendering()

onPageRendering(  $templateName, array  $twigVariables) : void

Triggered before Pico renders the page

Parameters

$templateName
array $twigVariables

onPageRendered()

onPageRendered(  $output) : void

Triggered after Pico has rendered the page

Parameters

$output

onMetaHeaders()

onMetaHeaders(array  $headers) : void

Triggered when Pico reads its known meta header fields

Parameters

array $headers

onYamlParserRegistered()

onYamlParserRegistered(\Symfony\Component\Yaml\Parser  $yamlParser) : void

Triggered when Pico registers the YAML parser

Parameters

\Symfony\Component\Yaml\Parser $yamlParser

onParsedownRegistered()

onParsedownRegistered(\Parsedown  $parsedown) : void

Triggered when Pico registers the Parsedown parser

Parameters

\Parsedown $parsedown

onTwigRegistered()

onTwigRegistered(\Twig_Environment  $twig) : void

Triggered when Pico registers the twig template engine

Parameters

\Twig_Environment $twig

checkDependencies()

checkDependencies(boolean  $recursive) : void

Enables all plugins which this plugin depends on

Parameters

boolean $recursive

enable required plugins automatically

Throws

\RuntimeException

thrown when a dependency fails

checkDependants()

checkDependants(boolean  $recursive) : void

Disables all plugins which depend on this plugin

Parameters

boolean $recursive

disabled dependant plugins automatically

Throws

\RuntimeException

thrown when a dependency fails

checkCompatibility()

checkCompatibility() : void

Checks compatibility with Pico's API version

Pico automatically adds a dependency to \PicoDeprecated when the plugin's API is older than Pico's API. \PicoDeprecated furthermore throws a exception when it can't provide compatibility in such cases. However, we still have to decide whether this plugin is compatible to newer API versions, what requires some special (version specific) precaution and is therefore usually not the case.

Throws

\RuntimeException

thrown when the plugin's and Pico's API aren't compatible