Documentation

Cms
Classes

Controller
in package

october

cms

Uses AssetMaker, EventEmitter, ResponseMaker, SecurityController

The CMS controller class.

The controller finds and serves requested pages.

$assetPath


    public
        string
    $assetPath

Specifies a path to the asset directory.

$vars


    public
        array<string|int, mixed>
    $vars
     = []

A list of variables to pass to the page.

$assets


    protected
        array<string|int, mixed>
    $assets
     = ['js' => [], 'css' => [], 'rss' => []]

Collection of assets to display in the layout.

$componentContext


    protected
        ComponentBase
    $componentContext

Object of the active component, used internally.

$instance


    protected
    static    self
    $instance

Cache of self

$layout


    protected
        Layout
    $layout

A reference to the CMS layout template used by the page.

$layoutObj


    protected
        CodeBase
    $layoutObj

A reference to the CMS layout code section object.

$loader


    protected
        Loader
    $loader

A reference to the Twig template loader.

$page


    protected
        Page
    $page

A reference to the CMS page template being processed.

$pageContents


    protected
        string
    $pageContents

Contains the rendered page contents string.

$pageObj


    protected
        CodeBase
    $pageObj

A reference to the CMS page code section object.

$partialStack


    protected
        array<string|int, mixed>
    $partialStack
     = []

Component partial stack, used internally.

$responseHeaderBag


    protected
        ResponseHeaderBag
    $responseHeaderBag
     = null

$responseOverride


    protected
        mixed
    $responseOverride
     = null

Override the standard controller response.

$router


    protected
        Router
    $router

A reference to the Router object.

$statusCode


    protected
        int
    $statusCode
     = 200

Response status code

$theme


    protected
        Theme
    $theme

A reference to the CMS theme processed by the controller.

$twig


    protected
        Environment
    $twig

Keeps the Twig environment object.

__construct()

Creates the controller.


    public
                __construct([Theme $theme = null ]) : mixed

Parameters

$theme : Theme = null: Specifies the CMS theme. If the theme is not specified, the current active theme used.

Return values

mixed —

addComponent()

Adds a component to the page object.


    public
                addComponent(mixed $name, string $alias, array<string|int, mixed> $properties[, bool $addToLayout = false ]) : ComponentBase|null

Parameters

$name : mixed: Component class name or short name
$alias : string: Alias to give the component
$properties : array<string|int, mixed>: Component properties
$addToLayout : bool = false: Add to layout, instead of page

Return values

ComponentBase|null —

Component object. Will return null if a soft component is used but not found.

addCss()

Adds StyleSheet asset to the asset list. Call $this->makeAssets() in a view to output corresponding markup.


    public
                addCss(string $name[, array<string|int, mixed> $attributes = [] ]) : void

Parameters

$name : string: Specifies a path (URL) to the script.
$attributes : array<string|int, mixed> = []: Adds extra HTML attributes to the asset link.

Return values

void —

addJs()

Adds JavaScript asset to the asset list. Call $this->makeAssets() in a view to output corresponding markup.


    public
                addJs(string $name[, array<string|int, mixed> $attributes = [] ]) : void

Parameters

$name : string: Specifies a path (URL) to the script.
$attributes : array<string|int, mixed> = []: Adds extra HTML attributes to the asset link.

Return values

void —

addRss()

Adds an RSS link asset to the asset list. Call $this->makeAssets() in a view to output corresponding markup.


    public
                addRss(string $name[, array<string|int, mixed> $attributes = [] ]) : void

Parameters

$name : string: Specifies a path (URL) to the RSS channel
$attributes : array<string|int, mixed> = []: Adds extra HTML attributes to the asset link.

Return values

void —

combineAssets()

Run the provided assets through the Asset Combiner


    public
                combineAssets(array<string|int, mixed> $assets[, string $localPath = '' ]) : string

Parameters

$assets : array<string|int, mixed>: Collection of assets
$localPath : string = '': Prefix all assets with this path (optional)

Return values

string —

currentPageUrl()

Looks up the current page URL with supplied parameters and route persistence.


    public
                currentPageUrl([array<string|int, mixed> $parameters = [] ][, bool $routePersistence = true ]) : null|string

Parameters

$parameters : array<string|int, mixed> = []
$routePersistence : bool = true

