Theme

API reference › yii › base › Theme

class	`yii\base\Theme`
Extends	`Component` » `BaseObject`
Implements	`Configurable`
Since	2.0
Source	`framework/base/Theme.php`

Theme represents an application theme.

When View renders a view file, it will check the active theme to see if there is a themed version of the view file exists. If so, the themed version will be rendered instead.

A theme is a directory consisting of view files which are meant to replace their non-themed counterparts.

Theme uses $pathMap to achieve the view file replacement:

It first looks for a key in $pathMap that is a substring of the given view file path;
If such a key exists, the corresponding value will be used to replace the corresponding part in the view file path;
It will then check if the updated view file exists or not. If so, that file will be used to replace the original view file.
If Step 2 or 3 fails, the original view file will be used.

For example, if $pathMap is ['@app/views' => '@app/themes/basic'], then the themed version for a view file @app/views/site/index.php will be @app/themes/basic/site/index.php.

It is possible to map a single path to multiple paths. For example,

'pathMap' => [
    '@app/views' => [
        '@app/themes/christmas',
        '@app/themes/basic',
    ],
]

In this case, the themed version could be either @app/themes/christmas/site/index.php or @app/themes/basic/site/index.php. The former has precedence over the latter if both files exist.

To use a theme, you should configure the theme property of the “view” application component like the following:

'view' => [
    'theme' => [
        'basePath' => '@app/themes/basic',
        'baseUrl' => '@web/themes/basic',
    ],
],

The above configuration specifies a theme located under the “themes/basic” directory of the Web folder that contains the entry script of the application. If your theme is designed to handle modules, you may configure the $pathMap property like described above.

For more details and usage information on Theme, see the guide article on theming.

Properties

Property	Type	Description	Defined by
`$basePath`	`string`	The root path of this theme.	`Theme`
`$baseUrl`	`string\|null`	The base URL (without ending slash) for this theme.	`Theme`
`$behaviors` read-only	`array<Behavior<static>>`	List of behaviors attached to this component.	`Component`
`$pathMap`	`array\|null`	The mapping between view directories and their corresponding themed versions. Default: `null`.	`Theme`

Methods

Method	Description	Defined by
`__construct()`	Constructor.	`BaseObject`
`__call()`	Calls the named method which is not a class method.	`Component`
`__clone()`	This method is called after the object is created by cloning an existing one.	`Component`
`__get()`	Returns the value of a component property.	`Component`
`__isset()`	Checks if a property is set, i.e. defined and not null.	`Component`
`__set()`	Sets the value of a component property.	`Component`
`__unset()`	Sets a component property to be null.	`Component`
`applyTo()`	Converts a file to a themed file if possible.	`Theme`
`attachBehavior()`	Attaches a behavior to this component.	`Component`
`attachBehaviors()`	Attaches a list of behaviors to the component.	`Component`
`behaviors()`	Returns a list of behaviors that this component should behave as.	`Component`
`canGetProperty()`	Returns a value indicating whether a property can be read.	`Component`
`canSetProperty()`	Returns a value indicating whether a property can be set.	`Component`
`className()` static	Returns the fully qualified name of this class.	`BaseObject`
`detachBehavior()`	Detaches a behavior from the component.	`Component`
`detachBehaviors()`	Detaches all behaviors from the component.	`Component`
`ensureBehaviors()`	Makes sure that the behaviors declared in `behaviors()` are attached to this component.	`Component`
`getBasePath()`		`Theme`
`getBaseUrl()`		`Theme`
`getBehavior()`	Returns the named behavior object.	`Component`
`getBehaviors()`	Returns all behaviors attached to this component.	`Component`
`getPath()`	Converts a relative file path into an absolute one using `$basePath`.	`Theme`
`getUrl()`	Converts a relative URL into an absolute URL using `$baseUrl`.	`Theme`
`hasEventHandlers()`	Returns a value indicating whether there is any handler attached to the named event.	`Component`
`hasMethod()`	Returns a value indicating whether a method is defined.	`Component`
`hasProperty()`	Returns a value indicating whether a property is defined for this component.	`Component`
`init()`	Initializes the object.	`BaseObject`
`off()`	Detaches an existing event handler from this component.	`Component`
`on()`	Attaches an event handler to an event.	`Component`
`setBasePath()`		`Theme`
`setBaseUrl()`		`Theme`
`trigger()`	Triggers an event.	`Component`

Property details

$basePath

public string $basePath

The root path of this theme.

All resources of this theme are located under this directory.

$baseUrl

public string|null $baseUrl

The base URL (without ending slash) for this theme.

All resources of this theme are considered to be under this base URL.

$pathMap

public array|null $pathMap = null

The mapping between view directories and their corresponding themed versions.

This property is used by applyTo() when a view is trying to apply the theme. Path aliases can be used when specifying directories. If this property is empty or not set, a mapping Application::$basePath to $basePath will be used.

Method details

applyTo()

public function applyTo(string $path): string

Converts a file to a themed file if possible.

If there is no corresponding themed file, the original file will be returned.

Parameters

Parameter	Type	Description
`$path`	`string`	The file to be themed

Returns

string: The themed file, or the original file if the themed version is not available.

Throws

InvalidConfigException: if $basePath is not set

getBasePath()

public function getBasePath(): string

Returns

string: The root path of this theme. All resources of this theme are located under this directory.

See also

$pathMap

getBaseUrl()

public function getBaseUrl(): string|null

Returns

string|null: The base URL (without ending slash) for this theme. All resources of this theme are considered to be under this base URL.

getPath()

public function getPath(string $path): string

Converts a relative file path into an absolute one using $basePath.

Parameters

Parameter	Type	Description
`$path`	`string`	The relative file path to be converted.

Returns

string: The absolute file path

Throws

InvalidConfigException: if $basePath is not set

getUrl()

public function getUrl(string $url): string

Converts a relative URL into an absolute URL using $baseUrl.

Parameters

Parameter	Type	Description
`$url`	`string`	The relative URL to be converted.

Returns

string: The absolute URL

Throws

InvalidConfigException: if $baseUrl is not set

setBasePath()

public function setBasePath(string $path): mixed

Parameters

Parameter	Type	Description
`$path`	`string`	The root path or path alias of this theme. All resources of this theme are located under this directory.

Returns

mixed

See also

$pathMap

setBaseUrl()

public function setBaseUrl(string|null $url): mixed

Parameters

Parameter	Type	Description
`$url`	`string\|null`	The base URL or path alias for this theme. All resources of this theme are considered to be under this base URL.

Returns

mixed