Class UrlHelper

UrlHelper class for generating URLs.

Namespace: Cake\View\Helper

Property Summary

$_View protected

Cake\View\View

The View instance this helper is attached to
$_assetUrlClassName protected

string

Asset URL engine class name
$_config protected

array<string, mixed>

Runtime config
$_configInitialized protected

bool

Whether the config property has already been configured with defaults
$_defaultConfig protected

array<string, mixed>

Default config for this class
$helperInstances protected

array<string,Cake\View\Helper>

Loaded helper instances.
$helpers protected

array

List of helpers used by this helper

Method Summary

__construct() public

Default Constructor
__debugInfo() public

Returns an array that can be used to describe the internal state of this object.
__get() public

Lazy loads helpers.
_configDelete() protected

Deletes a single config key.
_configRead() protected

Reads a config key.
_configWrite() protected

Writes a config key.
_confirm() protected

Returns a string to be used as onclick handler for confirm dialogs.
addClass() public

Adds the given class to the element options
assetTimestamp() public

Adds a timestamp to a file based resource based on the value of Asset.timestamp in Configure. If Asset.timestamp is true and debug is true, or Asset.timestamp === 'force' a timestamp will be added.
assetUrl() public

Generates URL for given asset file.
build() public

Returns a URL based on provided parameters.
buildFromPath() public

Returns a URL from a route path string.
configShallow() public

Merge provided config with existing config. Unlike config() which does a recursive merge for nested keys, this method does a simple merge.
css() public

Generates URL for given CSS file.
getConfig() public

Returns the config.
getConfigOrFail() public

Returns the config for this specific key.
getView() public

Get the view instance this helper is bound to.
image() public

Generates URL for given image file.
implementedEvents() public

Event listeners.
initialize() public

Check proper configuration
script() public

Generates URL for given javascript file.
setConfig() public

Sets the config.
webroot() public

Checks if a file exists when theme is used, if no file is found default location is returned

Method Detail

__construct() ¶ public

__construct(Cake\View\View $view, array<string, mixed> $config = [])

Default Constructor

Parameters

Cake\View\View $view: The View this helper is being attached to.
array<string, mixed> $config optional: Configuration settings for the helper.

__debugInfo() ¶ public

__debugInfo(): array<string, mixed>

Returns an array that can be used to describe the internal state of this object.

Returns

array<string, mixed>

__get() ¶ public

__get(string $name): Cake\View\Helper|null

Lazy loads helpers.

Parameters

string $name: Name of the property being accessed.

Returns

Cake\View\Helper|null

_configDelete() ¶ protected

_configDelete(string $key): void

Deletes a single config key.

Parameters

string $key: Key to delete.

Returns

void

Throws

Cake\Core\Exception\CakeException
if attempting to clobber existing config

_configRead() ¶ protected

_configRead(string|null $key): mixed

Reads a config key.

Parameters

string|null $key: Key to read.

Returns

mixed

_configWrite() ¶ protected

_configWrite(array<string, mixed>|string $key, mixed $value, string|bool $merge = false): void

Writes a config key.

Parameters

array<string, mixed>|string $key: Key to write to.
mixed $value: Value to write.
string|bool $merge optional: True to merge recursively, 'shallow' for simple merge, false to overwrite, defaults to false.

Returns

void

Throws

Cake\Core\Exception\CakeException
if attempting to clobber existing config

_confirm() ¶ protected

_confirm(string $okCode, string $cancelCode): string

Returns a string to be used as onclick handler for confirm dialogs.

Parameters

string $okCode: Code to be executed after user chose 'OK'
string $cancelCode: Code to be executed after user chose 'Cancel'

Returns

string

addClass() ¶ public

addClass(array<string, mixed> $options, string $class, string $key = 'class'): array<string, mixed>

Adds the given class to the element options

Parameters

array<string, mixed> $options: Array options/attributes to add a class to
string $class: The class name being added.
string $key optional: the key to use for class. Defaults to 'class'.

Returns

array<string, mixed>

assetTimestamp() ¶ public

assetTimestamp(string $path, string|bool $timestamp = null): string

Adds a timestamp to a file based resource based on the value of Asset.timestamp in Configure. If Asset.timestamp is true and debug is true, or Asset.timestamp === 'force' a timestamp will be added.

Parameters

string $path: The file path to timestamp, the path must be inside App.wwwRoot in Configure.
string|bool $timestamp optional: If set will overrule the value of Asset.timestamp in Configure.

