Pico 3.0 API Documentation (master branch)

Pico
in package

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 https://picocms.org/ for more info.

Tags
author

Gilbert Pellegrom

author

Daniel Rudolf

link
https://picocms.org
license

https://opensource.org/licenses/MIT The MIT License

version
3.0

Table of Contents

API_VERSION  = 4
Pico API version
SORT_ASC  = 0
Sort files in alphabetical ascending order
SORT_DESC  = 1
Sort files in alphabetical descending order
SORT_NONE  = 2
Don't sort files
VERSION  = '3.0.0-alpha.3'
Pico version
VERSION_ID  = 30000
Pico version ID
__construct()  : mixed
Constructs a new Pico instance
getAbsolutePath()  : string
Makes a relative path absolute to Pico's root dir
getAbsoluteUrl()  : string
Makes a relative URL absolute to Pico's base URL
getBaseThemeUrl()  : string
Returns the URL of the themes folder of this Pico instance
getBaseUrl()  : string
Returns the base URL of this Pico instance
getConfig()  : 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<string|int, mixed>|null
Returns the data of the requested page
getFileContent()  : string|null
Returns the cached contents of the requested page
getFileMeta()  : array<string|int, mixed>|null
Returns the parsed meta data of the requested page
getFiles()  : array<string|int, mixed>
Recursively walks through a directory and returns all containing files matching the specified file extension
getFilesGlob()  : array<string|int, mixed>
Returns all files in a directory matching a libc glob() pattern
getFormParameter()  : mixed
Filters a HTTP POST parameter with a specified filter
getMetaHeaders()  : array<string|int, string>
Returns known meta headers
getNextPage()  : array<string|int, mixed>|null
Returns the data of the next page relative to the page being served
getNormalizedPath()  : string
Normalizes a path by taking care of '', '.' and '..' parts
getPageId()  : string|null
Returns the page ID of a given content file
getPages()  : array<string|int, array<string|int, mixed>>|null
Returns the list of known pages
getPageTree()  : array<string|int, array<string|int, mixed>>|null
Returns a tree structure of known pages
getPageUrl()  : string
Returns the URL to a given page
getParsedown()  : Parsedown
Returns the Parsedown markdown parser
getPlugin()  : object
Returns the instance of a named plugin
getPlugins()  : array<string|int, object>|null
Returns all loaded plugins
getPluginsDir()  : string
Returns the plugins directory of this Pico instance
getPreviousPage()  : array<string|int, mixed>|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
getTheme()  : string
Returns the name of the current theme
getThemeApiVersion()  : int
Returns the API version of the current theme
getThemesDir()  : string
Returns the themes directory of this Pico instance
getTwig()  : TwigEnvironment|null
Returns the Twig template engine
getUrlFromPath()  : string
Returns the URL of a given absolute path within this Pico instance
getUrlParameter()  : mixed
Filters a URL GET parameter with a specified filter
getVendorDir()  : string
Returns the vendor directory of this Pico instance
getYamlParser()  : YamlParser
Returns the Symfony YAML parser
is404Content()  : bool
Returns TRUE when Pico is serving a 404 page
isDebugModeEnabled()  : bool
Returns TRUE if Pico's debug mode is enabled
isUrlRewritingEnabled()  : bool
Returns TRUE if URL rewriting is enabled
load404Content()  : string
Returns the raw contents of the first found 404 file when traversing up from the directory the requested file is in
loadFileContent()  : string
Returns the raw contents of a file
loadPlugin()  : PicoPluginInterface
Manually loads a plugin
parseFileContent()  : string
Parses the contents of a page using ParsedownExtra
parseFileMeta()  : array<string|int, mixed>
Parses the file meta from raw file contents
prepareFileContent()  : string
Applies some static preparations to the raw contents of a page
resolveFilePath()  : string
Resolves a given file path to its corresponding content file
run()  : string
Runs this Pico instance
setConfig()  : mixed
Sets Pico's config before calling Pico::run()
substituteFileContent()  : string
Replaces all %...% placeholders in a page's contents
substituteUrl()  : string
Substitutes URL placeholders (e.g. %base_url%)
triggerEvent()  : mixed
Triggers events on plugins using the current API version

