Controller

The CMS controller class.

 class Cms\Classes\Controller

The controller finds and serves requested pages.

Traits

Trait Description
AssetMaker

Asset Maker Trait Adds asset based methods to a class

EventEmitter

Adds system event related features to any class.

ResponseMaker

Response Maker Trait Stores attributes the can be used to prepare a response from the server.

SecurityController

Security Controller Trait Adds cross-site scripting protection methods to a controller based class

Properties

public $vars : array

A list of variables to pass to the page.

protected $componentContext : Cms\Classes\ComponentBase

Object of the active component, used internally.

protected static $instance : self

Cache of self

protected $layout : Cms\Classes\Layout

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

protected $layoutObj : Cms\Classes\CodeBase

A reference to the CMS layout code section object.

protected $page : Cms\Classes\Page

A reference to the CMS page template being processed.

protected $pageContents : string

Contains the rendered page contents string.

protected $pageObj : Cms\Classes\CodeBase

A reference to the CMS page code section object.

protected $partialStack : PartialStack

Component partial stack, used internally.

protected $router : Cms\Classes\Router

A reference to the Router object.

protected $theme : Cms\Classes\Theme

A reference to the CMS theme processed by the controller.

protected $twig : TwigEnvironment

Keeps the Twig environment object.

inherited public $assetPath : string

Inherited from AssetMaker

Specifies a path to the asset directory.

inherited protected $assets : array

Inherited from AssetMaker

Collection of assets to display in the layout.

inherited protected $orderFactor : integer

Inherited from AssetMaker

Ensures "first-come, first-served" applies to assets of the same ordering.

inherited protected $responseHeaderBag : Symfony\Component\HttpFoundation\ResponseHeaderBag

Inherited from ResponseMaker

inherited protected $responseOverride : mixed

Inherited from ResponseMaker

Override the standard controller response.

inherited protected $statusCode : int

Inherited from ResponseMaker

Response status code

Methods

public __construct (Cms\Classes\Theme $theme = null) : void

Creates the controller.

Parameters
Property Description
$theme

Specifies the CMS theme. If the theme is not specified, the current active theme used.

Returns
void

public addComponent (mixed $name, string $alias, array $properties, boolean $addToLayout = false) : ComponentBase | null

Adds a component to the page object.

Parameters
Property Description
$name
mixed

Component class name or short name

$alias
string

Alias to give the component

$properties
array

Component properties

$addToLayout
boolean

Add to layout, instead of page

Returns
ComponentBase | null

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

public currentPageUrl (array $parameters = [], boolean $routePersistence = true) : null | string

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

Parameters
Property Description
$parameters
array
$routePersistence
boolean
Returns
null | string

public findComponentByHandler (string $handler) : ComponentBase

Searches the layout and page components by an AJAX handler

Parameters
Property Description
$handler
string
Returns
ComponentBase

The component object, if found

public findComponentByName (mixed $name) : ComponentBase

Searches the layout and page components by an alias

Parameters
Property Description
$name
mixed
Returns
ComponentBase

The component object, if found

public findComponentByPartial (string $partial) : ComponentBase | null

Searches the layout and page components by a partial file

Parameters
Property Description
$partial
string
Returns
ComponentBase | null

The component object, if found

public getAjaxHandler () : string

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

Returns
string

public static getController () : self | null

Returns an existing instance of the controller.

If the controller doesn't exists, returns null.

Returns
self | null

public getLayout () : Cms\Classes\Layout

Returns the CMS layout object being processed by the controller.

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

Returns

Returns the Layout object or null.

public getLayoutObject () : Cms\Classes\CodeBase

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

Returns

public getLoader () : Cms\Twig\Loader

Returns the Twig loader.

Returns

public getPage () : Cms\Classes\Page

Returns the CMS page object being processed by the controller.

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

Returns

Returns the Page object or null.

public getPageObject () : Cms\Classes\CodeBase

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

Returns

public getRouter () : Cms\Classes\Router

Returns the routing object.

Returns

public getTheme () : Cms\Classes\Theme

Returns the current CMS theme.

Returns

public getTwig () : TwigEnvironment

Returns the Twig environment.

Returns
TwigEnvironment

public pageCycle ()

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

Returns
mixed

public pageUrl (mixed $name, array $parameters = [], boolean $routePersistence = true) : string | null

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

Parameters
Property Description
$name
mixed

Specifies the Cms Page file name.

$parameters
array

Route parameters to consider in the URL. If boolean will be used as the value for $routePersistence

$routePersistence
boolean

By default the existing routing parameters will be included

Returns
string | null

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

Returns a routing parameter.

Parameters
Property Description
$name
string

