0 follower

Final Class Yiisoft\View\Theme

All Classes | Methods

Inheritance	Yiisoft\View\Theme

Theme represents an application theme.

When {@see \Yiisoft\View\View} renders a view file, it will check the {@see \Yiisoft\View\View::$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 {@see \Yiisoft\View\Theme::$pathMap} to achieve the view file replacement:

It first looks for a key in {@see \Yiisoft\View\Theme::$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 {@see \Yiisoft\View\Theme::$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:

'yiisoft/view' => [
    'theme' => [
        'pathMap' => [
            '/app/views' => [
                '/app/themes/christmas',
                '/app/themes/basic',
            ],
        ],
        'basePath' => '',
        'baseUrl' => '',
    ],
],

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 the theme directly without configurations, you should set it using the {@see \Yiisoft\View\View::setTheme()} as follows:

$pathMap = [...];
$basePath = '/path/to/private/themes/basic';
$baseUrl = '/path/to/public/themes/basic';

$view->setTheme(new Theme([...], $basePath, $baseUrl));

Public Methods

Hide inherited methods

Method	Description	Defined By
__construct()		Yiisoft\View\Theme
applyTo()	Converts a file to a themed file if possible.	Yiisoft\View\Theme
getBasePath()	Returns the base path to the theme directory.	Yiisoft\View\Theme
getBaseUrl()	Returns the URL path for this theme.	Yiisoft\View\Theme
getPath()	Converts and returns a relative file path into an absolute one using {@see getBasePath()}.	Yiisoft\View\Theme
getUrl()	Converts and returns a relative URL into an absolute URL using {@see getbaseUrl()}.	Yiisoft\View\Theme

Method Details

Hide inherited methods

__construct() public method

public mixed __construct ( array $pathMap = [], string $basePath = '', string $baseUrl = '' )
$pathMap	array	The mapping between view directories and their corresponding themed versions. The path map is used by {@see \Yiisoft\View\applyTo()} when a view is trying to apply the theme.
$basePath	string	The base path to the theme directory.
$baseUrl	string	The base URL for this theme.

Source code

                public function __construct(array $pathMap = [], string $basePath = '', string $baseUrl = '')
{
    $this->validatePathMap($pathMap);
    $this->pathMap = $pathMap;
    if ($basePath !== '') {
        $this->basePath = rtrim($basePath, '/');
    }
    if ($baseUrl !== '') {
        $this->baseUrl = rtrim($baseUrl, '/');
    }
}

applyTo() public method

Converts a file to a themed file if possible.

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

public string applyTo ( string $path )
$path	string	The file to be themed
return	string	The themed file, or the original file if the themed version is not available.

Source code

                public function applyTo(string $path): string
{
    if ($this->pathMap === []) {
        return $path;
    }
    $path = FileHelper::normalizePath($path);
    foreach ($this->pathMap as $from => $tos) {
        $from = FileHelper::normalizePath($from) . '/';
        if (str_starts_with($path, $from)) {
            $n = strlen($from);
            foreach ((array) $tos as $to) {
                $to = FileHelper::normalizePath($to) . '/';
                $file = $to . substr($path, $n);
                if (is_file($file)) {
                    return $file;
                }
            }
        }
    }
    return $path;
}

getBasePath() public method

Returns the base path to the theme directory.

See also \Yiisoft\View\pathMap.

public string getBasePath ( )
return	string	The root path of this theme. All resources of this theme are located under this directory.

Source code

                public function getBasePath(): string
{
    return $this->basePath;
}

getBaseUrl() public method

Returns the URL path for this theme.

public string getBaseUrl ( )
return	string	The base URL (without ending slash) for this theme. All resources of this theme are considered to be under this base URL.

Source code

                public function getBaseUrl(): string
{
    return $this->baseUrl;
}

getPath() public method

Converts and returns a relative file path into an absolute one using {@see getBasePath()}.

public string getPath ( string $path )
$path	string	The relative file path to be converted.
return	string	The absolute file path.

Source code

                public function getPath(string $path): string
{
    if (($basePath = $this->getBasePath()) !== '') {
        return $basePath . '/' . ltrim($path, '/\\');
    }
    return $path;
}

getUrl() public method

Converts and returns a relative URL into an absolute URL using {@see getbaseUrl()}.

public string getUrl ( string $url )
$url	string	The relative URL to be converted.
return	string	The absolute URL

Source code

                public function getUrl(string $url): string
{
    if (($baseUrl = $this->getBaseUrl()) !== '') {
        return $baseUrl . '/' . ltrim($url, '/');
    }
    return $url;
}