Constants

API_VERSION

Pico API version

public int API_VERSION = 4

SORT_DESC

Sort files in alphabetical descending order

public int SORT_DESC = 1
Tags
see
Pico::getFiles()

VERSION

Pico version

public string VERSION = '3.0.0-alpha.3'

VERSION_ID

Pico version ID

public int VERSION_ID = 30000

Methods

__construct()

Constructs a new Pico instance

public __construct(string $rootDir, string $configDir, string $pluginsDir, string $themesDir[, bool $enableLocalPlugins = true ]) : mixed

To carry out all the processing in Pico, call Pico::run().

Parameters
$rootDir : string

root dir of this Pico instance

$configDir : string

config dir of this Pico instance

$pluginsDir : string

plugins dir of this Pico instance

$themesDir : string

themes dir of this Pico instance

$enableLocalPlugins : bool = true

enables (TRUE; default) or disables (FALSE) loading plugins from the filesystem

Return values
mixed —

getAbsolutePath()

Makes a relative path absolute to Pico's root dir

public getAbsolutePath(string $path[, string $basePath = null ][, bool $endSlash = true ]) : string
Parameters
$path : string

relative or absolute path

$basePath : string = null

treat relative paths relative to the given path; defaults to Pico::$rootDir

$endSlash : bool = true

whether to add a trailing slash to the absolute path or not (defaults to TRUE)

Return values
string —

absolute path

getAbsoluteUrl()

Makes a relative URL absolute to Pico's base URL

public getAbsoluteUrl(string $url[, string $baseUrl = null ][, bool $endSlash = true ]) : string

Please note that URLs starting with a slash are considered absolute URLs even though they don't include a scheme and host.

Parameters
$url : string

relative or absolute URL

$baseUrl : string = null

treat relative URLs relative to the given URL; defaults to Pico::getBaseUrl()

$endSlash : bool = true

whether to add a trailing slash to the absolute URL or not (defaults to TRUE)

Return values
string —

absolute URL

getBaseThemeUrl()

Returns the URL of the themes folder of this Pico instance

public getBaseThemeUrl() : string
Tags
see
Pico::getUrlFromPath()
deprecated
2.1.0
Return values
string —

getBaseUrl()

Returns the base URL of this Pico instance

public getBaseUrl() : string

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).

Return values
string —

the base url

getConfig()

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

public getConfig([string $configName = null ][, mixed $default = null ]) : mixed
Parameters
$configName : string = null

optional name of a config variable

$default : mixed = null

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

Tags
see
Pico::setConfig()
see
Pico::loadConfig()
Return values
mixed —

if no name of a config variable has been supplied, the 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

getConfigDir()

Returns the config directory of this Pico instance

public getConfigDir() : string
Return values
string —

config directory path

getCurrentPage()

Returns the data of the requested page

public getCurrentPage() : array<string|int, mixed>|null
Tags
see
Pico::discoverCurrentPage()
Return values
array<string|int, mixed>|null —

page data

getFileMeta()

Returns the parsed meta data of the requested page

public getFileMeta() : array<string|int, mixed>|null
Tags
see
Pico::parseFileMeta()
Return values
array<string|int, mixed>|null —

parsed meta data

getFiles()

Recursively walks through a directory and returns all containing files matching the specified file extension

public getFiles(string $directory[, string $fileExtension = '' ][, int $order = self::SORT_ASC ]) : array<string|int, mixed>
Parameters
$directory : string

start directory

$fileExtension : string = ''

return files with the given file extension only (optional)

$order : int = self::SORT_ASC

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 values
array<string|int, mixed> —

list of found files

