PHP Class Pico

Pico is a stupidly simple, blazing fast, flat file CMS. - Stupidly Simple: Pico makes creating and maintaining a website as simple as editing text files. - Blazing Fast: Pico is seriously lightweight and doesn't use a database, making it super fast. - No Database: Pico is a "flat file" CMS, meaning no database woes, no MySQL queries, nothing. - Markdown Formatting: Edit your website in your favourite text editor using simple Markdown formatting. - Twig Templates: Pico uses the Twig templating engine, for powerful and flexible themes. - Open Source: Pico is completely free and open source, released under the MIT license. See for more info.
Author: Gilbert Pellegrom
Author: Daniel Rudolf
Mostrar archivo Open project: gilbitron/pico Class Usage Examples

Protected Properties

Property Type Description
$config array | null Current configuration of this Pico instance
$configDir string Config directory of this Pico instance
$content string | null Parsed content being served
$currentPage array | null Data of the page being served
$locked boolean Boolean indicating whether Pico started processing yet
$meta array | null Meta data of the page to serve
$nextPage array | null Data of the next page relative to the page being served
$pages array[] | null List of known pages
$parsedown ParsedownExtra | null Parsedown Extra instance used for markdown parsing
$plugins object[] | null List of loaded plugins
$pluginsDir string Plugins directory of this Pico instance
$previousPage array | null Data of the previous page relative to the page being served
$rawContent string | null Raw, not yet parsed contents to serve
$requestFile string | null Absolute path to the content file being served
$requestUrl string | null Part of the URL describing the requested contents
$rootDir string Root directory of this Pico instance
$themesDir string Themes directory of this Pico instance
$twig Twig_Environment | null Twig instance used for template parsing
$twigVariables array | null Variables passed to the twig template

Public Methods

Method Description
__construct ( string $rootDir, string $configDir, string $pluginsDir, string $themesDir ) Constructs a new Pico instance
getAbsolutePath ( string $path ) : string Makes a relative path absolute to Pico's root dir
getBaseUrl ( ) : string Returns the base URL of this Pico instance
getConfig ( string $configName = null ) : mixed Returns either the value of the specified config variable or the config array
getConfigDir ( ) : string Returns the config directory of this Pico instance
getCurrentPage ( ) : array | null Returns the data of the requested page
getFileContent ( ) : string | null Returns the cached contents of the requested page
getFileMeta ( ) : array | null Returns the parsed meta data of the requested page
getMetaHeaders ( ) : string[] Returns known meta headers and triggers the onMetaHeaders event
getNextPage ( ) : array | null Returns the data of the next page relative to the page being served
getPageUrl ( string $page, array | string $queryData = null ) : string Returns the URL to a given page
getPages ( ) : array[] | null Returns the list of known pages
getParsedown ( ) : ParsedownExtra | null Returns the Parsedown Extra markdown parser
getPlugin ( string $pluginName ) : object Returns the instance of a named plugin
getPlugins ( ) : object[] | null Returns all loaded plugins
getPluginsDir ( ) : string Returns the plugins directory of this Pico instance
getPreviousPage ( ) : array | null Returns the data of the previous page relative to the page being served
getRawContent ( ) : string | null Returns the raw contents, either of the requested or the 404 file
getRequestFile ( ) : string | null Returns the absolute path to the content file to serve
getRequestUrl ( ) : string | null Returns the URL where a user requested the page
getRootDir ( ) : string Returns the root directory of this Pico instance
getThemesDir ( ) : string Returns the themes directory of this Pico instance
getTwig ( ) : Twig_Environment | null Returns the twig template engine
isUrlRewritingEnabled ( ) : boolean Returns true if URL rewriting is enabled
load404Content ( string $file ) : string Returns the raw contents of the first found 404 file when traversing up from the directory the requested file is in
loadFileContent ( string $file ) : string Returns the raw contents of a file
parseFileContent ( string $content ) : string Parses the contents of a page using ParsedownExtra
parseFileMeta ( string $rawContent, array $headers ) : array Parses the file meta from raw file contents
prepareFileContent ( string $rawContent, array $meta ) : string Applies some static preparations to the raw contents of a page, e.g. removing the meta header and replacing %base_url%
run ( ) : string Runs this Pico instance
setConfig ( array $config ) : void Sets Pico's config before calling Pico::run()

Protected Methods

