Cms\Classes\Controller

Source: ~/modules/cms/classes/Controller.php

The CMS controller class. The controller finds and serves requested pages.

Public properties

public array $vars

A list of variables to pass to the page.

public string $assetPath

Specifies a path to the asset directory.

Protected properties

protected Cms\Classes\Theme $theme

A reference to the CMS theme processed by the controller.

protected Cms\Classes\Router $router

A reference to the Router object.

protected Cms\Twig\Loader $loader

A reference to the Twig template loader.

protected Cms\Classes\Page $page

A reference to the CMS page template being processed.

protected Cms\Classes\CodeBase $pageObj

A reference to the CMS page code section object.

protected Cms\Classes\Layout $layout

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

protected Cms\Classes\CodeBase $layoutObj

A reference to the CMS layout code section object.

protected TwigEnvironment $twig

Keeps the Twig environment object.

protected string $pageContents

Contains the rendered page contents string.

protected static self $instance

Cache of self

protected Cms\Classes\ComponentBase $componentContext

Object of the active component, used internally.

protected array $partialStack

Component partial stack, used internally.

protected array $assets

Collection of assets to display in the layout.

protected array $emitterSingleEventCollection

Collection of registered events to be fired once only.

protected array $emitterEventCollection

Collection of registered events.

protected array $emitterEventSorted

Sorted collection of events.

protected int $statusCode

Response status code

protected mixed $responseOverride

Override the standard controller response.

protected Symfony\Component\HttpFoundation\ResponseHeaderBag $responseHeaderBag

Public methods

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

Creates the controller.

Parameters

• Cms\Classes\Theme $theme - Specifies the CMS theme. If the theme is not specified, the current active theme used.

public ComponentBase addComponent(mixed $name, string $alias, array $properties, bool $addToLayout=false)

Adds a component to the page object

Parameters

• mixed $name - Component class name or short name
• string $alias - Alias to give the component
• array $properties - Component properties
• bool $addToLayout - Add to layout, instead of page

public void addCss(string $name, array $attributes=array())

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

Parameters

• string $name - Specifies a path (URL) to the script.
• array $attributes - Adds extra HTML attributes to the asset link.

public void addJs(string $name, array $attributes=array())

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

Parameters

• string $name - Specifies a path (URL) to the script.
• array $attributes - Adds extra HTML attributes to the asset link.

public void addRss(string $name, array $attributes=array())

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

Parameters

• string $name - Specifies a path (URL) to the RSS channel
• array $attributes - Adds extra HTML attributes to the asset link.

public self bindEvent($event, $callback, $priority=0)

Create a new event binding.

Parameters

• $event
• $callback
• $priority

public self bindEventOnce($event, $callback)

Create a new event binding that fires once only

Parameters

• $event
• $callback

public string combineAssets(array $assets, string $localPath='')

Run the provided assets through the Asset Combiner

Parameters

• array $assets - Collection of assets
• string $localPath - Prefix all assets with this path (optional)

public null|string currentPageUrl(array $parameters=array(), bool $routePersistence=true)

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

Parameters

• array $parameters
• bool $routePersistence

public ComponentBase findComponentByHandler(string $handler)

Searches the layout and page components by an AJAX handler

Parameters

• string $handler

public ComponentBase findComponentByName($name $name)

Searches the layout and page components by an alias

Parameters

• $name $name

public ComponentBase findComponentByPartial(string $partial)

Searches the layout and page components by a partial file

Parameters

• string $partial

public array fireEvent(string $event, array $params=array(), boolean $halt=false)

Fire an event and call the listeners.

Parameters

• string $event - Event name
• array $params - Event parameters
• boolean $halt - Halt after first non-null result

public mixed fireSystemEvent(string $event, array $params=array(), boolean $halt=true)

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

• string $event - Event name
• array $params - Event parameters
• boolean $halt - Halt after first non-null result

public string fireViewEvent(string $event, array $params=array())

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

For example:

<?= $this->fireViewEvent('backend.auth.extendSigninView') ?>

Parameters

• string $event - Event name
• array $params - Event parameters

public void 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 string getAjaxHandler()

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

public string getAssetPath(string $fileName, string $assetPath=NULL)

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.

Parameters

• string $fileName - File to load.
• string $assetPath - Explicitly define an asset path.

public array getAssetPaths()

Returns an array of all registered asset paths.

public static mixed getController()

Returns an existing instance of the controller. If the controller doesn't exists, returns null.

public Cms\Classes\Layout getLayout()

Returns the CMS layout object being processed by the controller. The object is not available on the early stages of the controller initialization.

public Cms\Classes\CodeBase getLayoutObject()

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

public Cms\Twig\Loader getLoader()

Returns the Twig loader.

public Cms\Classes\Page getPage()

Returns the CMS page object being processed by the controller. The object is not available on the early stages of the controller initialization.

public Cms\Classes\CodeBase getPageObject()

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

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

Get the header response bag

