\Pico

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

Summary

Methods
Properties
Constants
__construct()
getRootDir()
getConfigDir()
getPluginsDir()
getThemesDir()
run()
getPlugin()
getPlugins()
setConfig()
getConfig()
getRequestUrl()
getRequestFile()
loadFileContent()
load404Content()
getRawContent()
getMetaHeaders()
parseFileMeta()
getFileMeta()
getParsedown()
prepareFileContent()
parseFileContent()
getFileContent()
getPages()
getCurrentPage()
getPreviousPage()
getNextPage()
getTwig()
getBaseUrl()
isUrlRewritingEnabled()
getPageUrl()
getAbsolutePath()
No public properties found
SORT_ASC
SORT_DESC
SORT_NONE
loadPlugins()
loadConfig()
evaluateRequestUrl()
discoverRequestFile()
registerParsedown()
readPages()
sortPages()
discoverCurrentPage()
registerTwig()
getTwigVariables()
getFiles()
triggerEvent()
$rootDir
$configDir
$pluginsDir
$themesDir
$locked
$plugins
$config
$requestUrl
$requestFile
$rawContent
$meta
$parsedown
$content
$pages
$currentPage
$previousPage
$nextPage
$twig
$twigVariables
N/A
No private methods found
No private properties found
N/A

Constants

SORT_ASC

SORT_ASC

Sort files in alphabetical ascending order

SORT_DESC

SORT_DESC

Sort files in alphabetical descending order

SORT_NONE

SORT_NONE

Don't sort files

Properties

$rootDir

$rootDir : string

Root directory of this Pico instance

Type

string

$configDir

$configDir : string

Config directory of this Pico instance

Type

string

$pluginsDir

$pluginsDir : string

Plugins directory of this Pico instance

Type

string

$themesDir

$themesDir : string

Themes directory of this Pico instance

Type

string

$locked

$locked : boolean

Boolean indicating whether Pico started processing yet

Type

boolean

$plugins

$plugins : array<mixed,object>|null

List of loaded plugins

Type

array<mixed,object>|null

$config

$config : array<mixed,mixed>|null

Current configuration of this Pico instance

Type

array<mixed,mixed>|null

$requestUrl

$requestUrl : string|null

Part of the URL describing the requested contents

Type

string|null

$requestFile

$requestFile : string|null

Absolute path to the content file being served

Type

string|null

$rawContent

$rawContent : string|null

Raw, not yet parsed contents to serve

Type

string|null

$meta

$meta : array<mixed,string>|null

Meta data of the page to serve

Type

array<mixed,string>|null

$parsedown

$parsedown : \ParsedownExtra|null

Parsedown Extra instance used for markdown parsing

Type

\ParsedownExtra|null

$content

$content : string|null

Parsed content being served

Type

string|null

$pages

$pages : array<mixed,array>|null

List of known pages

Type

array<mixed,array>|null

$currentPage

$currentPage : array|null

Data of the page being served

Type

array|null

$previousPage

$previousPage : array|null

Data of the previous page relative to the page being served

Type

array|null

$nextPage

$nextPage : array|null

Data of the next page relative to the page being served

Type

array|null

$twig

$twig : \Twig_Environment|null

Twig instance used for template parsing

Type

\Twig_Environment|null

$twigVariables

$twigVariables : array<mixed,mixed>|null

Variables passed to the twig template

Type

array<mixed,mixed>|null

Methods

__construct()

__construct(string  $rootDir, string  $configDir, string  $pluginsDir, string  $themesDir) 

Constructs a new Pico instance

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

Parameters

string $rootDir

root directory of this Pico instance

string $configDir

config directory of this Pico instance

string $pluginsDir

plugins directory of this Pico instance

string $themesDir

themes directory of this Pico instance

getRootDir()

getRootDir() : string

Returns the root directory of this Pico instance

Returns

string —

root directory path

getConfigDir()

getConfigDir() : string

Returns the config directory of this Pico instance

Returns

string —

config directory path

getPluginsDir()

getPluginsDir() : string

Returns the plugins directory of this Pico instance

Returns

string —

plugins directory path

getThemesDir()

getThemesDir() : string

Returns the themes directory of this Pico instance

Returns

string —

themes directory path

run()

run() : string

Runs this Pico instance

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

Throws

\Exception

thrown when a not recoverable error occurs

Returns

string —

rendered Pico contents

getPlugin()

getPlugin(string  $pluginName) : object

Returns the instance of a named plugin

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

Parameters

string $pluginName

name of the plugin

Throws

\RuntimeException

thrown when the plugin wasn't found

Returns

object —

instance of the plugin

getPlugins()

getPlugins() : array<mixed,object>|null

Returns all loaded plugins

Returns

array<mixed,object>|null

setConfig()

setConfig(array<mixed,mixed>  $config) : void

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

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 Pico::__construct() and Pico::run() only. Options set with this method cannot be overwritten by {@path "config/config.php"}.

Parameters

array<mixed,mixed> $config

array with config variables

Throws

\LogicException

thrown if Pico already started processing

getConfig()

getConfig(string  $configName = null) : mixed

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

Parameters