Routing parameter name.

$default
string

Default to use if none is found.

Returns
string

public static render (string $pageFile, array $parameters = [], Cms\Classes\Theme $theme = null) : mixed

Renders a page in its entirety, including component initialization.

AJAX will be disabled for this process.

Parameters
Property Description
$pageFile
string

Specifies the CMS page file name to run.

$parameters
array

Routing parameters.

$theme

Theme object

Returns
mixed

public renderComponent (mixed $name, array $parameters = []) : string

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

Parameters
Property Description
$name
mixed
$parameters
array
Returns
string

Returns the component default contents.

public renderContent (string $name, array $parameters = [], boolean $throwException = true) : string | false

Renders a requested content file.

The framework uses this method internally.

Parameters
Property Description
$name
string

The content view to load.

$parameters
array

Parameter variables to pass to the view.

$throwException
boolean

Throw an exception if the content file is not found.

Returns
string | false

Content file, or false if $throwException is false.

public renderPage ()

Renders a requested page.

The framework uses this method internally.

Returns
mixed

public renderPartial (string $name, array $parameters = [], boolean $throwException = true) : mixed

Renders a requested partial.

The framework uses this method internally.

Parameters
Property Description
$name
string

The view to load.

$parameters
array

Parameter variables to pass to the view.

$throwException
boolean

Throw an exception if the partial is not found.

Returns
mixed

Partial contents or false if not throwing an exception.

public run (string $url = "\/") : BaseResponse

Finds and serves the requested page.

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
Property Description
$url
string

Specifies the requested page URL.

Returns
BaseResponse

Returns the response to the provided URL

public runPage (Cms\Classes\Page $page, boolean $useAjax = true) : mixed

Runs a page directly from its object and supplied parameters.

Parameters
Property Description
$page

Specifies the CMS page to run.

$useAjax
boolean
Returns
mixed

public setComponentContext (ComponentBase $component = null) : void

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

Parameters
Property Description
$component
ComponentBase
Returns
void

public themeUrl (mixed $url = null) : string

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.

Parameters
Property Description
$url
mixed

Specifies the theme-relative URL. If null, the theme path is returned.

Returns
string

protected execAjaxHandlers () : mixed

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

Returns
mixed

Returns the AJAX Response object or null.

protected execPageCycle ()

Executes the page life cycle.

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

Returns
mixed

protected initComponents () : void

Initializes the components for the layout and page.

Returns
void

protected initCustomObjects () : void

Initializes the custom layout and page objects.

Returns
void

protected initTwigEnvironment () : void

Initializes the Twig environment and loader.

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

Returns
void

protected isSoftComponent (string $label) : bool

Checks if component name has @.

Parameters
Property Description
$label
string
Returns
bool

protected parseComponentLabel (string $label) : string

Removes prefixed '@' from soft component name

Parameters
Property Description
$label
string
Returns
string

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

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

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

Parameters
Property Description
$page

Specifies the current CMS page.

$url
string

Specifies the current URL.

$content
string

The page markup to post-process.

Returns
string

Returns the updated result string.

protected runAjaxHandler (string $handler) : bool

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

The method stops as soon as the handler is found.

Parameters
Property Description
$handler
string

name of the ajax handler

Returns
bool

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

protected setComponentPropertiesFromParams (ComponentBase $component, array $parameters = [])

Sets component property values from partial parameters.

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

Parameters
Property Description
$component
ComponentBase

The component object.

$parameters
array

Specifies the partial parameters.

Returns
mixed

protected themeCombineAssets (array $url) : string

Generates a URL to the AssetCombiner for the provided array of assets

Parameters
Property Description
$url
array
Returns
string

inherited public addCss (string | array $name, array $attributes = []) : void

Inherited from AssetMaker

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

Parameters
Property Description
$name
string | array

When an array of paths are provided they will be passed to the Asset Combiner

$attributes
array

When a string is provided it will be used as the 'build' attribute value

Returns
void

inherited public addJs (string | array $name, array $attributes = []) : void

Inherited from AssetMaker

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

Parameters
Property Description
$name
string | array

When an array of paths are provided they will be passed to the Asset Combiner

$attributes
array

When a string is provided it will be used as the 'build' attribute value

Returns
void

inherited public addRss (string $name, array $attributes = []) : void

Inherited from AssetMaker

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

Parameters
Property Description
$name
string
$attributes
array
Returns
void

inherited public addVite (array | string $entrypoints, ?string $package = null) : void

Inherited from AssetMaker

Adds Vite tags

Parameters
Property Description
$entrypoints
array | string

The list of entry points for Vite

$package
?string

The package name of the plugin or theme

Returns
void