Return values

null|string —

findComponentByHandler()

Searches the layout and page components by an AJAX handler


    public
                findComponentByHandler(string $handler) : ComponentBase

Parameters

$handler : string

Return values

ComponentBase —

The component object, if found

findComponentByName()

Searches the layout and page components by an alias


    public
                findComponentByName( $name) : ComponentBase

Parameters

$name :

Return values

ComponentBase —

The component object, if found

findComponentByPartial()

Searches the layout and page components by a partial file


    public
                findComponentByPartial(string $partial) : ComponentBase

Parameters

$partial : string

Return values

ComponentBase —

The component object, if found

fireSystemEvent()

Fires a combination of local and global events. The first segment is removed from the event name locally and the local object is passed as the first argument to the event globally. Halting is also enabled by default.


    public
                fireSystemEvent(string $event[, array<string|int, mixed> $params = [] ][, bool $halt = true ]) : mixed

For example:

$this->fireSystemEvent('backend.list.myEvent', ['my value']);

Is equivalent to:

$this->fireEvent('list.myEvent', ['myvalue'], true);

Event::fire('backend.list.myEvent', [$this, 'myvalue'], true);

Parameters

$event : string: Event name
$params : array<string|int, mixed> = []: Event parameters
$halt : bool = true: Halt after first non-null result

Return values

mixed —

fireViewEvent()

Special event function used for extending within view files, allowing HTML to be injected multiple times.


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

For example:

fireViewEvent('backend.auth.extendSigninView') ?>

Parameters

$event : string: Event name
$params : array<string|int, mixed> = []: Event parameters

Return values

string —

flushAssets()

Disables the use, and subequent broadcast, of assets. This is useful to call during an AJAX request to speed things up. This method works by specifically targeting the hasAssetsDefined method.


    public
                flushAssets() : void

Return values

void —

getAjaxHandler()

Returns the AJAX handler for the current request, if available.


    public
                getAjaxHandler() : string

Return values

string —

getAssetPath()

Locates a file based on it's definition. If the file starts with a forward slash, it will be returned in context of the application public path, otherwise it will be returned in context of the asset path.


    public
                getAssetPath(string $fileName[, string $assetPath = null ]) : string

Parameters

$fileName : string: File to load.
$assetPath : string = null: Explicitly define an asset path.

Return values

string —

Relative path to the asset file.

getAssetPaths()

Returns an array of all registered asset paths.


    public
                getAssetPaths() : array<string|int, mixed>

Return values

array<string|int, mixed> —

getController()

Returns an existing instance of the controller.


    public
            static    getController() : mixed

If the controller doesn't exists, returns null.

Return values

mixed —

Returns the controller object or null.

getLayout()

Returns the CMS layout object being processed by the controller.


    public
                getLayout() : Layout

The object is not available on the early stages of the controller initialization.

Return values

Layout —

Returns the Layout object or null.

getLayoutObject()

Intended to be called from the page, returns the layout code base object.


    public
                getLayoutObject() : CodeBase

Return values

CodeBase —

getLoader()

Returns the Twig loader.


    public
                getLoader() : Loader

Return values

Loader —

getPage()

Returns the CMS page object being processed by the controller.


    public
                getPage() : Page

The object is not available on the early stages of the controller initialization.

Return values

Page —

Returns the Page object or null.

getPageObject()

Intended to be called from the layout, returns the page code base object.


    public
                getPageObject() : CodeBase

Return values

CodeBase —

getResponseHeaders()

Get the header response bag


    public
                getResponseHeaders() : ResponseHeaderBag|null

Return values

ResponseHeaderBag|null —

getRouter()

Returns the routing object.


    public
                getRouter() : Router

Return values

Router —

getStatusCode()

Returns the status code for the current web response.


    public
                getStatusCode() : int

Return values

int —

Status code

getTheme()

Returns the current CMS theme.


    public
                getTheme() : Theme

Return values

Theme —

getTwig()

Returns the Twig environment.


    public
                getTwig() : Environment

Return values

Environment —

hasAssetsDefined()

Returns true if assets any have been added.


    public
                hasAssetsDefined() : bool

Return values

bool —

makeAssets()

