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

Improve inline code comments; preparing use of phpDocumentor

Browse Source
pico-3.0-alpha
Daniel Rudolf 10 years ago
parent 4171f9a031
commit 92af554d14
4 changed files with 95 additions and 50 deletions
Show all changes Ignore whitespace when comparing lines Ignore changes in amount of whitespace Ignore changes in whitespace at EOL
Show Stats Download Patch File Download Diff File
  1. 2
      lib/AbstractPicoPlugin.php
  2. 94
      lib/Pico.php
  3. 7
      plugins/00-PicoDeprecated.php
  4. 42
      plugins/DummyPlugin.php

2
lib/AbstractPicoPlugin.php
Unescape View File

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

94
lib/Pico.php
Unescape View File

@ -89,7 +89,7 @@ class Pico
* List of loaded plugins
*
* @see Pico::loadPlugins()
* @var array<object>
* @var array<object>|null
*/
protected $plugins;
@ -97,23 +97,23 @@ class Pico
* Current configuration of this Pico instance
*
* @see Pico::loadConfig()
* @var array
* @var array<string, mixed>|null
*/
protected $config;
/**
* URL with which the user requested the page
* Part of the URL describing the requested contents
*
* @see Pico::evaluateRequestUrl()
* @var string
* @var string|null
*/
protected $requestUrl;
/**
* Path to the content file being served
* Absolute path to the content file being served
*
* @see Pico::discoverRequestFile()
* @var string
* @var string|null
*/
protected $requestFile;
@ -121,7 +121,7 @@ class Pico
* Raw, not yet parsed contents to serve
*
* @see Pico::loadFileContent()
* @var string
* @var string|null
*/
protected $rawContent;
@ -129,7 +129,7 @@ class Pico
* Meta data of the page to serve
*
* @see Pico::parseFileMeta()
* @var array
* @var array<string, string>|null
*/
protected $meta;
@ -138,7 +138,7 @@ class Pico
*
* @see Pico::prepareFileContent()
* @see Pico::parseFileContent()
* @var string
* @var string|null
*/
protected $content;
@ -146,7 +146,7 @@ class Pico
* List of known pages
*
* @see Pico::readPages()
* @var array
* @var array<array>|null
*/
protected $pages;
@ -154,7 +154,7 @@ class Pico
* Data of the page being served
*
* @see Pico::discoverCurrentPage()
* @var array
* @var array|null
*/
protected $currentPage;
@ -162,7 +162,7 @@ class Pico
* Data of the previous page relative to the page being served
*
* @see Pico::discoverCurrentPage()
* @var array
* @var array|null
*/
protected $previousPage;
@ -170,7 +170,7 @@ class Pico
* Data of the next page relative to the page being served
*
* @see Pico::discoverCurrentPage()
* @var array
* @var array|null
*/
protected $nextPage;
@ -178,14 +178,14 @@ class Pico
* Twig instance used for template parsing
*
* @see Pico::registerTwig()
* @var Twig_Environment
* @var Twig_Environment|null
*/
protected $twig;
/**
* Variables passed to the twig template
*
* @var array
* @var array<string, mixed>|null
*/
protected $twigVariables;
@ -193,6 +193,11 @@ class Pico
* Constructs a new Pico instance
*
* 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)
{
@ -398,7 +403,7 @@ class Pico
* Returns all loaded plugins
*
* @see Pico::loadPlugins()
* @return array<object>
* @return array<object>|null
*/
public function getPlugins()
{
@ -458,10 +463,11 @@ class Pico
* call and Pico::run(). Options set with this method cannot be overwritten
* by {@path "config/config.php"}.
*
* @param array $config array with configuration variables, like
* $config in {@path "config/config.php"}
* @param array<string, mixed> $config array with configuration variables,
* like $config in {@path "config/config.php"}
* @return void
* @throws RuntimeException thrown if Pico already started processing
* @throws RuntimeException thrown if Pico already started
* processing
*/
public function setConfig(array $config)
{
@ -534,7 +540,7 @@ class Pico
* Returns the URL where a user requested the page
*
* @see Pico::evaluateRequestUrl()
* @return string request URL
* @return string|null request URL
*/
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()
* @return string file path
* @return string|null file path
*/
public function getRequestFile()
{
@ -616,7 +622,7 @@ class Pico
* Returns the cached raw contents, either of the requested or the 404 file
*
* @see Pico::loadFileContent()
* @return string raw contents
* @return string|null raw contents
*/
public function getRawContent()
{
@ -629,7 +635,9 @@ class Pico
* Heads up! Calling this method triggers the `onMetaHeaders` event.
* 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()
{
@ -657,9 +665,9 @@ class Pico
* for users and pure (!) theme developers ONLY.
*
* @see <http://symfony.com/doc/current/components/yaml/introduction.html>
* @param string $rawContent the raw file contents
* @param array $headers a array containing the known headers
* @return array parsed meta data
* @param string $rawContent the raw file contents
* @param array<string, string> $headers known meta headers
* @return array parsed meta data
*/
public function parseFileMeta($rawContent, array $headers)
{
@ -707,7 +715,7 @@ class Pico
* Returns the parsed meta data of the requested page
*
* @see Pico::parseFileMeta()
* @return array parsed meta data
* @return array|null parsed meta data
*/
public function getFileMeta()
{
@ -772,7 +780,7 @@ class Pico
* Returns the cached contents of the requested page
*
* @see Pico::parseFileContent()
* @return string parsed contents
* @return string|null parsed contents
*/
public function getFileContent()
{
@ -782,6 +790,22 @@ class 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
*/
protected function readPages()
@ -884,7 +908,7 @@ class Pico
* Returns the list of known pages
*
* @see Pico::readPages()
* @return array the data of all pages
* @return array|null the data of all pages
*/
public function getPages()
{
@ -932,7 +956,7 @@ class Pico
* Returns the data of the requested page
*
* @see Pico::discoverCurrentPage()
* @return array page data
* @return array|null page data
*/
public function getCurrentPage()
{
@ -943,7 +967,7 @@ class Pico
* Returns the data of the previous page relative to the page being served
*
* @see Pico::discoverCurrentPage()
* @return array page data
* @return array|null page data
*/
public function getPreviousPage()
{
@ -954,7 +978,7 @@ class Pico
* Returns the data of the next page relative to the page being served
*
* @see Pico::discoverCurrentPage()
* @return array page data
* @return array|null page data
*/
public function getNextPage()
{
@ -977,7 +1001,7 @@ class Pico
/**
* Returns the twig template engine
*
* @return Twig_Environment twig template engine
* @return Twig_Environment|null twig template engine
*/
public function getTwig()
{
@ -990,7 +1014,7 @@ class Pico
* URLs and paths (namely base_dir, base_url, theme_dir and theme_url)
* don't add a trailing slash for historic reasons.
*
* @return array template variables
* @return array<string, mixed> template variables
*/
protected function getTwigVariables()
{

7
plugins/00-PicoDeprecated.php
Unescape View File

@ -54,7 +54,7 @@ class PicoDeprecated extends AbstractPicoPlugin
/**
* The requested file
*
* @var string
* @var string|null
* @see PicoDeprecated::onRequestFile()
*/
protected $requestFile;
@ -139,7 +139,7 @@ class PicoDeprecated extends AbstractPicoPlugin
/**
* 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
*/
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()
*/

42
plugins/DummyPlugin.php
Unescape View File

@ -16,6 +16,7 @@ class DummyPlugin extends AbstractPicoPlugin
/**
* This plugin is enabled by default?
*
* @var boolean
* @see AbstractPicoPlugin::$enabled
*/
protected $enabled = false;
@ -23,6 +24,7 @@ class DummyPlugin extends AbstractPicoPlugin
/**
* This plugin depends on {@link ...}
*
* @var array<string>
* @see AbstractPicoPlugin::$dependsOn
*/
protected $dependsOn = array();
@ -47,7 +49,7 @@ class DummyPlugin extends AbstractPicoPlugin
* Triggered after Pico has read its configuration
*
* @see Pico::getConfig()
* @param array &$config array of config variables
* @param array<string, mixed> &$config array of config variables
* @return void
*/
public function onConfigLoaded(&$config)
@ -60,7 +62,7 @@ class DummyPlugin extends AbstractPicoPlugin
*
* @see Pico::getBaseUrl()
* @see Pico::getRequestUrl()
* @param string &$url request URL
* @param string &$url part of the URL describing the requested contents
* @return void
*/
public function onRequestUrl(&$url)
@ -72,7 +74,7 @@ class DummyPlugin extends AbstractPicoPlugin
* Triggered after Pico has discovered the content file to serve
*
* @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
*/
public function onRequestFile(&$file)
@ -132,7 +134,9 @@ class DummyPlugin extends AbstractPicoPlugin
* Triggered when Pico reads its known meta header fields
*
* @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
*/
public function onMetaHeaders(&$headers)
@ -144,8 +148,8 @@ class DummyPlugin extends AbstractPicoPlugin
* Triggered before Pico parses the meta header
*
* @see Pico::parseFileMeta()
* @param string &$rawContent raw file contents
* @param array &$headers known meta header fields
* @param string &$rawContent raw file contents
* @param array<string, string> &$headers known meta header fields
* @return void
*/
public function onMetaParsing(&$rawContent, &$headers)
@ -157,7 +161,7 @@ class DummyPlugin extends AbstractPicoPlugin
* Triggered after Pico has parsed the meta header
*
* @see Pico::getFileMeta()
* @param array &$meta parsed meta data
* @param array<string, string> &$meta parsed meta data
* @return void
*/
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
*
* @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
*/
public function onSinglePageLoaded(&$pageData)
@ -215,6 +232,9 @@ class DummyPlugin extends AbstractPicoPlugin
/**
* 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::getCurrentPage()
* @see Pico::getPreviousPage()
@ -244,9 +264,9 @@ class DummyPlugin extends AbstractPicoPlugin
* Triggered before Pico renders the page
*
* @see Pico::getTwig()
* @param Twig_Environment &$twig twig template engine
* @param array &$twigVariables variables passed to the template
* @param string &$templateName name of the template to render
* @param Twig_Environment &$twig twig template engine
* @param array<string, mixed> &$twigVariables template variables
* @param string &$templateName file name of the template
* @return void
*/
public function onPageRendering(&$twig, &$twigVariables, &$templateName)

Write Preview
Loading…
Cancel
Save