Final Class Yiisoft\View\View
| Inheritance | Yiisoft\View\View |
|---|---|
| Implements | Yiisoft\View\ViewInterface |
| Uses Traits | Yiisoft\View\ViewTrait |
View represents an instance of a view for use in an any environment.
View provides a set of methods (e.g. {@see \Yiisoft\View\View::render()}) for rendering purpose.
Public Methods
| Method | Description | Defined By |
|---|---|---|
| __construct() | Yiisoft\View\View | |
| addToParameter() | Add values to end of common array parameter. If specified parameter does not exist or him is not array, then parameter will be added as empty array. | Yiisoft\View\ViewTrait |
| beginPage() | Marks the beginning of a view. | Yiisoft\View\View |
| clear() | Clears the data for working with the event loop. | Yiisoft\View\ViewTrait |
| deepClone() | Returns a new instance with deep clone of the object, including state cloning. | Yiisoft\View\View |
| endPage() | Marks the ending of a view. | Yiisoft\View\View |
| getBasePath() | Gets the base path to the view directory. | Yiisoft\View\ViewTrait |
| getBlock() | Gets content of the block by ID. | Yiisoft\View\ViewTrait |
| getFallbackExtensions() | Gets the fallback view file extension. | Yiisoft\View\ViewTrait |
| getLocale() | Get the specified locale code. | Yiisoft\View\ViewTrait |
| getParameter() | Gets a common parameter value by ID. | Yiisoft\View\ViewTrait |
| getPlaceholderSignature() | Gets the placeholder signature. | Yiisoft\View\ViewTrait |
| getTheme() | Gets the theme instance, or null if no theme has been set. |
Yiisoft\View\ViewTrait |
| getViewFile() | Gets the view file currently being rendered. | Yiisoft\View\ViewTrait |
| hasBlock() | Checks the existence of a content block by ID. | Yiisoft\View\ViewTrait |
| hasParameter() | Checks the existence of a common parameter by ID. | Yiisoft\View\ViewTrait |
| localize() | Returns the localized version of a specified file. | Yiisoft\View\ViewTrait |
| removeBlock() | Removes a content block. | Yiisoft\View\ViewTrait |
| removeParameter() | Removes a common parameter. | Yiisoft\View\ViewTrait |
| render() | Renders a view. | Yiisoft\View\ViewTrait |
| setBlock() | Sets a content block. | Yiisoft\View\ViewTrait |
| setLocale() | Set the specified locale code. | Yiisoft\View\ViewTrait |
| setParameter() | Sets a common parameter that is accessible in all view templates. | Yiisoft\View\ViewTrait |
| setParameters() | Sets a common parameters that is accessible in all view templates. | Yiisoft\View\ViewTrait |
| setTheme() | Set the specified theme instance. | Yiisoft\View\ViewTrait |
| withBasePath() | Returns a new instance with specified base path to the view directory. | Yiisoft\View\ViewTrait |
| withClearedState() | Returns a new instance with cleared state (blocks, parameters, etc.) | Yiisoft\View\View |
| withContext() | Returns a new instance with the specified view context instance. | Yiisoft\View\ViewTrait |
| withContextPath() | Returns a new instance with the specified view context path. | Yiisoft\View\ViewTrait |
| withFallbackExtension() | Returns a new instance with the specified fallback view file extension. | Yiisoft\View\ViewTrait |
| withLocale() | Set the specified locale code. | Yiisoft\View\ViewTrait |
| withPlaceholderSalt() | Returns a new instance with specified salt for the placeholder signature {@see getPlaceholderSignature()}. | Yiisoft\View\ViewTrait |
| withRenderers() | Returns a new instance with the specified renderers. | Yiisoft\View\ViewTrait |
| withSourceLocale() | Returns a new instance with the specified source locale. | Yiisoft\View\ViewTrait |
| withTheme() | Yiisoft\View\ViewTrait |
Protected Methods
| Method | Description | Defined By |
|---|---|---|
| createAfterRenderEvent() | Yiisoft\View\View | |
| createBeforeRenderEvent() | Yiisoft\View\View |
Constants
| Constant | Value | Description | Defined By |
|---|---|---|---|
| PHP_EXTENSION | 'php' | Yiisoft\View\ViewInterface |
Method Details
| public mixed __construct ( string|null $basePath = null, \Psr\EventDispatcher\EventDispatcherInterface|null $eventDispatcher = null ) | ||
| $basePath | string|null |
The full path to the base directory of views. |
| $eventDispatcher | \Psr\EventDispatcher\EventDispatcherInterface|null |
The event dispatcher instance. |
public function __construct(?string $basePath = null, ?EventDispatcherInterface $eventDispatcher = null)
{
$this->basePath = $basePath;
$this->state = new ViewState();
$this->localeState = new LocaleState();
$this->themeState = new ThemeState();
$this->eventDispatcher = $eventDispatcher;
$this->setPlaceholderSalt(__DIR__);
}
Defined in: Yiisoft\View\ViewTrait::addToParameter()
Add values to end of common array parameter. If specified parameter does not exist or him is not array, then parameter will be added as empty array.
| public Yiisoft\View\View addToParameter ( string $id, mixed $value ) | ||
| $id | string |
The unique identifier of the parameter. |
| $value | mixed |
Value(s) for add to end of array parameter. |
| throws | InvalidArgumentException |
When specified parameter already exists and is not an array. |
|---|---|---|
public function addToParameter(string $id, mixed ...$value): static
{
$this->state->addToParameter($id, ...$value);
return $this;
}
Marks the beginning of a view.
| public void beginPage ( ) |
public function beginPage(): void
{
ob_start();
ob_implicit_flush(false);
$this->eventDispatcher?->dispatch(new PageBegin($this));
}
Defined in: Yiisoft\View\ViewTrait::clear()
Clears the data for working with the event loop.
| public void clear ( ) |
public function clear(): void
{
$this->viewFiles = [];
$this->state->clear();
$this->localeState = new LocaleState();
$this->themeState = new ThemeState();
}
| protected Yiisoft\View\Event\AfterRenderEventInterface createAfterRenderEvent ( string $viewFile, array $parameters, string $result ) | ||
| $viewFile | string | |
| $parameters | array | |
| $result | string | |
protected function createAfterRenderEvent(
string $viewFile,
array $parameters,
string $result
): AfterRenderEventInterface {
return new AfterRender($this, $viewFile, $parameters, $result);
}
| protected \Psr\EventDispatcher\StoppableEventInterface createBeforeRenderEvent ( string $viewFile, array $parameters ) | ||
| $viewFile | string | |
| $parameters | array | |
protected function createBeforeRenderEvent(string $viewFile, array $parameters): StoppableEventInterface
{
return new BeforeRender($this, $viewFile, $parameters);
}
Returns a new instance with deep clone of the object, including state cloning.
| public Yiisoft\View\View deepClone ( ) |
public function deepClone(): static
{
$new = clone $this;
$new->state = clone $this->state;
$new->localeState = clone $this->localeState;
$new->themeState = clone $this->themeState;
return $new;
}
Marks the ending of a view.
| public void endPage ( ) |
public function endPage(): void
{
$this->eventDispatcher?->dispatch(new PageEnd($this));
ob_end_flush();
}
Defined in: Yiisoft\View\ViewTrait::getBasePath()
Gets the base path to the view directory.
| public string getBasePath ( ) | ||
| return | string |
The base view path. |
|---|---|---|
public function getBasePath(): string
{
if ($this->basePath === null) {
throw new LogicException('The base path is not set.');
}
return $this->basePath;
}
Defined in: Yiisoft\View\ViewTrait::getBlock()
Gets content of the block by ID.
| public string getBlock ( string $id ) | ||
| $id | string |
The unique identifier of the block. |
| return | string |
The content of the block. |
|---|---|---|
public function getBlock(string $id): string
{
return $this->state->getBlock($id);
}
Defined in: Yiisoft\View\ViewTrait::getFallbackExtensions()
Gets the fallback view file extension.
| public string[] getFallbackExtensions ( ) | ||
| return | string[] |
The fallback view file extension. |
|---|---|---|
public function getFallbackExtensions(): array
{
return $this->fallbackExtensions;
}
Defined in: Yiisoft\View\ViewTrait::getLocale()
Get the specified locale code.
| public string getLocale ( ) | ||
| return | string |
The locale code. |
|---|---|---|
public function getLocale(): string
{
return $this->localeState->getLocale();
}
Defined in: Yiisoft\View\ViewTrait::getParameter()
Gets a common parameter value by ID.
| public mixed getParameter ( string $id, mixed $default ) | ||
| $id | string |
The unique identifier of the parameter. |
| $default | mixed |
The default value to be returned if the specified parameter does not exist. |
| return | mixed |
The value of the parameter. |
|---|---|---|
| throws | InvalidArgumentException |
If specified parameter does not exist and not passed default value. |
public function getParameter(string $id, mixed ...$default): mixed
{
return call_user_func([$this->state, 'getParameter'], $id, ...$default);
}
Defined in: Yiisoft\View\ViewTrait::getPlaceholderSignature()
Gets the placeholder signature.
| public string getPlaceholderSignature ( ) | ||
| return | string |
The placeholder signature. |
|---|---|---|
public function getPlaceholderSignature(): string
{
return $this->placeholderSignature;
}
Defined in: Yiisoft\View\ViewTrait::getTheme()
Gets the theme instance, or null if no theme has been set.
| public Yiisoft\View\Theme|null getTheme ( ) | ||
| return | Yiisoft\View\Theme|null |
The theme instance, or |
|---|---|---|
public function getTheme(): ?Theme
{
return $this->themeState->getTheme();
}
Defined in: Yiisoft\View\ViewTrait::getViewFile()
Gets the view file currently being rendered.
| public string|null getViewFile ( ) | ||
| return | string|null |
The view file currently being rendered. |
|---|---|---|
public function getViewFile(): ?string
{
/** @psalm-suppress InvalidArrayOffset */
return empty($this->viewFiles) ? null : end($this->viewFiles)['resolved'];
}
Defined in: Yiisoft\View\ViewTrait::hasBlock()
Checks the existence of a content block by ID.
| public boolean hasBlock ( string $id ) | ||
| $id | string |
The unique identifier of the block. |
| return | boolean |
Whether a content block exists. |
|---|---|---|
public function hasBlock(string $id): bool
{
return $this->state->hasBlock($id);
}
Defined in: Yiisoft\View\ViewTrait::hasParameter()
Checks the existence of a common parameter by ID.
| public boolean hasParameter ( string $id ) | ||
| $id | string |
The unique identifier of the parameter. |
| return | boolean |
Whether a custom parameter that is common for all view templates exists. |
|---|---|---|
public function hasParameter(string $id): bool
{
return $this->state->hasParameter($id);
}
Defined in: Yiisoft\View\ViewTrait::localize()
Returns the localized version of a specified file.
The searching is based on the specified locale code. In particular, a file with the same name will be looked for under the subdirectory whose name is the same as the locale code. For example, given the file "path/to/view.php" and locale code "zh-CN", the localized file will be looked for as "path/to/zh-CN/view.php". If the file is not found, it will try a fallback with just a locale code that is "zh" i.e. "path/to/zh/view.php". If it is not found as well the original file will be returned.
If the target and the source locale codes are the same, the original file will be returned.
| public string localize ( string $file, string|null $locale = null, string|null $sourceLocale = null ) | ||
| $file | string |
The original file |
| $locale | string|null |
The target locale that the file should be localized to. |
| $sourceLocale | string|null |
The locale that the original file is in. |
| return | string |
The matching localized file, or the original file if the localized version is not found. If the target and the source locale codes are the same, the original file will be returned. |
|---|---|---|
public function localize(string $file, ?string $locale = null, ?string $sourceLocale = null): string
{
$locale ??= $this->localeState->getLocale();
$sourceLocale ??= $this->sourceLocale;
if ($locale === $sourceLocale) {
return $file;
}
$desiredFile = dirname($file) . DIRECTORY_SEPARATOR . $locale . DIRECTORY_SEPARATOR . basename($file);
if (is_file($desiredFile)) {
return $desiredFile;
}
$locale = substr($locale, 0, 2);
if ($locale === $sourceLocale) {
return $file;
}
$desiredFile = dirname($file) . DIRECTORY_SEPARATOR . $locale . DIRECTORY_SEPARATOR . basename($file);
return is_file($desiredFile) ? $desiredFile : $file;
}
Defined in: Yiisoft\View\ViewTrait::removeBlock()
Removes a content block.
| public Yiisoft\View\View removeBlock ( string $id ) | ||
| $id | string |
The unique identifier of the block. |
public function removeBlock(string $id): static
{
$this->state->removeBlock($id);
return $this;
}
Defined in: Yiisoft\View\ViewTrait::removeParameter()
Removes a common parameter.
| public Yiisoft\View\View removeParameter ( string $id ) | ||
| $id | string |
The unique identifier of the parameter. |
public function removeParameter(string $id): static
{
$this->state->removeParameter($id);
return $this;
}
Defined in: Yiisoft\View\ViewTrait::render()
Renders a view.
The view to be rendered can be specified in one of the following formats:
- the absolute path to the view file, e.g. "/path/to/view.php";
- the name of the view starting with
//to join the base path {@see \Yiisoft\View\getBasePath()}, e.g. "//site/index"; - the name of the view starting with
./to join the directory containing the view currently being rendered (i.e., this happens when rendering a view within another view), e.g. "./widget"; - the name of the view starting with
../to join the parent directory containing the view currently being rendered, e.g. "../_header"; - the name of the view without the starting
//,./or../(e.g. "site/index"). The corresponding view file will be looked for under the {@see \Yiisoft\View\ViewContextInterface::getViewPath()} of the context set via {@see \Yiisoft\View\withContext()}. If the context instance was not set {@see \Yiisoft\View\withContext()}, it will be looked for under the base path.
Warning: Using .. in view path can lead to accessing unsafe data, e.g., //../../etc/passwd. Ensure that such
cases are handled properly.
| public string render ( string $view, array $parameters = [] ) | ||
| $view | string |
The view name. |
| $parameters | array |
The parameters (name-value pairs) that will be extracted and made available in the view file. |
| return | string |
The rendering result. |
|---|---|---|
| throws | LogicException |
If the view cannot be resolved. |
| throws | Yiisoft\View\Exception\ViewNotFoundException |
If the view file does not exist. |
| throws | Throwable | |
public function render(string $view, array $parameters = []): string
{
$viewFile = $this->findTemplateFile($view);
$parameters = array_merge($this->state->getParameters(), $parameters);
// TODO: these two match now
$requestedFile = $viewFile;
$theme = $this->getTheme();
if ($theme !== null) {
$viewFile = $theme->applyTo($viewFile);
}
if (is_file($viewFile)) {
$viewFile = $this->localize($viewFile);
} else {
throw new ViewNotFoundException("The view file \"$viewFile\" does not exist.");
}
$output = '';
$this->viewFiles[] = [
'resolved' => $viewFile,
'requested' => $requestedFile,
];
if ($this->beforeRender($viewFile, $parameters)) {
$ext = pathinfo($viewFile, PATHINFO_EXTENSION);
$renderer = $this->renderers[$ext] ?? new PhpTemplateRenderer();
$output = $renderer->render($this, $viewFile, $parameters);
$output = $this->afterRender($viewFile, $parameters, $output);
}
array_pop($this->viewFiles);
return $output;
}
Defined in: Yiisoft\View\ViewTrait::setBlock()
Sets a content block.
| public Yiisoft\View\View setBlock ( string $id, string $content ) | ||
| $id | string |
The unique identifier of the block. |
| $content | string |
The content of the block. |
public function setBlock(string $id, string $content): static
{
$this->state->setBlock($id, $content);
return $this;
}
Defined in: Yiisoft\View\ViewTrait::setLocale()
Set the specified locale code.
| public Yiisoft\View\View setLocale ( string $locale ) | ||
| $locale | string |
The locale code. |
public function setLocale(string $locale): static
{
$this->localeState->setLocale($locale);
return $this;
}
Defined in: Yiisoft\View\ViewTrait::setParameter()
Sets a common parameter that is accessible in all view templates.
| public Yiisoft\View\View setParameter ( string $id, mixed $value ) | ||
| $id | string |
The unique identifier of the parameter. |
| $value | mixed |
The value of the parameter. |
public function setParameter(string $id, mixed $value): static
{
$this->state->setParameter($id, $value);
return $this;
}
Defined in: Yiisoft\View\ViewTrait::setParameters()
Sets a common parameters that is accessible in all view templates.
See also setParameter().
| public Yiisoft\View\View setParameters ( array $parameters ) | ||
| $parameters | array |
Parameters that are common for all view templates. |
public function setParameters(array $parameters): static
{
$this->state->setParameters($parameters);
return $this;
}
Defined in: Yiisoft\View\ViewTrait::setTheme()
Set the specified theme instance.
| public Yiisoft\View\View setTheme ( Yiisoft\View\Theme|null $theme ) | ||
| $theme | Yiisoft\View\Theme|null |
The theme instance or |
public function setTheme(?Theme $theme): static
{
$this->themeState->setTheme($theme);
return $this;
}
Defined in: Yiisoft\View\ViewTrait::withBasePath()
Returns a new instance with specified base path to the view directory.
| public Yiisoft\View\View withBasePath ( string|null $basePath ) | ||
| $basePath | string|null |
The base path to the view directory. |
public function withBasePath(string|null $basePath): static
{
$new = clone $this;
$new->basePath = $basePath;
return $new;
}
Returns a new instance with cleared state (blocks, parameters, etc.)
| public Yiisoft\View\View withClearedState ( ) |
public function withClearedState(): static
{
$new = clone $this;
$new->state = new ViewState();
$new->localeState = new LocaleState();
$new->themeState = new ThemeState();
return $new;
}
Defined in: Yiisoft\View\ViewTrait::withContext()
Returns a new instance with the specified view context instance.
| public Yiisoft\View\View withContext ( Yiisoft\View\ViewContextInterface|null $context ) | ||
| $context | Yiisoft\View\ViewContextInterface|null |
The context under which the {@see \Yiisoft\View\render()} method is being invoked. |
public function withContext(ViewContextInterface|null $context): static
{
$new = clone $this;
$new->context = $context;
$new->viewFiles = [];
return $new;
}
Defined in: Yiisoft\View\ViewTrait::withContextPath()
Returns a new instance with the specified view context path.
| public Yiisoft\View\View withContextPath ( string $path ) | ||
| $path | string |
The context path under which the {@see \Yiisoft\View\render()} method is being invoked. |
public function withContextPath(string $path): static
{
return $this->withContext(new ViewContext($path));
}
Defined in: Yiisoft\View\ViewTrait::withFallbackExtension()
Returns a new instance with the specified fallback view file extension.
| public Yiisoft\View\View withFallbackExtension ( string $fallbackExtension, string $otherFallbacks ) | ||
| $fallbackExtension | string |
The fallback view file extension. Default is {@see \Yiisoft\View\ViewInterface::PHP_EXTENSION}. This will be appended to view file names if they don't exist. |
| $otherFallbacks | string | |
public function withFallbackExtension(string $fallbackExtension, string ...$otherFallbacks): static
{
$new = clone $this;
$new->fallbackExtensions = [$fallbackExtension, ...array_values($otherFallbacks)];
return $new;
}
Defined in: Yiisoft\View\ViewTrait::withLocale()
Set the specified locale code.
| public Yiisoft\View\View withLocale ( string $locale ) | ||
| $locale | string |
The locale code. |
public function withLocale(string $locale): static
{
$new = clone $this;
$new->localeState = new LocaleState($locale);
return $new;
}
Defined in: Yiisoft\View\ViewTrait::withPlaceholderSalt()
Returns a new instance with specified salt for the placeholder signature {@see getPlaceholderSignature()}.
| public Yiisoft\View\View withPlaceholderSalt ( string $salt ) | ||
| $salt | string |
The placeholder salt. |
public function withPlaceholderSalt(string $salt): static
{
$new = clone $this;
$new->setPlaceholderSalt($salt);
return $new;
}
Defined in: Yiisoft\View\ViewTrait::withRenderers()
Returns a new instance with the specified renderers.
| public Yiisoft\View\View withRenderers ( array $renderers ) | ||
| $renderers | array |
A list of available renderers indexed by their corresponding supported file extensions.
If no renderer is available for the given view file, the view file will be treated as a normal PHP and rendered via {@see \Yiisoft\View\PhpTemplateRenderer}. |
public function withRenderers(array $renderers): static
{
$new = clone $this;
$new->renderers = $renderers;
return $new;
}
Defined in: Yiisoft\View\ViewTrait::withSourceLocale()
Returns a new instance with the specified source locale.
| public Yiisoft\View\View withSourceLocale ( string $locale ) | ||
| $locale | string |
The source locale. |
public function withSourceLocale(string $locale): static
{
$new = clone $this;
$new->sourceLocale = $locale;
return $new;
}
Defined in: Yiisoft\View\ViewTrait::withTheme()
| public Yiisoft\View\View withTheme ( Yiisoft\View\Theme|null $theme ) | ||
| $theme | Yiisoft\View\Theme|null | |
public function withTheme(?Theme $theme): static
{
$new = clone $this;
$new->themeState = new ThemeState($theme);
return $new;
}
Signup or Login in order to comment.