getFilesGlob()

Returns all files in a directory matching a libc glob() pattern

public getFilesGlob(string $pattern[, int $order = self::SORT_ASC ]) : array<string|int, mixed>
Parameters
$pattern : string

the pattern to search for; see PHP's glob() function for details

$order : int = self::SORT_ASC

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

Tags
see
https://secure.php.net/manual/en/function.glob.php

PHP's glob() function

Return values
array<string|int, mixed> —

list of found files

getFormParameter()

Filters a HTTP POST parameter with a specified filter

public getFormParameter(string $name[, int|string $filter = '' ][, mixed|array<string|int, mixed> $options = null ][, int|string|array<string|int, int>|array<string|int, string> $flags = null ]) : mixed

This method is just an alias for Pico::filterVariable(), see Pico::filterVariable() for a detailed description. It can be used in Twig templates by calling the form_param function.

Parameters
$name : string

name of the HTTP POST parameter to filter

$filter : int|string = ''

the filter to apply

$options : mixed|array<string|int, mixed> = null

either a associative options array to be used by the filter or a scalar default value

$flags : int|string|array<string|int, int>|array<string|int, string> = null

flags and flag strings to be used by the filter

Tags
see
Pico::filterVariable()
Return values
mixed —

either the filtered data, FALSE if the filter fails, or NULL if the HTTP POST parameter doesn't exist and no default value is given

getMetaHeaders()

Returns known meta headers

public getMetaHeaders() : array<string|int, string>

This method triggers the onMetaHeaders event when the known meta headers weren't assembled yet.

Return values
array<string|int, string> —

known meta headers; the array key specifies the YAML key to search for, the array value is later used to access the found value

getNextPage()

Returns the data of the next page relative to the page being served

public getNextPage() : array<string|int, mixed>|null
Tags
see
Pico::discoverCurrentPage()
Return values
array<string|int, mixed>|null —

page data

getNormalizedPath()

Normalizes a path by taking care of '', '.' and '..' parts

public getNormalizedPath(string $path[, bool $allowAbsolutePath = false ][, bool $endSlash = true ]) : string
Parameters
$path : string

path to normalize

$allowAbsolutePath : bool = false

whether absolute paths are allowed

$endSlash : bool = true

whether to add a trailing slash to the normalized path or not (defaults to TRUE)

Tags
throws
UnexpectedValueException

thrown when a absolute path is passed although absolute paths aren't allowed

Return values
string —

normalized path

getPageId()

Returns the page ID of a given content file

public getPageId(string $path) : string|null
Parameters
$path : string

path to the content file

Return values
string|null —

either the corresponding page ID or NULL

getPages()

Returns the list of known pages

public getPages() : array<string|int, array<string|int, mixed>>|null
Tags
see
Pico::readPages()
Return values
array<string|int, array<string|int, mixed>>|null —

the data of all pages

getPageTree()

Returns a tree structure of known pages

public getPageTree() : array<string|int, array<string|int, mixed>>|null
Tags
see
Pico::buildPageTree()
Return values
array<string|int, array<string|int, mixed>>|null —

the tree structure of all pages

getPageUrl()

Returns the URL to a given page

public getPageUrl(string $page[, array<string|int, mixed>|string|null $queryData = null ][, bool $dropIndex = true ]) : string

This method can be used in Twig templates by applying the link filter to a string representing a page ID.

Parameters
$page : string

ID of the page to link to

$queryData : array<string|int, mixed>|string|null = null

either an array of properties to create a URL-encoded query string from, or a already encoded string

$dropIndex : bool = true

if the last path component is "index", passing TRUE (default) will remove this path component

Tags
throws
InvalidArgumentException

thrown when invalid arguments got passed

Return values
string —

URL

getParsedown()

Returns the Parsedown markdown parser

public getParsedown() : Parsedown

This method triggers the onParsedownRegistered event when the Parsedown markdown parser wasn't initiated yet.