Method Description
discoverCurrentPage ( ) : void Walks through the list of known pages and discovers the requested page as well as the previous and next page relative to it
discoverRequestFile ( ) : void Uses the request URL to discover the content file to serve
evaluateRequestUrl ( ) : void Evaluates the requested URL
getFiles ( string $directory, string $fileExtension = '', integer $order = self::SORT_ASC ) : array Recursively walks through a directory and returns all containing files matching the specified file extension
getTwigVariables ( ) : array Returns the variables passed to the template
loadConfig ( ) : void Loads the config.php from Pico::$configDir
loadPlugins ( ) : void Loads plugins from Pico::$pluginsDir in alphabetical order
readPages ( ) : void Reads the data of all pages known to Pico
registerParsedown ( ) : void Registers the Parsedown Extra markdown parser
registerTwig ( ) : void Registers the twig template engine
sortPages ( ) : void Sorts all pages known to Pico
triggerEvent ( string $eventName, array $params = [] ) : void Triggers events on plugins which implement PicoPluginInterface

Method Details

__construct() public method

To carry out all the processing in Pico, call {@link Pico::run()}.
public __construct ( string $rootDir, string $configDir, string $pluginsDir, string $themesDir )
$rootDir string root directory of this Pico instance
$configDir string config directory of this Pico instance
$pluginsDir string plugins directory of this Pico instance
$themesDir string themes directory of this Pico instance

discoverCurrentPage() protected method

Walks through the list of known pages and discovers the requested page as well as the previous and next page relative to it
See also: Pico::getCurrentPage()
See also: Pico::getPreviousPage()
See also: Pico::getNextPage()
protected discoverCurrentPage ( ) : void
return void

discoverRequestFile() protected method

Uses the request URL to discover the content file to serve
See also: Pico::getRequestFile()
protected discoverRequestFile ( ) : void
return void

evaluateRequestUrl() protected method

Pico 1.0 uses the QUERY_STRING routing method (e.g. /pico/?sub/page) to support SEO-like URLs out-of-the-box with any webserver. You can still setup URL rewriting (e.g. using mod_rewrite on Apache) to basically remove the ? from URLs, but your rewritten URLs must follow the new QUERY_STRING principles. URL rewriting requires some special configuration on your webserver, but this should be "basic work" for any webmaster... Pico 0.9 and older required Apache with mod_rewrite enabled, thus old 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 update your rewriting rules. We recommend you to use the link filter in templates to create internal links, e.g. {{ "sub/page"|link }} is equivalent to {{ base_url }}/sub/page and {{ base_url }}?sub/page, depending on enabled URL rewriting. In content files you can use the %base_url% variable; e.g. %base_url%?sub/page will be replaced accordingly.
See also: Pico::getRequestUrl()
protected evaluateRequestUrl ( ) : void
return void

getAbsolutePath() public method

This method also guarantees a trailing slash.
public getAbsolutePath ( string $path ) : string
$path string relative or absolute path
return string absolute path

getBaseUrl() public method

Security Notice: You MUST configure Pico's base URL explicitly when using the base URL in contexts that are potentially vulnerable to HTTP Host Header Injection attacks (e.g. when generating emails).
public getBaseUrl ( ) : string
return string the base url

getConfig() public method

Returns either the value of the specified config variable or the config array
See also: Pico::setConfig()
See also: Pico::loadConfig()
public getConfig ( string $configName = null ) : mixed
$configName string optional name of a config variable
return mixed returns either the value of the named config variable, null if the config variable doesn't exist or the config array if no config name was supplied

getConfigDir() public method

Returns the config directory of this Pico instance
public getConfigDir ( ) : string
return string config directory path

getCurrentPage() public method

Returns the data of the requested page
See also: Pico::discoverCurrentPage()
public getCurrentPage ( ) : array | null
return array | null page data

getFileContent() public method

Returns the cached contents of the requested page
See also: Pico::prepareFileContent()
See also: Pico::parseFileContent()
public getFileContent ( ) : string | null
return string | null parsed contents

getFileMeta() public method

Returns the parsed meta data of the requested page
See also: Pico::parseFileMeta()
public getFileMeta ( ) : array | null
return array | null parsed meta data

getFiles() protected method

Recursively walks through a directory and returns all containing files matching the specified file extension
protected getFiles ( string $directory, string $fileExtension = '', integer $order = self::SORT_ASC ) : array
$directory string start directory
$fileExtension string return files with the given file extension only (optional)
$order integer 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

getMetaHeaders() public method

Heads up! Calling this method triggers the onMetaHeaders event. Keep this in mind to prevent a infinite loop!
public getMetaHeaders ( ) : string[]
return 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

getNextPage() public method

Returns the data of the next page relative to the page being served
See also: Pico::discoverCurrentPage()
public getNextPage ( ) : array | null
return array | null page data

getPageUrl() public method