Outputs `<link>` and `<script>` tags to load assets previously added with addJs and addCss method calls


    public
                makeAssets([string $type = null ]) : string

Parameters

$type : string = null: Return an asset collection of a given type (css, rss, js) or null for all.

Return values

string —

makeResponse()

Prepares a response that considers overrides and custom responses.


    public
                makeResponse(mixed $contents) : mixed

Parameters

$contents : mixed

Return values

mixed —

pageCycle()

Invokes the current page cycle without rendering the page, used by AJAX handler that may rely on the logic inside the action.


    public
                pageCycle() : mixed

Return values

mixed —

pageUrl()

Looks up the URL for a supplied page and returns it relative to the website root.


    public
                pageUrl(mixed $name[, array<string|int, mixed> $parameters = [] ][, bool $routePersistence = true ]) : string

Parameters

$name : mixed: Specifies the Cms Page file name.
$parameters : array<string|int, mixed> = []: Route parameters to consider in the URL.
$routePersistence : bool = true: By default the existing routing parameters will be included

Return values

string —

param()

Returns a routing parameter.


    public
                param(string $name[, string $default = null ]) : string

Parameters

$name : string: Routing parameter name.
$default : string = null: Default to use if none is found.

Return values

string —

render()

Renders a page in its entirety, including component initialization.


    public
            static    render(string $pageFile[, array<string|int, mixed> $parameters = [] ][, Theme $theme = null ]) : mixed

AJAX will be disabled for this process.

Parameters

$pageFile : string: Specifies the CMS page file name to run.
$parameters : array<string|int, mixed> = []: Routing parameters.
$theme : Theme = null: Theme object

Return values

mixed —

renderComponent()

Renders a component's default content, preserves the previous component context.


    public
                renderComponent( $name[, array<string|int, mixed> $parameters = [] ]) : string

Parameters

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

Return values

string —

Returns the component default contents.

renderContent()

Renders a requested content file.


    public
                renderContent(string $name[, array<string|int, mixed> $parameters = [] ]) : string

The framework uses this method internally.

Parameters

$name : string: The content view to load.
$parameters : array<string|int, mixed> = []: Parameter variables to pass to the view.

Return values

string —

renderPage()

Renders a requested page.


    public
                renderPage() : mixed

The framework uses this method internally.

Return values

mixed —

renderPartial()

Renders a requested partial.


    public
                renderPartial(string $name[, array<string|int, mixed> $parameters = [] ][, bool $throwException = true ]) : mixed

The framework uses this method internally.

Parameters

$name : string: The view to load.
$parameters : array<string|int, mixed> = []: Parameter variables to pass to the view.
$throwException : bool = true: Throw an exception if the partial is not found.

Return values

mixed —

Partial contents or false if not throwing an exception.

run()

Finds and serves the requested page.


    public
                run([string|null $url = '/' ]) : BaseResponse

If the page cannot be found, returns the page with the URL /404. If the /404 page doesn't exist, returns the system 404 page. If the parameter is null, the current URL used. If it is not provided then '/' is used

Parameters

$url : string|null = '/': Specifies the requested page URL.

Return values

BaseResponse —

Returns the response to the provided URL

runPage()

Runs a page directly from its object and supplied parameters.


    public
                runPage(Page $page[, mixed $useAjax = true ]) : string

Parameters

$page : Page: Specifies the CMS page to run.
$useAjax : mixed = true

Return values

string —

setComponentContext()

Set the component context manually, used by Components when calling renderPartial.


    public
                setComponentContext([ComponentBase $component = null ]) : void

Parameters

$component : ComponentBase = null

Return values

void —

setResponse()

Sets the response for the current page request cycle, this value takes priority over the standard response prepared by the controller.


    public
                setResponse(mixed $response) : $this

Parameters

$response : mixed: Response object or string

Return values

$this —

setResponseCookie()

Add a cookie to the response.


    public
                setResponseCookie(Cookie|mixed $cookie) : $this

Parameters

$cookie : Cookie|mixed

Return values

$this —

setResponseHeader()

Set a header on the Response.


    public
                setResponseHeader(string $key, array<string|int, mixed>|string $values[, bool $replace = true ]) : $this

Parameters

$key : string
$values : array<string|int, mixed>|string
$replace : bool = true

Return values

$this —

setStatusCode()