Return values
Parsedown —

Parsedown markdown parser

getPlugin()

Returns the instance of a named plugin

public getPlugin(string $pluginName) : object

Plugins SHOULD implement PicoPluginInterface, but you MUST NOT rely on it. For more information see PicoPluginInterface.

Parameters
$pluginName : string

name of the plugin

Tags
see
Pico::loadPlugins()
see
Pico::getPlugins()
throws
RuntimeException

thrown when the plugin wasn't found

Return values
object —

instance of the plugin

getPlugins()

Returns all loaded plugins

public getPlugins() : array<string|int, object>|null
Tags
see
Pico::loadPlugins()
see
Pico::getPlugin()
Return values
array<string|int, object>|null —

getPluginsDir()

Returns the plugins directory of this Pico instance

public getPluginsDir() : string
Return values
string —

plugins directory path

getPreviousPage()

Returns the data of the previous page relative to the page being served

public getPreviousPage() : array<string|int, mixed>|null
Tags
see
Pico::discoverCurrentPage()
Return values
array<string|int, mixed>|null —

page data

getRequestFile()

Returns the absolute path to the content file to serve

public getRequestFile() : string|null
Tags
see
Pico::resolveFilePath()
Return values
string|null —

file pat

getRequestUrl()

Returns the URL where a user requested the page

public getRequestUrl() : string|null
Tags
see
Pico::evaluateRequestUrl()
Return values
string|null —

request URL

getRootDir()

Returns the root directory of this Pico instance

public getRootDir() : string
Return values
string —

root directory path

getTheme()

Returns the name of the current theme

public getTheme() : string
Tags
see
Pico::loadTheme()
see
Pico::getThemeApiVersion()
Return values
string —

getThemeApiVersion()

Returns the API version of the current theme

public getThemeApiVersion() : int
Tags
see
Pico::loadTheme()
see
Pico::getTheme()
Return values
int —

getThemesDir()

Returns the themes directory of this Pico instance

public getThemesDir() : string
Return values
string —

themes directory path

getTwig()

Returns the Twig template engine

public getTwig() : TwigEnvironment|null

This method triggers the onTwigRegistered event when the Twig template engine wasn't initiated yet. When initiating Twig, this method also registers Pico's core Twig filter content as well as Pico's PicoTwigExtension Twig extension.

Tags
see
Pico::getTwig()
see
https://twig.symfony.com/

Twig website

see
https://github.com/twigphp/Twig

Twig on GitHub

Return values
TwigEnvironment|null —

Twig template engine

getUrlFromPath()

Returns the URL of a given absolute path within this Pico instance

public getUrlFromPath(string $absolutePath) : string

We assume that the given path is a arbitrary deep sub folder of the script's base path (i.e. the directory "index.php" is in resp. the httpdocs directory). If this isn't the case, we check whether it's a sub folder of Pico::$rootDir (what is often identical to the script's base path). If this isn't the case either, we fall back to the basename of the given folder. This whole process ultimately allows us to use Pico::getBaseUrl() as origin for the URL.

This method is used to guess Pico's plugins_url, themes_url and assets_url. However, guessing might fail, requiring a manual config.

Parameters
$absolutePath : string

the absolute path to interpret

Return values
string —

the URL of the given folder

getUrlParameter()

Filters a URL GET parameter with a specified filter

public getUrlParameter(string $name[, int|string $filter = '' ][, mixed|array<string|int, mixed> $options = null ][, int|string|array<string|int, int>|array<string|int, string> $flags = null ]) : mixed

This method is just an alias for Pico::filterVariable(), see Pico::filterVariable() for a detailed description. It can be used in Twig templates by calling the url_param function.

Parameters
$name : string

name of the URL GET parameter to filter

$filter : int|string = ''

the filter to apply

$options : mixed|array<string|int, mixed> = null

either a associative options array to be used by the filter or a scalar default value