Returns the URL to a given page
public getPageUrl ( string $page, array | string $queryData = null ) : string
$page string identifier of the page to link to
$queryData array | string either an array containing properties to create a URL-encoded query string from, or a already encoded string
return string URL

getPages() public method

Returns the list of known pages
See also: Pico::readPages()
See also: Pico::sortPages()
public getPages ( ) : array[] | null
return array[] | null the data of all pages

getParsedown() public method

Returns the Parsedown Extra markdown parser
See also: Pico::registerParsedown()
public getParsedown ( ) : ParsedownExtra | null
return ParsedownExtra | null Parsedown Extra markdown parser

getPlugin() public method

Plugins SHOULD implement {@link PicoPluginInterface}, but you MUST NOT rely on it. For more information see {@link PicoPluginInterface}.
See also: Pico::loadPlugins()
See also: Pico::getPlugins()
public getPlugin ( string $pluginName ) : object
$pluginName string name of the plugin
return object instance of the plugin

getPlugins() public method

Returns all loaded plugins
See also: Pico::loadPlugins()
See also: Pico::getPlugin()
public getPlugins ( ) : object[] | null
return object[] | null

getPluginsDir() public method

Returns the plugins directory of this Pico instance
public getPluginsDir ( ) : string
return string plugins directory path

getPreviousPage() public method

Returns the data of the previous page relative to the page being served
See also: Pico::discoverCurrentPage()
public getPreviousPage ( ) : array | null
return array | null page data

getRawContent() public method

Returns the raw contents, either of the requested or the 404 file
See also: Pico::loadFileContent()
See also: Pico::load404Content()
public getRawContent ( ) : string | null
return string | null raw contents

getRequestFile() public method

Returns the absolute path to the content file to serve
See also: Pico::discoverRequestFile()
public getRequestFile ( ) : string | null
return string | null file path

getRequestUrl() public method

Returns the URL where a user requested the page
See also: Pico::evaluateRequestUrl()
public getRequestUrl ( ) : string | null
return string | null request URL

getRootDir() public method

Returns the root directory of this Pico instance
public getRootDir ( ) : string
return string root directory path

getThemesDir() public method

Returns the themes directory of this Pico instance
public getThemesDir ( ) : string
return string themes directory path

getTwig() public method

Returns the twig template engine
See also: Pico::registerTwig()
public getTwig ( ) : Twig_Environment | null
return Twig_Environment | null Twig template engine

getTwigVariables() protected method

URLs and paths (namely base_dir, base_url, theme_dir and theme_url) don't add a trailing slash for historic reasons.
protected getTwigVariables ( ) : array
return array template variables

isUrlRewritingEnabled() public method

Returns true if URL rewriting is enabled
public isUrlRewritingEnabled ( ) : boolean
return boolean true if URL rewriting is enabled, false otherwise

load404Content() public method

Returns the raw contents of the first found 404 file when traversing up from the directory the requested file is in
See also: Pico::getRawContent()
public load404Content ( string $file ) : string
$file string path to requested (but not existing) file
return string raw contents of the 404 file

loadConfig() protected method

Loads the config.php from Pico::$configDir
See also: Pico::setConfig()
See also: Pico::getConfig()
protected loadConfig ( ) : void
return void

loadFileContent() public method

Returns the raw contents of a file
See also: Pico::getRawContent()
public loadFileContent ( string $file ) : string
$file string file path
return string raw contents of the file

loadPlugins() protected method

Plugin files MAY be prefixed by a number (e.g. 00-PicoDeprecated.php) to indicate their processing order. Plugins without a prefix will be loaded last. If you want to use a prefix, you MUST consider the following directives: - 00 to 19: Reserved - 20 to 39: Low level code helper plugins - 40 to 59: Plugins manipulating routing or the pages array - 60 to 79: Plugins hooking into template or markdown parsing - 80 to 99: Plugins using the onPageRendered event
See also: Pico::getPlugin()
See also: Pico::getPlugins()
protected loadPlugins ( ) : void
return void

parseFileContent() public method

Parses the contents of a page using ParsedownExtra
See also: Pico::prepareFileContent()
See also: Pico::getFileContent()
public parseFileContent ( string $content ) : string
$content string raw contents of a page (Markdown)
return string parsed contents (HTML)

parseFileMeta() public method

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 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 onMetaHeaders event first. The implicit availability of headers is for users and pure (!) theme developers ONLY.
See also: Pico::getFileMeta()
See also: http://symfony.com/doc/current/components/yaml/introduction.html
public parseFileMeta ( string $rawContent, array $headers ) : array
$rawContent string the raw file contents
$headers array known meta headers
return array parsed meta data

prepareFileContent() public method