Sets the status code for the current web response.


    public
                setStatusCode(int $code) : $this

Parameters

$code : int: Status code

Return values

$this —

themeUrl()

Converts supplied URL to a theme URL relative to the website root. If the URL provided is an array then the files will be combined.


    public
                themeUrl([mixed $url = null ]) : string

Parameters

$url : mixed = null: Specifies the theme-relative URL. If null, the theme path is returned.

Return values

string —

addAsset()

Adds the provided asset to the internal asset collections


    protected
                addAsset(string $type, string $path, array<string|int, mixed> $attributes) : mixed

Parameters

$type : string: The type of the asset: 'js' || 'css' || 'rss'
$path : string: The path to the asset
$attributes : array<string|int, mixed>: The attributes for the asset

Return values

mixed —

execAjaxHandlers()

Executes the page, layout, component and plugin AJAX handlers.


    protected
                execAjaxHandlers() : mixed

Return values

mixed —

Returns the AJAX Response object or null.

execPageCycle()

Executes the page life cycle.


    protected
                execPageCycle() : mixed

Creates an object from the PHP sections of the page and it's layout, then executes their life cycle functions.

Return values

mixed —

getAssetEntryBuildPath()

Internal helper, attaches a build code to an asset path


    protected
                getAssetEntryBuildPath(array<string|int, mixed> $asset) : string

Parameters

$asset : array<string|int, mixed>: Stored asset array

Return values

string —

getAssetScheme()

Internal helper, get asset scheme


    protected
                getAssetScheme(string $asset) : string

Parameters

$asset : string: Specifies a path (URL) to the asset.

Return values

string —

getLocalPath()


    protected
                getLocalPath(string $relativePath) : mixed

Parameters

$relativePath : string

Return values

mixed —

initComponents()

Initializes the components for the layout and page.


    protected
                initComponents() : void

Return values

void —

initCustomObjects()

Initializes the custom layout and page objects.


    protected
                initCustomObjects() : void

Return values

void —

initTwigEnvironment()

Initializes the Twig environment and loader.


    protected
                initTwigEnvironment() : void

Registers the \Cms\Twig\Extension object with Twig.

Return values

void —

isSoftComponent()

Checks if component name has @.


    protected
                isSoftComponent(string $label) : bool

Parameters

$label : string

Return values

bool —

makeXsrfCookie()

Adds anti-CSRF cookie.


    protected
                makeXsrfCookie() : Cookie

Adds a cookie with a token for CSRF checks to the response.

Return values

Cookie —

parseComponentLabel()

Removes prefixed '@' from soft component name


    protected
                parseComponentLabel(string $label) : string

Parameters

$label : string

Return values

string —

postProcessResult()

Post-processes page HTML code before it's sent to the client.


    protected
                postProcessResult(Page $page, string $url, string $content) : string

Note for pre-processing see cms.template.processTwigContent event.

Parameters

$page : Page: Specifies the current CMS page.
$url : string: Specifies the current URL.
$content : string: The page markup to post-process.

Return values

string —

Returns the updated result string.

removeDuplicates()

Removes duplicate assets from the entire collection.


    protected
                removeDuplicates() : void

Return values

void —

runAjaxHandler()

Tries to find and run an AJAX handler in the page, layout, components and plugins.


    protected
                runAjaxHandler(string $handler) : bool

The method stops as soon as the handler is found.

Parameters

$handler : string: name of the ajax handler

Return values

bool —

Returns true if the handler was found. Returns false otherwise.

setComponentPropertiesFromParams()

Sets component property values from partial parameters.


    protected
                setComponentPropertiesFromParams(ComponentBase $component[, array<string|int, mixed> $parameters = [] ]) : mixed

The property values should be defined as {{ param }}.

Parameters

$component : ComponentBase: The component object.
$parameters : array<string|int, mixed> = []: Specifies the partial parameters.

Return values

mixed —

verifyCsrfToken()

Checks the request data / headers for a valid CSRF token.


    protected
                verifyCsrfToken() : bool

Returns false if a valid token is not found. Override this method to disable the check.

Return values

bool —

verifyForceSecure()

Checks if the back-end should force a secure protocol (HTTPS) enabled by config.


    protected
                verifyForceSecure() : bool

Return values

bool —