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

Various small improvements

Browse Source 
- Improve class docs for phpDocumentor
- Add missing onPagesLoading() event to DummyPlugin
- Add some TODOs to the UPGRADE section of the docs
This commit is contained in:
Daniel Rudolf 2015-10-29 02:55:30 +01:00
parent f1fc4c979e
commit 54ce5b9699
6 changed files with 143 additions and 56 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

20
lib/AbstractPicoPlugin.php
View File

@ -15,44 +15,43 @@ abstract class AbstractPicoPlugin implements PicoPluginInterface
/** /**
* Current instance of Pico * Current instance of Pico
* *
* @var Pico
* @see PicoPluginInterface::__construct()
* @see PicoPluginInterface::getPico() * @see PicoPluginInterface::getPico()
* @var Pico
*/ */
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)
* *
* @var boolean
* @see PicoPluginInterface::isEnabled() * @see PicoPluginInterface::isEnabled()
* @see PicoPluginInterface::setEnabled() * @see PicoPluginInterface::setEnabled()
* @var boolean
*/ */
protected $enabled = true; protected $enabled = true;
/** /**
* Boolean indicating if this plugin was ever enabled/disabled manually * Boolean indicating if this plugin was ever enabled/disabled manually
* *
* @var boolean
* @see PicoPluginInterface::isStatusChanged() * @see PicoPluginInterface::isStatusChanged()
* @var boolean
*/ */
protected $statusChanged = false; protected $statusChanged = false;
/** /**
* List of plugins which this plugin depends on * List of plugins which this plugin depends on
* *
* @var string[]
* @see PicoPluginInterface::getDependencies()
* @see AbstractPicoPlugin::checkDependencies() * @see AbstractPicoPlugin::checkDependencies()
* @see PicoPluginInterface::getDependencies()
* @var string[]
*/ */
protected $dependsOn = array(); protected $dependsOn = array();
/** /**
* List of plugin which depend on this plugin * List of plugin which depend on this plugin
* *
* @var object[]
* @see PicoPluginInterface::getDependants()
* @see AbstractPicoPlugin::checkDependants() * @see AbstractPicoPlugin::checkDependants()
* @see PicoPluginInterface::getDependants()
* @var object[]
*/ */
private $dependants; private $dependants;
@ -129,8 +128,9 @@ abstract class AbstractPicoPlugin implements PicoPluginInterface
} }
/** /**
* Passes all not satisfiable method calls to {@link Pico} * Passes all not satisfiable method calls to Pico
* *
* @see Pico
* @param string $methodName name of the method to call * @param string $methodName name of the method to call
* @param array $params parameters to pass * @param array $params parameters to pass
* @return mixed return value of the called method * @return mixed return value of the called method
@ -150,6 +150,7 @@ abstract class AbstractPicoPlugin implements PicoPluginInterface
/** /**
* Enables all plugins which this plugin depends on * Enables all plugins which this plugin depends on
* *
* @see PicoPluginInterface::getDependencies()
* @param boolean $recursive enable required plugins automatically * @param boolean $recursive enable required plugins automatically
* @return void * @return void
* @throws RuntimeException thrown when a dependency fails * @throws RuntimeException thrown when a dependency fails
@ -198,6 +199,7 @@ abstract class AbstractPicoPlugin implements PicoPluginInterface
/** /**
* Disables all plugins which depend on this plugin * Disables all plugins which depend on this plugin
* *
* @see PicoPluginInterface::getDependants()
* @param boolean $recursive disabled dependant plugins automatically * @param boolean $recursive disabled dependant plugins automatically
* @return void * @return void
* @throws RuntimeException thrown when a dependency fails * @throws RuntimeException thrown when a dependency fails

98
lib/Pico.php
View File

@ -53,6 +53,7 @@ class Pico
/** /**
* Root directory of this Pico instance * Root directory of this Pico instance
* *
* @see Pico::getRootDir()
* @var string * @var string
*/ */
protected $rootDir; protected $rootDir;
@ -60,6 +61,7 @@ class Pico
/** /**
* Config directory of this Pico instance * Config directory of this Pico instance
* *
* @see Pico::getConfigDir()
* @var string * @var string
*/ */
protected $configDir; protected $configDir;
@ -67,6 +69,7 @@ class Pico
/** /**
* Plugins directory of this Pico instance * Plugins directory of this Pico instance
* *
* @see Pico::getPluginsDir()
* @var string * @var string
*/ */
protected $pluginsDir; protected $pluginsDir;
@ -74,6 +77,7 @@ class Pico
/** /**
* Themes directory of this Pico instance * Themes directory of this Pico instance
* *
* @see Pico::getThemesDir()
* @var string * @var string
*/ */
protected $themesDir; protected $themesDir;
@ -88,7 +92,7 @@ class Pico
/** /**
* List of loaded plugins * List of loaded plugins
* *
* @see Pico::loadPlugins() * @see Pico::getPlugins()
* @var object[]|null * @var object[]|null
*/ */
protected $plugins; protected $plugins;
@ -96,7 +100,7 @@ class Pico
/** /**
* Current configuration of this Pico instance * Current configuration of this Pico instance
* *
* @see Pico::loadConfig() * @see Pico::getConfig()
* @var mixed[]|null * @var mixed[]|null
*/ */
protected $config; protected $config;
@ -104,7 +108,7 @@ class Pico
/** /**
* Part of the URL describing the requested contents * Part of the URL describing the requested contents
* *
* @see Pico::evaluateRequestUrl() * @see Pico::getRequestUrl()
* @var string|null * @var string|null
*/ */
protected $requestUrl; protected $requestUrl;
@ -112,7 +116,7 @@ class Pico
/** /**
* Absolute path to the content file being served * Absolute path to the content file being served
* *
* @see Pico::discoverRequestFile() * @see Pico::getRequestFile()
* @var string|null * @var string|null
*/ */
protected $requestFile; protected $requestFile;
@ -120,7 +124,7 @@ class Pico
/** /**
* Raw, not yet parsed contents to serve * Raw, not yet parsed contents to serve
* *
* @see Pico::loadFileContent() * @see Pico::getRawContent()
* @var string|null * @var string|null
*/ */
protected $rawContent; protected $rawContent;
@ -128,7 +132,7 @@ class Pico
/** /**
* Meta data of the page to serve * Meta data of the page to serve
* *
* @see Pico::parseFileMeta() * @see Pico::getFileMeta()
* @var string[]|null * @var string[]|null
*/ */
protected $meta; protected $meta;
@ -136,8 +140,7 @@ class Pico
/** /**
* Parsed content being served * Parsed content being served
* *
* @see Pico::prepareFileContent() * @see Pico::getFileContent()
* @see Pico::parseFileContent()
* @var string|null * @var string|null
*/ */
protected $content; protected $content;
@ -145,7 +148,7 @@ class Pico
/** /**
* List of known pages * List of known pages
* *
* @see Pico::readPages() * @see Pico::getPages()
* @var array[]|null * @var array[]|null
*/ */
protected $pages; protected $pages;
@ -153,7 +156,7 @@ class Pico
/** /**
* Data of the page being served * Data of the page being served
* *
* @see Pico::discoverCurrentPage() * @see Pico::getCurrentPage()
* @var array|null * @var array|null
*/ */
protected $currentPage; protected $currentPage;
@ -161,7 +164,7 @@ class Pico
/** /**
* Data of the previous page relative to the page being served * Data of the previous page relative to the page being served
* *
* @see Pico::discoverCurrentPage() * @see Pico::getPreviousPage()
* @var array|null * @var array|null
*/ */
protected $previousPage; protected $previousPage;
@ -169,7 +172,7 @@ class Pico
/** /**
* Data of the next page relative to the page being served * Data of the next page relative to the page being served
* *
* @see Pico::discoverCurrentPage() * @see Pico::getNextPage()
* @var array|null * @var array|null
*/ */
protected $nextPage; protected $nextPage;
@ -177,7 +180,7 @@ class Pico
/** /**
* Twig instance used for template parsing * Twig instance used for template parsing
* *
* @see Pico::registerTwig() * @see Pico::getTwig()
* @var Twig_Environment|null * @var Twig_Environment|null
*/ */
protected $twig; protected $twig;
@ -185,6 +188,7 @@ class Pico
/** /**
* Variables passed to the twig template * Variables passed to the twig template
* *
* @see Pico::getTwigVariables
* @var mixed[]|null * @var mixed[]|null
*/ */
protected $twigVariables; protected $twigVariables;
@ -192,7 +196,7 @@ class Pico
/** /**
* Constructs a new Pico instance * Constructs a new Pico instance
* *
* To carry out all the processing in Pico, call the run() method. * To carry out all the processing in Pico, call {@link Pico::run()}.
* *
* @param string $rootDir root directory of this Pico instance * @param string $rootDir root directory of this Pico instance
* @param string $configDir config directory of this Pico instance * @param string $configDir config directory of this Pico instance
@ -355,6 +359,8 @@ class Pico
* to indicate their processing order. You MUST NOT use prefixes between * to indicate their processing order. You MUST NOT use prefixes between
* 00 and 19 (reserved for built-in plugins). * 00 and 19 (reserved for built-in plugins).
* *
* @see Pico::getPlugin()
* @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
*/ */
@ -386,6 +392,7 @@ class Pico
* rely on it. For more information see {@link PicoPluginInterface}. * rely on it. For more information see {@link PicoPluginInterface}.
* *
* @see Pico::loadPlugins() * @see Pico::loadPlugins()
* @see Pico::getPlugins()
* @param string $pluginName name of the plugin * @param string $pluginName name of the plugin
* @return object instance of the plugin * @return object instance of the plugin
* @throws RuntimeException thrown when the plugin wasn't found * @throws RuntimeException thrown when the plugin wasn't found
@ -403,6 +410,7 @@ class Pico
* Returns all loaded plugins * Returns all loaded plugins
* *
* @see Pico::loadPlugins() * @see Pico::loadPlugins()
* @see Pico::getPlugin()
* @return object[]|null * @return object[]|null
*/ */
public function getPlugins() public function getPlugins()
@ -413,6 +421,8 @@ class Pico
/** /**
* Loads the config.php from Pico::$configDir * Loads the config.php from Pico::$configDir
* *
* @see Pico::setConfig()
* @see Pico::getConfig()
* @return void * @return void
*/ */
protected function loadConfig() protected function loadConfig()
@ -459,12 +469,15 @@ class Pico
* *
* This method allows you to modify Picos config without creating a * This method allows you to modify Picos config without creating a
* {@path "config/config.php"} or changing some of its variables before * {@path "config/config.php"} or changing some of its variables before
* Pico starts processing. It can only be called between the constructor * Pico starts processing.
* call and Pico::run(). Options set with this method cannot be overwritten
* by {@path "config/config.php"}.
* *
* @param mixed[] $config array with configuration variables, like * You can call this method between {@link Pico::__construct()} and
* $config in {@path "config/config.php"} * {@link Pico::run()} only. Options set with this method cannot be
* overwritten by {@path "config/config.php"}.
*
* @see Pico::loadConfig()
* @see Pico::getConfig()
* @param mixed[] $config array with config variables
* @return void * @return void
* @throws RuntimeException thrown if Pico already started processing * @throws RuntimeException thrown if Pico already started processing
*/ */
@ -481,6 +494,7 @@ 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::loadConfig() * @see Pico::loadConfig()
* @param string $configName optional name of a config variable * @param string $configName optional name of a config variable
* @return mixed returns either the value of the named config * @return mixed returns either the value of the named config
@ -499,15 +513,15 @@ class Pico
/** /**
* Evaluates the requested URL * Evaluates the requested URL
* *
* Pico 1.0 uses the QUERY_STRING routing method (e.g. /pico/?sub/page) to * Pico 1.0 uses the `QUERY_STRING` routing method (e.g. `/pico/?sub/page`)
* support SEO-like URLs out-of-the-box with any webserver. You can still * to support SEO-like URLs out-of-the-box with any webserver. You can
* setup URL rewriting (e.g. using mod_rewrite on Apache) to basically * still setup URL rewriting (e.g. using `mod_rewrite` on Apache) to
* remove the `?` from URLs, but your rewritten URLs must follow the * basically remove the `?` from URLs, but your rewritten URLs must follow
* new QUERY_STRING principles. URL rewriting requires some special * the new `QUERY_STRING` principles. URL rewriting requires some special
* configuration on your webserver, but this should be "basic work" for * configuration on your webserver, but this should be "basic work" for
* any webmaster... * any webmaster...
* *
* Pico 0.9 and older required Apache with mod_rewrite enabled, thus old * Pico 0.9 and older required Apache with `mod_rewrite` enabled, thus old
* plugins, templates and contents may require you to enable URL rewriting * plugins, templates and contents may require you to enable URL rewriting
* to work. If you're upgrading from Pico 0.9, you will probably have to * to work. If you're upgrading from Pico 0.9, you will probably have to
* update your rewriting rules. * update your rewriting rules.
@ -518,6 +532,7 @@ class Pico
* `%base_url%` variable; e.g. `%base_url%?sub/page` will be automatically * `%base_url%` variable; e.g. `%base_url%?sub/page` will be automatically
* replaced accordingly. * replaced accordingly.
* *
* @see Pico::getRequestUrl()
* @return void * @return void
*/ */
protected function evaluateRequestUrl() protected function evaluateRequestUrl()
@ -549,6 +564,7 @@ class Pico
/** /**
* Uses the request URL to discover the content file to serve * Uses the request URL to discover the content file to serve
* *
* @see Pico::getRequestFile()
* @return void * @return void
*/ */
protected function discoverRequestFile() protected function discoverRequestFile()
@ -611,6 +627,7 @@ class Pico
/** /**
* Returns the raw contents of a file * Returns the raw contents of a file
* *
* @see Pico::getRawContent()
* @param string $file file path * @param string $file file path
* @return string raw contents of the file * @return string raw contents of the file
*/ */
@ -623,6 +640,7 @@ class Pico
* Returns the raw contents of the first found 404 file when traversing * Returns the raw contents of the first found 404 file when traversing
* up from the directory the requested file is in * up from the directory the requested file is in
* *
* @see Pico::getRawContent()
* @param string $file path to requested (but not existing) file * @param string $file path to requested (but not existing) file
* @return string raw contents of the 404 file * @return string raw contents of the 404 file
* @throws RuntimeException thrown when no suitable 404 file is found * @throws RuntimeException thrown when no suitable 404 file is found
@ -644,9 +662,10 @@ class Pico
} }
/** /**
* Returns the cached 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()
* @return string|null raw contents * @return string|null raw contents
*/ */
public function getRawContent() public function getRawContent()
@ -683,12 +702,13 @@ class Pico
* Parses the file meta from raw file contents * Parses the file meta from raw file contents
* *
* Meta data MUST start on the first line of the file, either opened and * Meta data MUST start on the first line of the file, either opened and
* closed by --- or C-style block comments (deprecated). The headers are * closed by `---` or C-style block comments (deprecated). The headers are
* parsed by the YAML component of the Symfony project, keys are lowered. * parsed by the YAML component of the Symfony project, keys are lowered.
* If you're a plugin developer, you MUST register new headers during the * If you're a plugin developer, you MUST register new headers during the
* `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 <http://symfony.com/doc/current/components/yaml/introduction.html> * @see <http://symfony.com/doc/current/components/yaml/introduction.html>
* @param string $rawContent the raw file contents * @param string $rawContent the raw file contents
* @param string[] $headers known meta headers * @param string[] $headers known meta headers
@ -751,6 +771,8 @@ class Pico
* Applies some static preparations to the raw contents of a page, * Applies some static preparations to the raw contents of a page,
* e.g. removing the meta header and replacing %base_url% * e.g. removing the meta header and replacing %base_url%
* *
* @see Pico::parseFileContent()
* @see Pico::getFileContent()
* @param string $rawContent raw contents of a page * @param string $rawContent raw contents of a page
* @return string contents prepared for parsing * @return string contents prepared for parsing
*/ */
@ -795,6 +817,8 @@ class Pico
/** /**
* Parses the contents of a page using ParsedownExtra * Parses the contents of a page using ParsedownExtra
* *
* @see Pico::prepareFileContent()
* @see Pico::getFileContent()
* @param string $content raw contents of a page (Markdown) * @param string $content raw contents of a page (Markdown)
* @return string parsed contents (HTML) * @return string parsed contents (HTML)
*/ */
@ -807,6 +831,7 @@ class Pico
/** /**
* Returns the cached contents of the requested page * Returns the cached contents of the requested page
* *
* @see Pico::prepareFileContent()
* @see Pico::parseFileContent() * @see Pico::parseFileContent()
* @return string|null parsed contents * @return string|null parsed contents
*/ */
@ -834,6 +859,8 @@ class Pico
* | meta | parsed meta data of the page) | * | meta | parsed meta data of the page) |
* +----------------+------------------------------------------+ * +----------------+------------------------------------------+
* *
* @see Pico::sortPages()
* @see Pico::getPages()
* @return void * @return void
*/ */
protected function readPages() protected function readPages()
@ -896,6 +923,8 @@ class Pico
/** /**
* Sorts all pages known to Pico * Sorts all pages known to Pico
* *
* @see Pico::readPages()
* @see Pico::getPages()
* @return void * @return void
*/ */
protected function sortPages() protected function sortPages()
@ -936,6 +965,7 @@ class Pico
* Returns the list of known pages * Returns the list of known pages
* *
* @see Pico::readPages() * @see Pico::readPages()
* @see Pico::sortPages()
* @return array|null the data of all pages * @return array|null the data of all pages
*/ */
public function getPages() public function getPages()
@ -947,6 +977,9 @@ class Pico
* Walks through the list of known pages and discovers the requested page * Walks through the list of known pages and discovers the requested page
* as well as the previous and next page relative to it * as well as the previous and next page relative to it
* *
* @see Pico::getCurrentPage()
* @see Pico::getPreviousPage()
* @see Pico::getNextPage()
* @return void * @return void
*/ */
protected function discoverCurrentPage() protected function discoverCurrentPage()
@ -1016,6 +1049,7 @@ class Pico
/** /**
* Registers the twig template engine * Registers the twig template engine
* *
* @see Pico::getTwig()
* @return void * @return void
*/ */
protected function registerTwig() protected function registerTwig()
@ -1029,6 +1063,7 @@ class Pico
/** /**
* Returns the twig template engine * Returns the twig template engine
* *
* @see Pico::registerTwig()
* @return Twig_Environment|null twig template engine * @return Twig_Environment|null twig template engine
*/ */
public function getTwig() public function getTwig()
@ -1039,8 +1074,8 @@ class Pico
/** /**
* Returns the variables passed to the template * Returns the variables passed to the template
* *
* URLs and paths (namely base_dir, base_url, theme_dir and theme_url) * URLs and paths (namely `base_dir`, `base_url`, `theme_dir` and
* don't add a trailing slash for historic reasons. * `theme_url`) don't add a trailing slash for historic reasons.
* *
* @return mixed[] template variables * @return mixed[] template variables
*/ */
@ -1179,11 +1214,14 @@ class Pico
} }
/** /**
* Triggers events on plugins which implement {@link PicoPluginInterface} * Triggers events on plugins which implement PicoPluginInterface
* *
* Deprecated events (as used by plugins not implementing * Deprecated events (as used by plugins not implementing
* {@link IPocPlugin}) are triggered by {@link PicoDeprecated}. * {@link IPocPlugin}) are triggered by {@link PicoDeprecated}.
* *
* @see PicoPluginInterface
* @see AbstractPicoPlugin
* @see DummyPlugin
* @param string $eventName name of the event to trigger * @param string $eventName name of the event to trigger
* @param array $params optional parameters to pass * @param array $params optional parameters to pass
* @return void * @return void

9
lib/PicoPluginInterface.php
View File

@ -14,11 +14,11 @@
* plugins are loaded. Consequently the old events are never triggered when * plugins are loaded. Consequently the old events are never triggered when
* your plugin is implementing this interface and no old plugins are present. * your plugin is implementing this interface and no old plugins are present.
* *
* If you're developing a new plugin, you MUST implement PicoPluginInterface. If * If you're developing a new plugin, you MUST implement this interface. If
* you're the developer of an old plugin, it is STRONGLY RECOMMENDED to use * you're the developer of an old plugin, it is STRONGLY RECOMMENDED to use
* the events introduced in Pico 1.0 when releasing a new version of your * the events introduced in Pico 1.0 when releasing a new version of your
* plugin. If you want to use any of the new events, you MUST implement * plugin. If you want to use any of the new events, you MUST implement
* PicoPluginInterface and update all other events you use. * this interface and update all other events you use.
* *
* @author Daniel Rudolf * @author Daniel Rudolf
* @link http://picocms.org * @link http://picocms.org
@ -46,6 +46,8 @@ interface PicoPluginInterface
/** /**
* Enables or disables this plugin * Enables or disables this plugin
* *
* @see PicoPluginInterface::isEnabled()
* @see PicoPluginInterface::isStatusChanged()
* @param boolean $enabled enable (true) or disable (false) this plugin * @param boolean $enabled enable (true) or disable (false) this plugin
* @param boolean $recursive when true, enable or disable recursively * @param boolean $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
@ -63,6 +65,7 @@ interface PicoPluginInterface
/** /**
* 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) * @return boolean plugin is enabled (true) or disabled (false)
*/ */
public function isEnabled(); public function isEnabled();
@ -70,6 +73,7 @@ interface PicoPluginInterface
/** /**
* 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 * @return boolean plugin is in its default state (true), false otherwise
*/ */
public function isStatusChanged(); public function isStatusChanged();
@ -91,6 +95,7 @@ interface PicoPluginInterface
/** /**
* Returns the plugins instance of Pico * Returns the plugins instance of Pico
* *
* @see Pico
* @return Pico the plugins instance of Pico * @return Pico the plugins instance of Pico
*/ */
public function getPico(); public function getPico();

35
plugins/00-PicoDeprecated.php
View File

@ -54,8 +54,8 @@ class PicoDeprecated extends AbstractPicoPlugin
/** /**
* The requested file * The requested file
* *
* @see PicoDeprecated::getRequestFile()
* @var string|null * @var string|null
* @see PicoDeprecated::onRequestFile()
*/ */
protected $requestFile; protected $requestFile;
@ -103,11 +103,12 @@ class PicoDeprecated extends AbstractPicoPlugin
/** /**
* Defines deprecated constants * Defines deprecated constants
* *
* CONTENT_DIR is deprecated since v0.9, ROOT_DIR, LIB_DIR, PLUGINS_DIR, * `CONTENT_DIR` is deprecated since v0.9, `ROOT_DIR`, `LIB_DIR`,
* THEMES_DIR and CONTENT_EXT since v1.0, CONFIG_DIR existed just for a * `PLUGINS_DIR`, `THEMES_DIR` and `CONTENT_EXT` since v1.0, `CONFIG_DIR`
* short time between v0.9 and v1.0 and CACHE_DIR was dropped with v1.0 * existed just for a short time between v0.9 and v1.0 and `CACHE_DIR`
* without a replacement. * was dropped with v1.0 without a replacement.
* *
* @see PicoDeprecated::onConfigLoaded()
* @return void * @return void
*/ */
protected function defineConstants() protected function defineConstants()
@ -137,8 +138,10 @@ class PicoDeprecated extends AbstractPicoPlugin
} }
/** /**
* Read {@path "config.php"} in Picos root dir * Read config.php in Picos root dir
* *
* @see PicoDeprecated::onConfigLoaded()
* @see Pico::loadConfig()
* @param mixed[] &$config array of config variables * @param mixed[] &$config array of config variables
* @return void * @return void
*/ */
@ -154,8 +157,10 @@ class PicoDeprecated extends AbstractPicoPlugin
} }
/** /**
* Enables the plugins {@link PicoParsePagesContent} and {@link PicoExcerpt} * Enables the plugins PicoParsePagesContent and PicoExcerpt
* *
* @see PicoParsePagesContent
* @see PicoExcerpt
* @return void * @return void
*/ */
protected function enablePlugins() protected function enablePlugins()
@ -190,9 +195,11 @@ class PicoDeprecated extends AbstractPicoPlugin
} }
/** /**
* Sets {@link PicoDeprecated::$requestFile} to trigger the deprecated * Sets PicoDeprecated::$requestFile to trigger the deprecated
* events after_load_content() and after_404_load_content() * events after_load_content() and after_404_load_content()
* *
* @see PicoDeprecated::onContentLoaded()
* @see PicoDeprecated::on404ContentLoaded()
* @see DummyPlugin::onRequestFile() * @see DummyPlugin::onRequestFile()
*/ */
public function onRequestFile(&$file) public function onRequestFile(&$file)
@ -298,6 +305,11 @@ class PicoDeprecated extends AbstractPicoPlugin
* Triggers the deprecated event * Triggers the deprecated event
* get_pages($pages, $currentPage, $previousPage, $nextPage) * get_pages($pages, $currentPage, $previousPage, $nextPage)
* *
* Please note that the `get_pages()` event gets `$pages` passed without a
* array index. The index is rebuild later using either the `id` array key
* or is derived from the `url` array key. Duplicates are prevented by
* adding `~dup` when necessary.
*
* @see DummyPlugin::onPagesLoaded() * @see DummyPlugin::onPagesLoaded()
*/ */
public function onPagesLoaded(&$pages, &$currentPage, &$previousPage, &$nextPage) public function onPagesLoaded(&$pages, &$currentPage, &$previousPage, &$nextPage)
@ -342,6 +354,9 @@ class PicoDeprecated extends AbstractPicoPlugin
/** /**
* Triggers the deprecated event before_render($twigVariables, $twig, $templateName) * Triggers the deprecated event before_render($twigVariables, $twig, $templateName)
* *
* Please note that the `before_render()` event gets `$templateName` passed
* without its file extension. The file extension is later added again.
*
* @see DummyPlugin::onPageRendering() * @see DummyPlugin::onPageRendering()
*/ */
public function onPageRendering(&$twig, &$twigVariables, &$templateName) public function onPageRendering(&$twig, &$twigVariables, &$templateName)
@ -372,6 +387,10 @@ class PicoDeprecated extends AbstractPicoPlugin
/** /**
* Triggers a deprecated event on all plugins * Triggers a deprecated event on all plugins
* *
* Deprecated events are also triggered on plugins which implement
* {@link PicoPluginInterface}. Please note that the methods are called
* directly and not through {@link PicoPluginInterface::handleEvent()}.
*
* @param string $eventName event to trigger * @param string $eventName event to trigger
* @param array $params parameters to pass * @param array $params parameters to pass
* @return void * @return void

6
plugins/02-PicoExcerpt.php
View File

@ -11,7 +11,7 @@
* {@link PicoParsePagesContent}, what heavily impacts Picos performance. You * {@link PicoParsePagesContent}, what heavily impacts Picos performance. You
* should either use the Description meta header field or write something own. * should either use the Description meta header field or write something own.
* Best solution seems to be a filter for twig, see e.g. * Best solution seems to be a filter for twig, see e.g.
* <https://gist.github.com/james2doyle/6629712>. * {@link https://gist.github.com/james2doyle/6629712}.
* *
* @author Daniel Rudolf * @author Daniel Rudolf
* @link http://picocms.org * @link http://picocms.org
@ -28,8 +28,9 @@ class PicoExcerpt extends AbstractPicoPlugin
protected $enabled = false; protected $enabled = false;
/** /**
* This plugin depends on {@link PicoParsePagesContent} * This plugin depends on PicoParsePagesContent
* *
* @see PicoParsePagesContent
* @see AbstractPicoPlugin::$dependsOn * @see AbstractPicoPlugin::$dependsOn
*/ */
protected $dependsOn = array('PicoParsePagesContent'); protected $dependsOn = array('PicoParsePagesContent');
@ -49,6 +50,7 @@ class PicoExcerpt extends AbstractPicoPlugin
/** /**
* Creates a excerpt for the contents of each page * Creates a excerpt for the contents of each page
* *
* @see PicoExcerpt::createExcerpt()
* @see DummyPlugin::onSinglePageLoaded() * @see DummyPlugin::onSinglePageLoaded()
*/ */
public function onSinglePageLoaded(&$pageData) public function onSinglePageLoaded(&$pageData)

31
plugins/DummyPlugin.php
View File

@ -16,16 +16,16 @@ class DummyPlugin extends AbstractPicoPlugin
/** /**
* This plugin is enabled by default? * This plugin is enabled by default?
* *
* @var boolean
* @see AbstractPicoPlugin::$enabled * @see AbstractPicoPlugin::$enabled
* @var boolean
*/ */
protected $enabled = false; protected $enabled = false;
/** /**
* This plugin depends on {@link ...} * This plugin depends on ...
* *
* @var string[]
* @see AbstractPicoPlugin::$dependsOn * @see AbstractPicoPlugin::$dependsOn
* @var string[]
*/ */
protected $dependsOn = array(); protected $dependsOn = array();
@ -60,7 +60,6 @@ class DummyPlugin extends AbstractPicoPlugin
/** /**
* Triggered after Pico has evaluated the request URL * Triggered after Pico has evaluated the request URL
* *
* @see Pico::getBaseUrl()
* @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
@ -73,6 +72,7 @@ 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::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
@ -86,6 +86,7 @@ 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()
* @param string &$file path to the file which contents will be read * @param string &$file path to the file which contents will be read
* @return void * @return void
*/ */
@ -107,9 +108,10 @@ class DummyPlugin extends AbstractPicoPlugin
} }
/** /**
* Triggered before Pico reads the contents of the 404 file * Triggered before Pico reads the contents of a 404 file
* *
* @see Pico::load404Content() * @see Pico::load404Content()
* @see DummyPlugin::on404ContentLoaded()
* @param string &$file path to the file which contents were requested * @param string &$file path to the file which contents were requested
* @return void * @return void
*/ */
@ -148,6 +150,7 @@ 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()
* @param string &$rawContent raw file contents * @param string &$rawContent raw file contents
* @param string[] &$headers known meta header fields * @param string[] &$headers known meta header fields
* @return void * @return void
@ -173,6 +176,8 @@ 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::onContentParsed()
* @param string &$rawContent raw file contents * @param string &$rawContent raw file contents
* @return void * @return void
*/ */
@ -185,6 +190,7 @@ 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()
* @param string &$content prepared file contents for parsing * @param string &$content prepared file contents for parsing
* @return void * @return void
*/ */
@ -205,9 +211,23 @@ class DummyPlugin extends AbstractPicoPlugin
// your code // your code
} }
/**
* Triggered before Pico reads all known pages
*
* @see Pico::readPages()
* @see DummyPlugin::onSinglePageLoaded()
* @see DummyPlugin::onPagesLoaded()
* @return void
*/
public function onPagesLoading()
{
// your code
}
/** /**
* Triggered when Pico reads a single page from the list of all known pages * Triggered when Pico reads a single page from the list of all known pages
* *
* @see DummyPlugin::onPagesLoaded()
* @param array &$pageData { * @param array &$pageData {
* data of the loaded page * data of the loaded page
* *
@ -264,6 +284,7 @@ class DummyPlugin extends AbstractPicoPlugin
* Triggered before Pico renders the page * Triggered before Pico renders the page
* *
* @see Pico::getTwig() * @see Pico::getTwig()
* @see DummyPlugin::onPageRendered()
* @param Twig_Environment &$twig twig template engine * @param Twig_Environment &$twig twig template engine
* @param mixed[] &$twigVariables template variables * @param mixed[] &$twigVariables template variables
* @param string &$templateName file name of the template * @param string &$templateName file name of the template