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

Improve inline code comments; preparing use of phpDocumentor

Browse Source
This commit is contained in:
Daniel Rudolf 2015-10-27 01:39:28 +01:00
parent 4171f9a031
commit 92af554d14
4 changed files with 95 additions and 50 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
lib/AbstractPicoPlugin.php
View File

@ -50,7 +50,7 @@ abstract class AbstractPicoPlugin implements PicoPluginInterface
/** /**
* List of plugin which depend on this plugin * List of plugin which depend on this plugin
* *
* @var array<object> * @var array<string, object>
* @see PicoPluginInterface::getDependants() * @see PicoPluginInterface::getDependants()
* @see AbstractPicoPlugin::checkDependants() * @see AbstractPicoPlugin::checkDependants()
*/ */

94
lib/Pico.php
View File

@ -89,7 +89,7 @@ class Pico
* List of loaded plugins * List of loaded plugins
* *
* @see Pico::loadPlugins() * @see Pico::loadPlugins()
* @var array<object> * @var array<object>|null
*/ */
protected $plugins; protected $plugins;
@ -97,23 +97,23 @@ class Pico
* Current configuration of this Pico instance * Current configuration of this Pico instance
* *
* @see Pico::loadConfig() * @see Pico::loadConfig()
* @var array * @var array<string, mixed>|null
*/ */
protected $config; protected $config;
/** /**
* URL with which the user requested the page * Part of the URL describing the requested contents
* *
* @see Pico::evaluateRequestUrl() * @see Pico::evaluateRequestUrl()
* @var string * @var string|null
*/ */
protected $requestUrl; protected $requestUrl;
/** /**
* Path to the content file being served * Absolute path to the content file being served
* *
* @see Pico::discoverRequestFile() * @see Pico::discoverRequestFile()
* @var string * @var string|null
*/ */
protected $requestFile; protected $requestFile;
@ -121,7 +121,7 @@ class Pico
* Raw, not yet parsed contents to serve * Raw, not yet parsed contents to serve
* *
* @see Pico::loadFileContent() * @see Pico::loadFileContent()
* @var string * @var string|null
*/ */
protected $rawContent; protected $rawContent;
@ -129,7 +129,7 @@ class Pico
* Meta data of the page to serve * Meta data of the page to serve
* *
* @see Pico::parseFileMeta() * @see Pico::parseFileMeta()
* @var array * @var array<string, string>|null
*/ */
protected $meta; protected $meta;
@ -138,7 +138,7 @@ class Pico
* *
* @see Pico::prepareFileContent() * @see Pico::prepareFileContent()
* @see Pico::parseFileContent() * @see Pico::parseFileContent()
* @var string * @var string|null
*/ */
protected $content; protected $content;
@ -146,7 +146,7 @@ class Pico
* List of known pages * List of known pages
* *
* @see Pico::readPages() * @see Pico::readPages()
* @var array * @var array<array>|null
*/ */
protected $pages; protected $pages;
@ -154,7 +154,7 @@ class Pico
* Data of the page being served * Data of the page being served
* *
* @see Pico::discoverCurrentPage() * @see Pico::discoverCurrentPage()
* @var array * @var array|null
*/ */
protected $currentPage; protected $currentPage;
@ -162,7 +162,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::discoverCurrentPage()
* @var array * @var array|null
*/ */
protected $previousPage; protected $previousPage;
@ -170,7 +170,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::discoverCurrentPage()
* @var array * @var array|null
*/ */
protected $nextPage; protected $nextPage;
@ -178,14 +178,14 @@ class Pico
* Twig instance used for template parsing * Twig instance used for template parsing
* *
* @see Pico::registerTwig() * @see Pico::registerTwig()
* @var Twig_Environment * @var Twig_Environment|null
*/ */
protected $twig; protected $twig;
/** /**
* Variables passed to the twig template * Variables passed to the twig template
* *
* @var array * @var array<string, mixed>|null
*/ */
protected $twigVariables; protected $twigVariables;
@ -193,6 +193,11 @@ 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 the run() method.
*
* @param string $rootDir root directory of this Pico instance
* @param string $configDir config directory of this Pico instance
* @param string $pluginsDir plugins directory of this Pico instance
* @param string $themesDir themes directory of this Pico instance
*/ */
public function __construct($rootDir, $configDir, $pluginsDir, $themesDir) public function __construct($rootDir, $configDir, $pluginsDir, $themesDir)
{ {
@ -398,7 +403,7 @@ class Pico
* Returns all loaded plugins * Returns all loaded plugins
* *
* @see Pico::loadPlugins() * @see Pico::loadPlugins()
* @return array<object> * @return array<object>|null
*/ */
public function getPlugins() public function getPlugins()
{ {
@ -458,10 +463,11 @@ class Pico
* call and Pico::run(). Options set with this method cannot be overwritten * call and Pico::run(). Options set with this method cannot be overwritten
* by {@path "config/config.php"}. * by {@path "config/config.php"}.
* *
* @param array $config array with configuration variables, like * @param array<string, mixed> $config array with configuration variables,
* $config in {@path "config/config.php"} * like $config in {@path "config/config.php"}
* @return void * @return void
* @throws RuntimeException thrown if Pico already started processing * @throws RuntimeException thrown if Pico already started
* processing
*/ */
public function setConfig(array $config) public function setConfig(array $config)
{ {
@ -534,7 +540,7 @@ class Pico
* Returns the URL where a user requested the page * Returns the URL where a user requested the page
* *
* @see Pico::evaluateRequestUrl() * @see Pico::evaluateRequestUrl()
* @return string request URL * @return string|null request URL
*/ */
public function getRequestUrl() public function getRequestUrl()
{ {
@ -567,10 +573,10 @@ class Pico
} }
/** /**
* Returns the path to the content file to serve * Returns the absolute path to the content file to serve
* *
* @see Pico::discoverRequestFile() * @see Pico::discoverRequestFile()
* @return string file path * @return string|null file path
*/ */
public function getRequestFile() public function getRequestFile()
{ {
@ -616,7 +622,7 @@ class Pico
* Returns the cached raw contents, either of the requested or the 404 file * Returns the cached raw contents, either of the requested or the 404 file
* *
* @see Pico::loadFileContent() * @see Pico::loadFileContent()
* @return string raw contents * @return string|null raw contents
*/ */
public function getRawContent() public function getRawContent()
{ {
@ -629,7 +635,9 @@ class Pico
* Heads up! Calling this method triggers the `onMetaHeaders` event. * Heads up! Calling this method triggers the `onMetaHeaders` event.
* Keep this in mind to prevent a infinite loop! * Keep this in mind to prevent a infinite loop!
* *
* @return array known meta headers * @return array<string, string> known meta headers; the array value
* specifies the YAML key to search for, the array key is later used
* to access the found value
*/ */
public function getMetaHeaders() public function getMetaHeaders()
{ {
@ -657,9 +665,9 @@ class Pico
* for users and pure (!) theme developers ONLY. * for users and pure (!) theme developers ONLY.
* *
* @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 array $headers a array containing the known headers * @param array<string, string> $headers known meta headers
* @return array parsed meta data * @return array parsed meta data
*/ */
public function parseFileMeta($rawContent, array $headers) public function parseFileMeta($rawContent, array $headers)
{ {
@ -707,7 +715,7 @@ class Pico
* Returns the parsed meta data of the requested page * Returns the parsed meta data of the requested page
* *
* @see Pico::parseFileMeta() * @see Pico::parseFileMeta()
* @return array parsed meta data * @return array|null parsed meta data
*/ */
public function getFileMeta() public function getFileMeta()
{ {
@ -772,7 +780,7 @@ class Pico
* Returns the cached contents of the requested page * Returns the cached contents of the requested page
* *
* @see Pico::parseFileContent() * @see Pico::parseFileContent()
* @return string parsed contents * @return string|null parsed contents
*/ */
public function getFileContent() public function getFileContent()
{ {
@ -782,6 +790,22 @@ class Pico
/** /**
* Reads the data of all pages known to Pico * Reads the data of all pages known to Pico
* *
* The page data will be an array containing the following values:
* +----------------+------------------------------------------+
* | Array key | Description |
* +----------------+------------------------------------------+
* | id | relative path to the content file |
* | url | URL to the page |
* | title | title of the page (YAML header) |
* | description | description of the page (YAML header) |
* | author | author of the page (YAML header) |
* | time | timestamp derived from the Date header |
* | date | date of the page (YAML header) |
* | date_formatted | formatted date of the page |
* | raw_content | raw, not yet parsed contents of the page |
* | meta | parsed meta data of the page) |
* +----------------+------------------------------------------+
*
* @return void * @return void
*/ */
protected function readPages() protected function readPages()
@ -884,7 +908,7 @@ class Pico
* Returns the list of known pages * Returns the list of known pages
* *
* @see Pico::readPages() * @see Pico::readPages()
* @return array the data of all pages * @return array|null the data of all pages
*/ */
public function getPages() public function getPages()
{ {
@ -932,7 +956,7 @@ class Pico
* Returns the data of the requested page * Returns the data of the requested page
* *
* @see Pico::discoverCurrentPage() * @see Pico::discoverCurrentPage()
* @return array page data * @return array|null page data
*/ */
public function getCurrentPage() public function getCurrentPage()
{ {
@ -943,7 +967,7 @@ class Pico
* Returns the data of the previous page relative to the page being served * Returns the data of the previous page relative to the page being served
* *
* @see Pico::discoverCurrentPage() * @see Pico::discoverCurrentPage()
* @return array page data * @return array|null page data
*/ */
public function getPreviousPage() public function getPreviousPage()
{ {
@ -954,7 +978,7 @@ class Pico
* Returns the data of the next page relative to the page being served * Returns the data of the next page relative to the page being served
* *
* @see Pico::discoverCurrentPage() * @see Pico::discoverCurrentPage()
* @return array page data * @return array|null page data
*/ */
public function getNextPage() public function getNextPage()
{ {
@ -977,7 +1001,7 @@ class Pico
/** /**
* Returns the twig template engine * Returns the twig template engine
* *
* @return Twig_Environment twig template engine * @return Twig_Environment|null twig template engine
*/ */
public function getTwig() public function getTwig()
{ {
@ -990,7 +1014,7 @@ class Pico
* URLs and paths (namely base_dir, base_url, theme_dir and theme_url) * URLs and paths (namely base_dir, base_url, theme_dir and theme_url)
* don't add a trailing slash for historic reasons. * don't add a trailing slash for historic reasons.
* *
* @return array template variables * @return array<string, mixed> template variables
*/ */
protected function getTwigVariables() protected function getTwigVariables()
{ {

7
plugins/00-PicoDeprecated.php
View File

@ -54,7 +54,7 @@ class PicoDeprecated extends AbstractPicoPlugin
/** /**
* The requested file * The requested file
* *
* @var string * @var string|null
* @see PicoDeprecated::onRequestFile() * @see PicoDeprecated::onRequestFile()
*/ */
protected $requestFile; protected $requestFile;
@ -139,7 +139,7 @@ class PicoDeprecated extends AbstractPicoPlugin
/** /**
* Read {@path "config.php"} in Picos root dir * Read {@path "config.php"} in Picos root dir
* *
* @param array &$config array of config variables * @param array<string, mixed> &$config array of config variables
* @return void * @return void
*/ */
protected function loadRootDirConfig(&$config) protected function loadRootDirConfig(&$config)
@ -295,7 +295,8 @@ class PicoDeprecated extends AbstractPicoPlugin
} }
/** /**
* Triggers the deprecated event get_pages($pages, $currentPage, $previousPage, $nextPage) * Triggers the deprecated event
* get_pages($pages, $currentPage, $previousPage, $nextPage)
* *
* @see DummyPlugin::onPagesLoaded() * @see DummyPlugin::onPagesLoaded()
*/ */

42
plugins/DummyPlugin.php
View File

@ -16,6 +16,7 @@ class DummyPlugin extends AbstractPicoPlugin
/** /**
* This plugin is enabled by default? * This plugin is enabled by default?
* *
* @var boolean
* @see AbstractPicoPlugin::$enabled * @see AbstractPicoPlugin::$enabled
*/ */
protected $enabled = false; protected $enabled = false;
@ -23,6 +24,7 @@ class DummyPlugin extends AbstractPicoPlugin
/** /**
* This plugin depends on {@link ...} * This plugin depends on {@link ...}
* *
* @var array<string>
* @see AbstractPicoPlugin::$dependsOn * @see AbstractPicoPlugin::$dependsOn
*/ */
protected $dependsOn = array(); protected $dependsOn = array();
@ -47,7 +49,7 @@ class DummyPlugin extends AbstractPicoPlugin
* Triggered after Pico has read its configuration * Triggered after Pico has read its configuration
* *
* @see Pico::getConfig() * @see Pico::getConfig()
* @param array &$config array of config variables * @param array<string, mixed> &$config array of config variables
* @return void * @return void
*/ */
public function onConfigLoaded(&$config) public function onConfigLoaded(&$config)
@ -60,7 +62,7 @@ class DummyPlugin extends AbstractPicoPlugin
* *
* @see Pico::getBaseUrl() * @see Pico::getBaseUrl()
* @see Pico::getRequestUrl() * @see Pico::getRequestUrl()
* @param string &$url request URL * @param string &$url part of the URL describing the requested contents
* @return void * @return void
*/ */
public function onRequestUrl(&$url) public function onRequestUrl(&$url)
@ -72,7 +74,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::getRequestFile() * @see Pico::getRequestFile()
* @param string &$file path to the content file to serve * @param string &$file absolute path to the content file to serve
* @return void * @return void
*/ */
public function onRequestFile(&$file) public function onRequestFile(&$file)
@ -132,7 +134,9 @@ class DummyPlugin extends AbstractPicoPlugin
* Triggered when Pico reads its known meta header fields * Triggered when Pico reads its known meta header fields
* *
* @see Pico::getMetaHeaders() * @see Pico::getMetaHeaders()
* @param array<string> &$headers list of known meta header fields * @param array<string, string> &$headers list of known meta header
* fields; the array value specifies the YAML key to search for, the
* array key is later used to access the found value
* @return void * @return void
*/ */
public function onMetaHeaders(&$headers) public function onMetaHeaders(&$headers)
@ -144,8 +148,8 @@ class DummyPlugin extends AbstractPicoPlugin
* Triggered before Pico parses the meta header * Triggered before Pico parses the meta header
* *
* @see Pico::parseFileMeta() * @see Pico::parseFileMeta()
* @param string &$rawContent raw file contents * @param string &$rawContent raw file contents
* @param array &$headers known meta header fields * @param array<string, string> &$headers known meta header fields
* @return void * @return void
*/ */
public function onMetaParsing(&$rawContent, &$headers) public function onMetaParsing(&$rawContent, &$headers)
@ -157,7 +161,7 @@ class DummyPlugin extends AbstractPicoPlugin
* Triggered after Pico has parsed the meta header * Triggered after Pico has parsed the meta header
* *
* @see Pico::getFileMeta() * @see Pico::getFileMeta()
* @param array &$meta parsed meta data * @param array<string, string> &$meta parsed meta data
* @return void * @return void
*/ */
public function onMetaParsed(&$meta) public function onMetaParsed(&$meta)
@ -204,7 +208,20 @@ class DummyPlugin extends AbstractPicoPlugin
/** /**
* 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
* *
* @param array &$pageData data of the loaded page * @param array &$pageData {
* data of the loaded page
*
* @var string $id relative path to the content file
* @var string $url URL to the page
* @var string $title title of the page (YAML header)
* @var string $description description of the page (YAML header)
* @var string $author author of the page (YAML header)
* @var string $time timestamp derived from the Date header
* @var string $date date of the page (YAML header)
* @var string $date_formatted formatted date of the page
* @var string $raw_content raw, not yet parsed contents of the page
* @var string $meta parsed meta data of the page
* }
* @return void * @return void
*/ */
public function onSinglePageLoaded(&$pageData) public function onSinglePageLoaded(&$pageData)
@ -215,6 +232,9 @@ class DummyPlugin extends AbstractPicoPlugin
/** /**
* Triggered after Pico has read all known pages * Triggered after Pico has read all known pages
* *
* See {@link DummyPlugin::onSinglePageLoaded()} for details about the
* structure of the page data.
*
* @see Pico::getPages() * @see Pico::getPages()
* @see Pico::getCurrentPage() * @see Pico::getCurrentPage()
* @see Pico::getPreviousPage() * @see Pico::getPreviousPage()
@ -244,9 +264,9 @@ class DummyPlugin extends AbstractPicoPlugin
* Triggered before Pico renders the page * Triggered before Pico renders the page
* *
* @see Pico::getTwig() * @see Pico::getTwig()
* @param Twig_Environment &$twig twig template engine * @param Twig_Environment &$twig twig template engine
* @param array &$twigVariables variables passed to the template * @param array<string, mixed> &$twigVariables template variables
* @param string &$templateName name of the template to render * @param string &$templateName file name of the template
* @return void * @return void
*/ */
public function onPageRendering(&$twig, &$twigVariables, &$templateName) public function onPageRendering(&$twig, &$twigVariables, &$templateName)