$flags : int|string|array<string|int, int>|array<string|int, string> = null

flags and flag strings to be used by the filter

Tags
see
Pico::filterVariable()
Return values
mixed —

either the filtered data, FALSE if the filter fails, or NULL if the URL GET parameter doesn't exist and no default value is given

getVendorDir()

Returns the vendor directory of this Pico instance

public getVendorDir() : string
Return values
string —

vendor directory path

getYamlParser()

Returns the Symfony YAML parser

public getYamlParser() : YamlParser

This method triggers the onYamlParserRegistered event when the Symfony YAML parser wasn't initiated yet.

Return values
YamlParser —

Symfony YAML parser

is404Content()

Returns TRUE when Pico is serving a 404 page

public is404Content() : bool
Tags
see
Pico::load404Content()
Return values
bool —

TRUE if Pico is serving a 404 page, FALSE otherwise

isDebugModeEnabled()

Returns TRUE if Pico's debug mode is enabled

public isDebugModeEnabled() : bool
Return values
bool —

TRUE if Pico's debug mode is enabled, FALSE otherwise

isUrlRewritingEnabled()

Returns TRUE if URL rewriting is enabled

public isUrlRewritingEnabled() : bool
Return values
bool —

TRUE if URL rewriting is enabled, FALSE otherwise

load404Content()

Returns the raw contents of the first found 404 file when traversing up from the directory the requested file is in

public load404Content(string $file) : string

If no suitable 404.md is found, fallback to a built-in error message.

Parameters
$file : string

path to requested (but not existing) file

Tags
see
Pico::getRawContent()
Return values
string —

raw contents of the 404 file

loadFileContent()

Returns the raw contents of a file

public loadFileContent(string $file) : string
Parameters
$file : string

file path

Tags
see
Pico::getRawContent()
Return values
string —

raw contents of the file

loadPlugin()

Manually loads a plugin

public loadPlugin(PicoPluginInterface|string $plugin) : PicoPluginInterface

Manually loaded plugins MUST implement PicoPluginInterface. They are simply appended to the plugins array without any additional checks, so you might get unexpected results, depending on when you're loading a plugin. You SHOULD NOT load plugins after a event has been triggered by Pico. In-depth knowledge of Pico's inner workings is strongly advised otherwise, and you MUST NOT rely on PicoDeprecated to maintain backward compatibility in such cases.

If you e.g. load a plugin after the onPluginsLoaded event, Pico doesn't guarantee the plugin's order (Pico::sortPlugins()). Already triggered events won't get triggered on the manually loaded plugin. Thus you SHOULD load plugins either before Pico::run() is called, or via the constructor of another plugin (i.e. the plugin's __construct() method; plugins are instanced in Pico::loadPlugins()).

This method triggers the onPluginManuallyLoaded event.

Parameters
$plugin : PicoPluginInterface|string

either the class name of a plugin to instantiate or a plugin instance

Tags
see
Pico::loadPlugins()
see
Pico::getPlugin()
see
Pico::getPlugins()
throws
RuntimeException

thrown when the plugin couldn't be loaded

Return values
PicoPluginInterface —

instance of the loaded plugin

parseFileContent()

Parses the contents of a page using ParsedownExtra

public parseFileContent(string $markdown[, bool $singleLine = false ]) : string
Parameters
$markdown : string

Markdown contents of a page

$singleLine : bool = false

whether to parse just a single line of markup

Tags
see
Pico::prepareFileContent()
see
Pico::substituteFileContent()
see
Pico::getFileContent()
Return values
string —

parsed contents (HTML)

parseFileMeta()

Parses the file meta from raw file contents

public parseFileMeta(string $rawContent, array<string|int, string> $headers) : array<string|int, mixed>

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

Parameters
$rawContent : string

the raw file contents

$headers : array<string|int, string>

known meta headers

Tags
see
Pico::getFileMeta()
throws
ParseException

thrown when the meta data is invalid