public Cms\Classes\Router getRouter()

Returns the routing object.

public int getStatusCode()

Returns the status code for the current web response.

public Cms\Classes\Theme getTheme()

Returns the current CMS theme.

public TwigEnvironment getTwig()

Returns the Twig environment.

public bool hasAssetsDefined()

Returns true if assets any have been added.

public string makeAssets(string $type=NULL)

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

Parameters

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

public mixed makeResponse(mixed $contents)

Prepares a response that considers overrides and custom responses.

Parameters

• mixed $contents

public void pageCycle()

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

public string pageUrl(mixed $name, array $parameters=array(), bool $routePersistence=true)

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

Parameters

• mixed $name - Specifies the Cms Page file name.
• array $parameters - Route parameters to consider in the URL.
• bool $routePersistence - By default the existing routing parameters will be included

public string param(string $name, string $default=NULL)

Returns a routing parameter.

Parameters

• string $name - Routing parameter name.
• string $default - Default to use if none is found.

public static void render(string $pageFile, array $parameters=array(), Cms\Classes\Theme $theme=NULL)

Renders a page in its entirety, including component initialization. AJAX will be disabled for this process.

Parameters

• string $pageFile - Specifies the CMS page file name to run.
• array $parameters - Routing parameters.
• Cms\Classes\Theme $theme - Theme object

public string renderComponent($name $name, array $parameters=array())

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

Parameters

• $name $name
• array $parameters

public string renderContent(string $name, array $parameters=array())

Renders a requested content file. The framework uses this method internally.

Parameters

• string $name - The content view to load.
• array $parameters - Parameter variables to pass to the view.

public void renderPage()

Renders a requested page. The framework uses this method internally.

public mixed renderPartial(string $name, array $parameters=array(), bool $throwException=true)

Renders a requested partial. The framework uses this method internally.

Parameters

• string $name - The view to load.
• array $parameters - Parameter variables to pass to the view.
• bool $throwException - Throw an exception if the partial is not found.

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

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

• string|null $url - Specifies the requested page URL.

public string runPage(Cms\Classes\Page $page, $useAjax=true)

Runs a page directly from its object and supplied parameters.

Parameters

• Cms\Classes\Page $page - Specifies the CMS page to run.
• $useAjax

public void setComponentContext(ComponentBase $component=NULL)

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

Parameters

• ComponentBase $component

public $this setResponse(mixed $response)

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

Parameters

• mixed $response - Response object or string

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

Add a cookie to the response.

Parameters

• Symfony\Component\HttpFoundation\Cookie|mixed $cookie

public $this setResponseHeader(string $key, array|string $values, bool $replace=true)

Set a header on the Response.

Parameters

• string $key
• array|string $values
• bool $replace

public $this setStatusCode(int $code)

Sets the status code for the current web response.

Parameters

• int $code - Status code

public string themeUrl(mixed $url=NULL)

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

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

public self unbindEvent(string $event=NULL)

Destroys an event binding.

Parameters

• string $event - Event to destroy

Protected methods

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

Adds the provided asset to the internal asset collections

Parameters

• string $type - The type of the asset: 'js' || 'css' || 'rss'
• string $path - The path to the asset
• array $attributes - The attributes for the asset

protected array emitterEventSortEvents(string $eventName)

Sort the listeners for a given event by priority.

Parameters

• string $eventName

protected mixed execAjaxHandlers()

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

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

protected string getAssetEntryBuildPath(array $asset)

Internal helper, attaches a build code to an asset path

Parameters

• array $asset - Stored asset array

protected string getAssetScheme(string $asset)

Internal helper, get asset scheme

Parameters

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

protected void getLocalPath($relativePath)

Parameters

• $relativePath

protected void initComponents()

Initializes the components for the layout and page.

protected void initCustomObjects()

Initializes the custom layout and page objects.

protected void initTwigEnvironment()

Initializes the Twig environment and loader. Registers the \Cms\Twig\Extension object with Twig.

protected Symfony\Component\HttpFoundation\Cookie makeXsrfCookie()

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

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

Post-processes page HTML code before it's sent to the client. Note for pre-processing see cms.template.processTwigContent event.

Parameters

• Cms\Classes\Page $page - Specifies the current CMS page.
• string $url - Specifies the current URL.
• string $content - The page markup to post-process.

protected void removeDuplicates()

Removes duplicate assets from the entire collection.

protected boolean runAjaxHandler(string $handler)

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

• string $handler - Name of the ajax handler

protected void setComponentPropertiesFromParams(ComponentBase $component, array $parameters=array())

Sets component property values from partial parameters. The property values should be defined as {{ param }}.

Parameters

• ComponentBase $component - The component object.
• array $parameters - Specifies the partial parameters.

protected bool verifyCsrfToken()

Checks the request data / headers for a valid CSRF token. Returns false if a valid token is not found. Override this method to disable the check.

protected bool verifyForceSecure()

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