Applies some static preparations to the raw contents of a page, e.g. removing the meta header and replacing %base_url%
See also: Pico::parseFileContent()
See also: Pico::getFileContent()
public prepareFileContent ( string $rawContent, array $meta ) : string
$rawContent string raw contents of a page
$meta array meta data to use for %meta.*% replacement
return string contents prepared for parsing

readPages() protected method

The page data will be an array containing 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 | | raw_content | string | raw, not yet parsed contents of the page | | meta | string | parsed meta data of the page |
See also: Pico::sortPages()
See also: Pico::getPages()
protected readPages ( ) : void
return void

registerParsedown() protected method

Registers the Parsedown Extra markdown parser
See also: Pico::getParsedown()
protected registerParsedown ( ) : void
return void

registerTwig() protected method

This method also registers Pico's core Twig filters link and content as well as Pico's {@link PicoTwigExtension} Twig extension.
See also: Pico::getTwig()
protected registerTwig ( ) : void
return void

run() public method

Loads plugins, evaluates the config file, does URL routing, parses meta headers, processes Markdown, does Twig processing and returns the rendered contents.
public run ( ) : string
return string rendered Pico contents

setConfig() public method

This method allows you to modify Pico's config without creating a {@path "config/config.php"} or changing some of its variables before Pico starts processing. You can call this method between {@link Pico::__construct()} and {@link Pico::run()} only. Options set with this method cannot be overwritten by {@path "config/config.php"}.
See also: Pico::loadConfig()
See also: Pico::getConfig()
public setConfig ( array $config ) : void
$config array array with config variables
return void

sortPages() protected method

Sorts all pages known to Pico
See also: Pico::readPages()
See also: Pico::getPages()
protected sortPages ( ) : void
return void

triggerEvent() protected method

Deprecated events (as used by plugins not implementing {@link PicoPluginInterface}) are triggered by {@link PicoDeprecated}.
See also: PicoPluginInterface
See also: AbstractPicoPlugin
See also: DummyPlugin
protected triggerEvent ( string $eventName, array $params = [] ) : void
$eventName string name of the event to trigger
$params array optional parameters to pass
return void

Property Details

$config protected_oe property

Current configuration of this Pico instance
See also: Pico::getConfig()
protected array|null $config
return array | null

$configDir protected_oe property

Config directory of this Pico instance
See also: Pico::getConfigDir()
protected string $configDir
return string

$content protected_oe property

Parsed content being served
See also: Pico::getFileContent()
protected string|null $content
return string | null

$currentPage protected_oe property

Data of the page being served
See also: Pico::getCurrentPage()
protected array|null $currentPage
return array | null

$locked protected_oe property

Boolean indicating whether Pico started processing yet
protected bool $locked
return boolean

$meta protected_oe property

Meta data of the page to serve
See also: Pico::getFileMeta()
protected array|null $meta
return array | null

$nextPage protected_oe property

Data of the next page relative to the page being served
See also: Pico::getNextPage()
protected array|null $nextPage
return array | null

$pages protected_oe property

List of known pages
See also: Pico::getPages()
protected array[]|null $pages
return array[] | null

$parsedown protected_oe property

Parsedown Extra instance used for markdown parsing
See also: Pico::getParsedown()
protected ParsedownExtra|null $parsedown
return ParsedownExtra | null

$plugins protected_oe property

List of loaded plugins
See also: Pico::getPlugins()
protected object[]|null $plugins
return object[] | null

$pluginsDir protected_oe property

Plugins directory of this Pico instance
See also: Pico::getPluginsDir()
protected string $pluginsDir
return string

$previousPage protected_oe property

Data of the previous page relative to the page being served
See also: Pico::getPreviousPage()
protected array|null $previousPage
return array | null

$rawContent protected_oe property

Raw, not yet parsed contents to serve
See also: Pico::getRawContent()
protected string|null $rawContent
return string | null

$requestFile protected_oe property

Absolute path to the content file being served
See also: Pico::getRequestFile()
protected string|null $requestFile
return string | null

$requestUrl protected_oe property

Part of the URL describing the requested contents
See also: Pico::getRequestUrl()
protected string|null $requestUrl
return string | null

$rootDir protected_oe property

Root directory of this Pico instance
See also: Pico::getRootDir()
protected string $rootDir
return string

$themesDir protected_oe property

Themes directory of this Pico instance
See also: Pico::getThemesDir()
protected string $themesDir
return string

$twig protected_oe property

Twig instance used for template parsing
See also: Pico::getTwig()
protected Twig_Environment|null $twig
return Twig_Environment | null

$twigVariables protected_oe property

Variables passed to the twig template
See also: Pico::getTwigVariables
protected array|null $twigVariables
return array | null