inherited public combineAssets (array $assets, string $localPath = "") : string

Inherited from AssetMaker

Run the provided assets through the Asset Combiner

Parameters
Property Description
$assets
array
$localPath
string
Returns
string

inherited public fireSystemEvent (string $event, array $params = [], boolean $halt = true) : mixed

Inherited from EventEmitter

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.

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
Property Description
$event
string

Event name

$params
array

Event parameters

$halt
boolean

Halt after first non-null result

Returns
mixed

inherited public fireViewEvent (string $event, array $params = []) : string

Inherited from EventEmitter

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

For example:

= $this->fireViewEvent('backend.auth.extendSigninView') ?>
Parameters
Property Description
$event
string

Event name

$params
array

Event parameters

Returns
string

inherited public flushAssets () : void

Inherited from AssetMaker

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.

Returns
void

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

Inherited from AssetMaker

Returns the URL to the provided asset. If the provided fileName is a relative path without a leading slash it will be assumbed to be relative to the asset path.

Parameters
Property Description
$fileName
string
$assetPath
mixed
Returns
string

inherited public getAssetPaths () : array

Inherited from AssetMaker

Returns an array of all registered asset paths.

Assets will be prioritized based on their defined ordering.

Returns
array

inherited public getResponseHeaders () : Symfony\Component\HttpFoundation\ResponseHeaderBag | null

Inherited from ResponseMaker

Get the header response bag

Returns
Symfony\Component\HttpFoundation\ResponseHeaderBag | null

inherited public getStatusCode () : int

Inherited from ResponseMaker

Returns the status code for the current web response.

Returns
int

Status code

inherited public hasAssetsDefined () : bool

Inherited from AssetMaker

Returns true if assets any have been added.

Returns
bool

inherited public makeAssets ($type = null) : string | null

Inherited from AssetMaker

Outputs <link> and <script> tags to load assets previously added with addJs, addCss, & addRss method calls depending on the provided $type

Parameters
Property Description
$type
mixed
Returns
string | null

inherited public makeResponse (mixed $contents) : mixed

Inherited from ResponseMaker

Prepares a response that considers overrides and custom responses.

Parameters
Property Description
$contents
mixed
Returns
mixed

inherited public orderAssets (array $assets) : array

Inherited from AssetMaker

Prioritize assets based on the given order.

Parameters
Property Description
$assets
array
Returns
array

inherited public setResponse (mixed $response) : $this

Inherited from ResponseMaker

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

Parameters
Property Description
$response
mixed

Response object or string

Returns
$this

inherited public setResponseCookie (Symfony\Component\HttpFoundation\Cookie | mixed $cookie) : $this

Inherited from ResponseMaker

Add a cookie to the response.

Parameters
Property Description
$cookie
Symfony\Component\HttpFoundation\Cookie | mixed
Returns
$this

inherited public setResponseHeader (string $key, array | string $values, boolean $replace = true) : $this

Inherited from ResponseMaker

Set a header on the Response.

Parameters
Property Description
$key
string
$values
array | string
$replace
boolean
Returns
$this

inherited public setStatusCode (int $code) : $this

Inherited from ResponseMaker

Sets the status code for the current web response.

Parameters
Property Description
$code
int

Status code

Returns
$this

inherited protected addAsset (string $type, string $path, array $attributes) : void

Inherited from AssetMaker

Adds the provided asset to the internal asset collections

Parameters
Property Description
$type
string
$path
string
$attributes
array
Returns
void

inherited protected getAssetEntryBuildPath (array $asset) : string

Inherited from AssetMaker

Internal helper, attaches a build code to an asset path

Parameters
Property Description
$asset
array
Returns
string

inherited protected getAssetScheme (string $asset) : string

Inherited from AssetMaker

Internal helper, get asset scheme

Parameters
Property Description
$asset
string
Returns
string

inherited protected getLocalPath (string | null $relativePath) : string

Inherited from AssetMaker
Parameters
Property Description
$relativePath
string | null
Returns
string

inherited protected makeXsrfCookie () : Symfony\Component\HttpFoundation\Cookie

Inherited from SecurityController

Adds anti-CSRF cookie.

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

Returns
Symfony\Component\HttpFoundation\Cookie

inherited protected removeDuplicates () : void

Inherited from AssetMaker

Removes duplicate assets from the entire collection.

Returns
void

inherited protected verifyCsrfToken () : bool

Inherited from SecurityController

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

Returns
bool

Returns false if a valid token is not found or cms.enableCsrfProtection is set to false

inherited protected verifyForceSecure () : bool

Inherited from SecurityController

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

Returns
bool
Copyright © 2024 Winter CMS