Returns

string

assetUrl() ¶ public

assetUrl(string $path, array<string, mixed> $options = []): string

Generates URL for given asset file.

Depending on options passed provides full URL with domain name. Also calls Helper::assetTimestamp() to add timestamp to local files.

Options:

fullBase Boolean true or a string (e.g. https://example) to return full URL with protocol and domain name.
pathPrefix Path prefix for relative URLs
ext Asset extension to append
plugin False value will prevent parsing path as a plugin
timestamp Overrides the value of Asset.timestamp in Configure. Set to false to skip timestamp generation. Set to true to apply timestamps when debug is true. Set to 'force' to always enable timestamping regardless of debug value.

Parameters

string $path: Path string or URL array
array<string, mixed> $options optional: Options array.

Returns

string

build() ¶ public

build(array|string|null $url = null, array<string, mixed> $options = []): string

Returns a URL based on provided parameters.

Options:

escape: If false, the URL will be returned unescaped, do only use if it is manually escaped afterwards before being displayed.
fullBase: If true, the full base URL will be prepended to the result

Parameters

array|string|null $url optional: Either a relative string URL like /products/view/23 or an array of URL parameters. Using an array for URLs will allow you to leverage the reverse routing features of CakePHP.
array<string, mixed> $options optional: Array of options.

Returns

string

buildFromPath() ¶ public

buildFromPath(string $path, array $params = [], array<string, mixed> $options = []): string

Returns a URL from a route path string.

Options:

escape: If false, the URL will be returned unescaped, do only use if it is manually escaped afterwards before being displayed.
fullBase: If true, the full base URL will be prepended to the result

Parameters

string $path: Cake-relative route path.
array $params optional: An array specifying any additional parameters. Can be also any special parameters supported by Router::url().
array<string, mixed> $options optional: Array of options.

Returns

string

configShallow() ¶ public

configShallow(array<string, mixed>|string $key, mixed|null $value = null): $this

Merge provided config with existing config. Unlike config() which does a recursive merge for nested keys, this method does a simple merge.

Setting a specific value:

$this->configShallow('key', $value);

Setting a nested value:

$this->configShallow('some.nested.key', $value);

Updating multiple config settings at the same time:

$this->configShallow(['one' => 'value', 'another' => 'value']);

Parameters

array<string, mixed>|string $key: The key to set, or a complete array of configs.
mixed|null $value optional: The value to set.

Returns

$this

css() ¶ public

css(string $path, array<string, mixed> $options = []): string

Generates URL for given CSS file.

Depending on options passed provides full URL with domain name. Also calls Helper::assetTimestamp() to add timestamp to local files.

Parameters

string $path: Path string.
array<string, mixed> $options optional: Options array. Possible keys: fullBase Return full URL with domain name pathPrefix Path prefix for relative URLs ext Asset extension to append plugin False value will prevent parsing path as a plugin timestamp Overrides the value of Asset.timestamp in Configure. Set to false to skip timestamp generation. Set to true to apply timestamps when debug is true. Set to 'force' to always enable timestamping regardless of debug value.

Returns

string

getConfig() ¶ public

getConfig(string|null $key = null, mixed $default = null): mixed

Returns the config.

Usage

Reading the whole config:

$this->getConfig();

Reading a specific value:

$this->getConfig('key');

Reading a nested value:

$this->getConfig('some.nested.key');

Reading with default value:

$this->getConfig('some-key', 'default-value');

Parameters

string|null $key optional: The key to get or null for the whole config.
mixed $default optional: The return value when the key does not exist.

Returns

mixed

getConfigOrFail() ¶ public

getConfigOrFail(string $key): mixed

Returns the config for this specific key.

The config value for this key must exist, it can never be null.

Parameters

string $key: The key to get.

Returns

mixed

Throws

InvalidArgumentException

getView() ¶ public

getView(): Cake\View\View

Get the view instance this helper is bound to.

Returns

Cake\View\View

image() ¶ public

image(string $path, array<string, mixed> $options = []): string

Generates URL for given image file.

Depending on options passed provides full URL with domain name. Also calls Helper::assetTimestamp() to add timestamp to local files.

Parameters

string $path: Path string.
array<string, mixed> $options optional: Options array. Possible keys: fullBase Return full URL with domain name pathPrefix Path prefix for relative URLs plugin False value will prevent parsing path as a plugin timestamp Overrides the value of Asset.timestamp in Configure. Set to false to skip timestamp generation. Set to true to apply timestamps when debug is true. Set to 'force' to always enable timestamping regardless of debug value.

Returns

string

implementedEvents() ¶ public

implementedEvents(): array<string, mixed>

Event listeners.

By defining one of the callback methods a helper is assumed to be interested in the related event.

Override this method if you need to add non-conventional event listeners. Or if you want helpers to listen to non-standard events.

Returns

array<string, mixed>

initialize() ¶ public

initialize(array<string, mixed> $config): void

Check proper configuration

Implement this method to avoid having to overwrite the constructor and call parent.

Parameters

array<string, mixed> $config: The configuration settings provided to this helper.

Returns

void

script() ¶ public

script(string $path, array<string, mixed> $options = []): string

Generates URL for given javascript file.

Depending on options passed provides full URL with domain name. Also calls Helper::assetTimestamp() to add timestamp to local files.

Parameters

string $path: Path string.
array<string, mixed> $options optional: Options array. Possible keys: fullBase Return full URL with domain name pathPrefix Path prefix for relative URLs ext Asset extension to append plugin False value will prevent parsing path as a plugin timestamp Overrides the value of Asset.timestamp in Configure. Set to false to skip timestamp generation. Set to true to apply timestamps when debug is true. Set to 'force' to always enable timestamping regardless of debug value.

Returns

string

setConfig() ¶ public

setConfig(array<string, mixed>|string $key, mixed|null $value = null, bool $merge = true): $this

Sets the config.

Usage

Setting a specific value:

$this->setConfig('key', $value);

Setting a nested value:

$this->setConfig('some.nested.key', $value);

Updating multiple config settings at the same time:

$this->setConfig(['one' => 'value', 'another' => 'value']);

Parameters

array<string, mixed>|string $key: The key to set, or a complete array of configs.
mixed|null $value optional: The value to set.
bool $merge optional: Whether to recursively merge or overwrite existing config, defaults to true.

Returns

$this

Throws

Cake\Core\Exception\CakeException
When trying to set a key that is invalid.

webroot() ¶ public

webroot(string $file): string

Checks if a file exists when theme is used, if no file is found default location is returned

Parameters

string $file: The file to create a webroot path to.

Returns

string

Property Detail

`$_View` ¶ protected

The View instance this helper is attached to

Type

Cake\View\View

`$_assetUrlClassName` ¶ protected

Asset URL engine class name

Type

string

`$_config` ¶ protected

Runtime config

Type

array<string, mixed>

`$_configInitialized` ¶ protected

Whether the config property has already been configured with defaults

Type

bool

`$_defaultConfig` ¶ protected

Default config for this class

Type

array<string, mixed>

`$helperInstances` ¶ protected

Loaded helper instances.

Type

array<string,Cake\View\Helper>

`$helpers` ¶ protected

List of helpers used by this helper

Type

array

Namespaces

Class UrlHelper

Property Summary

Method Summary

__construct() public

__debugInfo() public

__get() public

_configDelete() protected

_configRead() protected

_configWrite() protected

_confirm() protected

addClass() public

assetTimestamp() public

assetUrl() public

build() public

buildFromPath() public

configShallow() public

css() public

getConfig() public

getConfigOrFail() public

getView() public

image() public

implementedEvents() public

initialize() public

script() public

setConfig() public

webroot() public

Method Detail

__construct() ¶ public

Parameters

__debugInfo() ¶ public

Returns

__get() ¶ public

Parameters

Returns

_configDelete() ¶ protected

Parameters

Returns

Throws

_configRead() ¶ protected

Parameters

Returns

_configWrite() ¶ protected

Parameters

Returns

Throws

_confirm() ¶ protected

Parameters

Returns

addClass() ¶ public

Parameters

Returns

assetTimestamp() ¶ public

Parameters

Returns

assetUrl() ¶ public

Options:

Parameters

Returns

build() ¶ public

Options:

Parameters

Returns

buildFromPath() ¶ public

Options:

Parameters

Returns

See Also

configShallow() ¶ public

Parameters

Returns

css() ¶ public

Parameters

Returns

getConfig() ¶ public

Usage

Parameters

Returns

getConfigOrFail() ¶ public

Parameters

`$_View` ¶ protected

`$_assetUrlClassName` ¶ protected

`$_config` ¶ protected

`$_configInitialized` ¶ protected

`$_defaultConfig` ¶ protected

`$helperInstances` ¶ protected

`$helpers` ¶ protected