0 follower

Final Class Yiisoft\View\View

InheritanceYiisoft\View\View
ImplementsYiisoft\View\ViewInterface
Uses TraitsYiisoft\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

Hide inherited 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

Constants

Hide inherited constants

Constant Value Description Defined By
PHP_EXTENSION 'php' Yiisoft\View\ViewInterface

Method Details

Hide inherited methods

__construct() public method

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__);
}

            
addToParameter() public method

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;
}

            
beginPage() public method

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));
}

            
clear() public method

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();
}

            
createAfterRenderEvent() protected method

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);
}

            
createBeforeRenderEvent() protected method

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);
}

            
deepClone() public method

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;
}

            
endPage() public method

Marks the ending of a view.

public void endPage ( )

                public function endPage(): void
{
    $this->eventDispatcher?->dispatch(new PageEnd($this));
    ob_end_flush();
}

            
getBasePath() public method

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;
}

            
getBlock() public method

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);
}

            
getFallbackExtensions() public method

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;
}

            
getLocale() public method

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();
}

            
getParameter() public method

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);
}

            
getPlaceholderSignature() public method

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;
}

            
getTheme() public method

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 null if no theme has been set.

                public function getTheme(): ?Theme
{
    return $this->themeState->getTheme();
}

            
getViewFile() public method

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. null if no view file is being rendered.

                public function getViewFile(): ?string
{
    /** @psalm-suppress InvalidArrayOffset */
    return empty($this->viewFiles) ? null : end($this->viewFiles)['resolved'];
}

            
hasBlock() public method

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);
}

            
hasParameter() public method

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);
}

            
localize() public method

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;
}

            
removeBlock() public method

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;
}

            
removeParameter() public method

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;
}

            
render() public method

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;
}

            
setBlock() public method

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;
}

            
setLocale() public method

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;
}

            
setParameter() public method

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;
}

            
setParameters() public method

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;
}

            
setTheme() public method

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 null for reset theme.

                public function setTheme(?Theme $theme): static
{
    $this->themeState->setTheme($theme);
    return $this;
}

            
withBasePath() public method

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;
}

            
withClearedState() public method

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;
}

            
withContext() public method

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;
}

            
withContextPath() public method

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));
}

            
withFallbackExtension() public method

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;
}

            
withLocale() public method

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;
}

            
withPlaceholderSalt() public method

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;
}

            
withRenderers() public method

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.

$view = $view->withRenderers(['twig' => new \Yiisoft\View\Twig\ViewRenderer($environment)]);

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;
}

            
withSourceLocale() public method

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;
}

            
withTheme() public method
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;
}