Return values
array<string|int, mixed> —

parsed meta data

prepareFileContent()

Applies some static preparations to the raw contents of a page

public prepareFileContent(string $rawContent[, array<string|int, mixed> $meta = [] ][, string|null $pageId = null ]) : string

This method removes the meta header and replaces %...% placeholders by calling the Pico::substituteFileContent() method.

Parameters
$rawContent : string

raw contents of a page

$meta : array<string|int, mixed> = []

meta data to use for %meta.*% replacement

$pageId : string|null = null

unique ID of the page for %page_*% replacement, might be NULL

Tags
see
Pico::substituteFileContent()
see
Pico::parseFileContent()
see
Pico::getFileContent()
Return values
string —

prepared Markdown contents

resolveFilePath()

Resolves a given file path to its corresponding content file

public resolveFilePath(string $requestUrl) : string

This method also prevents content_dir breakouts using malicious request URLs. We don't use realpath(), because we neither want to check for file existance, nor prohibit symlinks which intentionally point to somewhere outside the content_dir folder. It is STRONGLY RECOMMENDED to use PHP's open_basedir feature - always, not just with Pico!

Parameters
$requestUrl : string

path name (likely from a URL) to resolve

Tags
see
Pico::getRequestFile()
Return values
string —

path to the resolved content file

run()

Runs this Pico instance

public run() : string

Loads plugins, evaluates the config file, does URL routing, parses meta headers, processes Markdown, does Twig processing and returns the rendered contents.

Tags
throws
Exception

thrown when a irrecoverable error occurs

Return values
string —

rendered Pico contents

setConfig()

Sets Pico's config before calling Pico::run()

public setConfig(array<string|int, mixed> $config) : mixed

This method allows you to modify Pico's config without creating a "config/config.yml" or changing some of its variables before Pico starts processing.

You can call this method between Pico::__construct() and Pico::run() only. Options set with this method cannot be overwritten by "config/config.yml".

Parameters
$config : array<string|int, mixed>

array with config variables

Tags
see
Pico::loadConfig()
see
Pico::getConfig()
throws
LogicException

thrown if Pico already started processing

Return values
mixed —

substituteFileContent()

Replaces all %...% placeholders in a page's contents

public substituteFileContent(string $markdown[, array<string|int, mixed> $meta = [] ][, string|null $pageId = null ]) : string
Parameters
$markdown : string

Markdown contents of a page

$meta : array<string|int, mixed> = []

meta data to use for %meta.*% replacement

$pageId : string|null = null

unique ID of the page for %page_*% replacement, might be NULL

Return values
string —

substituted Markdown contents

substituteUrl()

Substitutes URL placeholders (e.g. %base_url%)

public substituteUrl(string $url) : string

This method is registered as the url Twig filter and often used to allow users to specify absolute URLs in meta data utilizing the known URL placeholders %base_url%, %plugins_url%, %themes_url%, %assets_url% and %theme_url%.

Don't confuse this with the link Twig filter, which takes a page ID as parameter. However, you can indeed use this method to create page URLs, e.g. {{ "%base_url%?sub/page"|url }}.

Parameters
$url : string

URL with placeholders

Return values
string —

URL with replaced placeholders

triggerEvent()

Triggers events on plugins using the current API version

public triggerEvent(string $eventName[, array<string|int, mixed> $params = [] ]) : mixed

Plugins using older API versions are handled by PicoDeprecated. Please note that PicoDeprecated also triggers custom events on plugins using older API versions, thus you can safely use this method to trigger custom events on all loaded plugins, no matter what API version - the event will be triggered in any case.

You MUST NOT trigger events of Pico's core with a plugin!

Parameters
$eventName : string

name of the event to trigger

$params : array<string|int, mixed> = []

optional parameters to pass

Tags
see
PicoPluginInterface
see
AbstractPicoPlugin
see
DummyPlugin
Return values
mixed —

Search results