string $configName

optional name of a config variable

Returns

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

getRequestUrl()

getRequestUrl() : string|null

Returns the URL where a user requested the page

Returns

string|null —

request URL

getRequestFile()

getRequestFile() : string|null

Returns the absolute path to the content file to serve

Returns

string|null —

file path

loadFileContent()

loadFileContent(string  $file) : string

Returns the raw contents of a file

Parameters

string $file

file path

Returns

string —

raw contents of the file

load404Content()

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

Parameters

string $file

path to requested (but not existing) file

Throws

\RuntimeException

thrown when no suitable 404 file is found

Returns

string —

raw contents of the 404 file

getRawContent()

getRawContent() : string|null

Returns the raw contents, either of the requested or the 404 file

Returns

string|null —

raw contents

getMetaHeaders()

getMetaHeaders() : array<mixed,string>

Returns known meta headers and triggers the onMetaHeaders event

Heads up! Calling this method triggers the onMetaHeaders event. Keep this in mind to prevent a infinite loop!

Returns

array<mixed,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

parseFileMeta()

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

Parses the file meta from raw file contents

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.

Parameters

string $rawContent

the raw file contents

array<mixed,string> $headers

known meta headers

Throws

\Symfony\Component\Yaml\Exception\ParseException

thrown when the meta data is invalid

Returns

array —

parsed meta data

getFileMeta()

getFileMeta() : array|null

Returns the parsed meta data of the requested page

Returns

array|null —

parsed meta data

getParsedown()

getParsedown() : \ParsedownExtra|null

Returns the Parsedown Extra markdown parser

Returns

\ParsedownExtra|null —

Parsedown Extra markdown parser

prepareFileContent()

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%

Parameters

string $rawContent

raw contents of a page

array $meta

meta data to use for %meta.*% replacement

Returns

string —

contents prepared for parsing

parseFileContent()

parseFileContent(string  $content) : string

Parses the contents of a page using ParsedownExtra

Parameters

string $content

raw contents of a page (Markdown)

Returns

string —

parsed contents (HTML)

getFileContent()

getFileContent() : string|null

Returns the cached contents of the requested page

Returns

string|null —

parsed contents

getPages()

getPages() : array<mixed,array>|null

Returns the list of known pages

Returns

array<mixed,array>|null —

the data of all pages

getCurrentPage()

getCurrentPage() : array|null

Returns the data of the requested page

Returns

array|null —

page data

getPreviousPage()

getPreviousPage() : array|null

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

Returns

array|null —

page data

getNextPage()

getNextPage() : array|null

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

Returns

array|null —

page data

getTwig()

getTwig() : \Twig_Environment|null

Returns the twig template engine

Returns

\Twig_Environment|null —

Twig template engine

getBaseUrl()

getBaseUrl() : string

Returns the base URL of this Pico instance

Returns

string —

the base url

isUrlRewritingEnabled()

isUrlRewritingEnabled() : boolean

Returns true if URL rewriting is enabled

Returns

boolean —

true if URL rewriting is enabled, false otherwise

getPageUrl()

getPageUrl(string  $page, array|string  $queryData = null) : string

Returns the URL to a given page

Parameters

string $page

identifier of the page to link to

array|string $queryData

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

Returns

string —

URL

getAbsolutePath()

getAbsolutePath(string  $path) : string

Makes a relative path absolute to Pico's root dir

This method also guarantees a trailing slash.

Parameters

string $path

relative or absolute path

Returns

string —

absolute path

loadPlugins()

loadPlugins() : void

Loads plugins from Pico::$pluginsDir in alphabetical order

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

Throws

\RuntimeException

thrown when a plugin couldn't be loaded

loadConfig()

loadConfig() : void

Loads the config.php from Pico::$configDir

evaluateRequestUrl()

evaluateRequestUrl() : void

Evaluates the requested URL

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.

discoverRequestFile()

discoverRequestFile() : void

Uses the request URL to discover the content file to serve

registerParsedown()

registerParsedown() : void

Registers the Parsedown Extra markdown parser

readPages()

readPages() : void

Reads the data of all pages known to Pico

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

sortPages()

sortPages() : void

Sorts all pages known to Pico

discoverCurrentPage()

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

registerTwig()

registerTwig() : void

Registers the twig template engine

This method also registers Picos core Twig filters link and content as well as Picos PicoTwigExtension Twig extension.

getTwigVariables()

getTwigVariables() : array<mixed,mixed>

Returns the variables passed to the template

URLs and paths (namely base_dir, base_url, theme_dir and theme_url) don't add a trailing slash for historic reasons.

Returns

array<mixed,mixed> —

template variables

getFiles()

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

Parameters

string $directory

start directory

string $fileExtension

return files with the given file extension only (optional)

integer $order

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

Returns

array —

list of found files

triggerEvent()

triggerEvent(string  $eventName, array  $params = array()) : void

Triggers events on plugins which implement PicoPluginInterface

Deprecated events (as used by plugins not implementing \IPocPlugin) are triggered by \PicoDeprecated.

Parameters

string $eventName

name of the event to trigger

array $params

optional parameters to pass