# Theme

> Theme represents an application theme.

[API reference](/docs/api/index.md) › [yii](/docs/api/yii/index.md) › [base](/docs/api/yii/base/index.md) › Theme

| class | `yii\base\Theme` |
| --- | --- |
| Extends | [`Component`](/docs/api/yii/base/component/index.md) » [`BaseObject`](/docs/api/yii/base/baseobject/index.md) |
| Implements | [`Configurable`](/docs/api/yii/base/configurable/index.md) |
| Since | 2.0 |
| Source | [`framework/base/Theme.php`](https://github.com/yiisoft/yii2/blob/22.0/framework/base/Theme.php#L75) |

Theme represents an application theme.

When [`View`](/docs/api/yii/base/view/index.md) renders a view file, it will check the [active theme](/docs/api/yii/base/view/index.md#property-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`](/docs/api/yii/base/theme/index.md#property-pathMap) to achieve the view file replacement:

1. It first looks for a key in [`$pathMap`](/docs/api/yii/base/theme/index.md#property-pathMap) that is a substring of the given view file path;
2. If such a key exists, the corresponding value will be used to replace the corresponding part
   in the view file path;
3. 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.
4. If Step 2 or 3 fails, the original view file will be used.

For example, if [`$pathMap`](/docs/api/yii/base/theme/index.md#property-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](/docs/api/yii/base/view/index.md#property-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`](/docs/api/yii/base/theme/index.md#property-pathMap) property like described above.

For more details and usage information on Theme, see the [guide article on theming](/docs/guide/output-theming/index.md).

## Properties

| Property | Type | Description | Defined by |
| --- | --- | --- | --- |
| [`$basePath`](#property-basePath) | `string` | The root path of this theme. | `Theme` |
| [`$baseUrl`](#property-baseUrl) | `string\|null` | The base URL (without ending slash) for this theme. | `Theme` |
| <span id="property-behaviors"></span>[`$behaviors`](/docs/api/yii/base/component/index.md#property-behaviors) read-only | `array<`[`Behavior`](/docs/api/yii/base/behavior/index.md)`<static>>` | List of behaviors attached to this component. | [`Component`](/docs/api/yii/base/component/index.md) |
| [`$pathMap`](#property-pathMap) | `array\|null` | The mapping between view directories and their corresponding themed versions. Default: `null`. | `Theme` |

## Methods

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

## Property details

### $basePath <span id="property-basePath"></span>

```php
public string $basePath
```

The root path of this theme.

All resources of this theme are located under this
directory.

### $baseUrl <span id="property-baseUrl"></span>

```php
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 <span id="property-pathMap"></span>

```php
public array|null $pathMap = null
```

The mapping between view directories and their corresponding themed versions.

This property is used by [`applyTo()`](/docs/api/yii/base/theme/index.md#method-applyTo) when a view is trying to apply the theme.
[Path aliases](/docs/guide/concept-aliases/index.md) can be used when specifying directories.
If this property is empty or not set, a mapping [`Application::$basePath`](/docs/api/yii/base/application/index.md#property-basePath) to [`$basePath`](/docs/api/yii/base/theme/index.md#property-basePath) will be used.

## Method details

### applyTo() <span id="method-applyTo"></span>

```php
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`](/docs/api/yii/base/invalidconfigexception/index.md): if [`$basePath`](/docs/api/yii/base/theme/index.md#property-basePath) is not set

### getBasePath() <span id="method-getBasePath"></span>

```php
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`](/docs/api/yii/base/theme/index.md#property-pathMap)

### getBaseUrl() <span id="method-getBaseUrl"></span>

```php
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() <span id="method-getPath"></span>

```php
public function getPath(string $path): string
```

Converts a relative file path into an absolute one using [`$basePath`](/docs/api/yii/base/theme/index.md#property-basePath).

**Parameters**

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

**Returns**

`string`: The absolute file path

**Throws**

- [`InvalidConfigException`](/docs/api/yii/base/invalidconfigexception/index.md): if [`$basePath`](/docs/api/yii/base/theme/index.md#property-basePath) is not set

### getUrl() <span id="method-getUrl"></span>

```php
public function getUrl(string $url): string
```

Converts a relative URL into an absolute URL using [`$baseUrl`](/docs/api/yii/base/theme/index.md#property-baseUrl).

**Parameters**

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

**Returns**

`string`: The absolute URL

**Throws**

- [`InvalidConfigException`](/docs/api/yii/base/invalidconfigexception/index.md): if [`$baseUrl`](/docs/api/yii/base/theme/index.md#property-baseUrl) is not set

### setBasePath() <span id="method-setBasePath"></span>

```php
public function setBasePath(string $path): mixed
```

**Parameters**

| Parameter | Type | Description |
| --- | --- | --- |
| `$path` | `string` | The root path or [path alias](/docs/guide/concept-aliases/index.md) of this theme. All resources of this theme are located under this directory. |

**Returns**

`mixed`

**See also**

- [`$pathMap`](/docs/api/yii/base/theme/index.md#property-pathMap)

### setBaseUrl() <span id="method-setBaseUrl"></span>

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

**Parameters**

| Parameter | Type | Description |
| --- | --- | --- |
| `$url` | `string\|null` | The base URL or [path alias](/docs/guide/concept-aliases/index.md) for this theme. All resources of this theme are considered to be under this base URL. |

**Returns**

`mixed`