PHP Luminova: View Layer and Template Rendering

The View class is used to load and render templates in Luminova, perfect for building apps using MVC or HMVC. It compiles your templates, presents them as HTML or other formats, and can cache the final output to speed up page loads.

Unlike the Content Response Class, which is for sending raw or API data, View focuses on rendering template files (html, xml, js, etc.) and gives you options for layout inheritance, rendering modes, and template scope to match your coding style.

Features

1. Fast Rendering – Compiles and minifies templates automatically.
2. Flexible Output – Supports templates that return HTML, arrays, objects, or scalars.
3. Built-in Caching – Saves rendered templates for better performance.
4. Highly Configurable – Adjust rendering modes via Template Rendering Configuration.

Rendering Modes

In Luminova, views can be rendered in Global (default) or Isolation mode. You can change this and other settings in the Template View Configuration.

Global

In global mode, you can access $this or self directly within the template view file. This allows you to reference properties from the application class (e.g., $this->app->foo) or public methods in the view class.

// /resources/View/index.php

$this->_title
$this->app->foo

When to Use:Choose Direct Rendering Mode when you want maximum convenience and direct access to the view class instance without extra setup.This is ideal for quick prototyping or when your template needs frequent interaction with application methods or properties.

Isolation

In isolation mode, $this and self are not available inside the template view file. Instead, you use a special $self variable, which works like $this but without giving the template direct access to the view object.

// /resources/View/index.php

$self->_title
$self->app->foo

When to Use:Choose Isolation Rendering Mode when you want stronger separation between your view and application logic, or when you need to avoid exposing the full $this context for security, maintainability, or testing purposes.

Default Global Options

When rendering templates in Luminova, certain variables (view options) are automatically available.These provide core details about the current template and can be used to control its behavior and output.

Immutable Options

These options are automatically set by the system and cannot be overridden when rendering views.

1. viewType, $_VIEW_TYPE (string) – The type of the template content.
2. active (string) – The name of the current template.

3. asset (string) – Relative path to the assets folder.

   Copy

   <img src="<?= $scope->_asset; ?>images/file.png">

4. href (string) – Relative link root.

   Copy

   <a href="<?= $scope->_href; ?>foo">Foo</a>

5. ALLOW_ACCESS (bool: true) – A constant that can be used to restrict access to files intended for the view class only.
6. $_VIEW_FILEPATH (string) – The absolute file path to the current template.

Note: $scope may be $this or $self depending on the rendering mode.

Mutable Options

These options can be overridden when rendering, allowing you to customize the template behavior.

1. noCache (bool) – Exclude the current template from caching.
2. title (string) – The page title. Defaults to "<active template> – <application name>" if not set.
3. subtitle (string) – The page subtitle. Defaults to the title if not set.

Options Access

In Luminova, template options are additional metadata passed during rendering. How these options are accessed depends on the Template Options Prefixing.

• When Prefixing is set to true (_):Options are accessed with a prefix inside templates:

  Copy

  $this->_fooOption
  // or
  $self->_fooOption

• When Prefixing is set to false:Options are accessed without a prefix:

  Copy

  $this->fooOption
  // or
  $self->fooOption

  Note: In isolation mode, avoid using the key self for options, as it’s reserved for the isolation scope keyword.

• When Prefixing is set to null:Options are provided raw as the $options array, accessible directly inside the template for both direct and isolation rendering:

  Copy

  $options['fooOption']

Also see view methods getOption() and getOptions()

Class Definition

• Class namespace: \Luminova\Template\View
• This class is marked as final and can't be subclassed
• This class implements:\Luminova\Interface\LazyInterface

Constants

These constants define template content type identifiers used by the framework for operations such as caching, minification, and other processing. For more rendering support see Response Class Documentation

Note: They are not the same as HTTP header Content-Type values, but are used internally for purposes such as caching, minification, and content processing. If no explicit HTTP header content type is set, these constants can also be used to determine the appropriate response header.

Properties

app

Holds the application instance.

public ?Luminova\Foundation\CoreApplication $app = null

Does not create a circular reference with the view instance.

Access within templates:

$this->app; 
// or  
$self->app;

When to use:Use this property when you need access to application-level services, configuration, or methods directly from within a template without instantiating or passing the application object manually.Use export for private properties.

Methods

constructor

Initialize the View object.

This constructor sets up template configuration for view management, and loads environment-based options.

public __construct(?Luminova\Foundation\CoreApplication $app): mixed

Parameters:

Note: You may not need to initialize this class manually as it is already available within the Luminova\Foundation\CoreApplication class, which can be accessed inside controller classes.For global helper access, use Luminova\Funcs\view(...).

view

Sets the view template and its content type for rendering.

It resolves the template path and prepares it for rendering or later access.

Call this method to specify which view file to use, before any of these methods (render(), respond(), promise(), exists() or info()) are called.

Search Paths:

• /resources/Views/ — MVC view directory.
• /app/Modules/Views/ — HMVC root view directory.
• /app/Modules/<Module>/Views/ — HMVC module-specific views.

Supported Content Types:

• html, json, text|txt, xml, js, css, rdf, atom, rss

The $template must exclude file extensions (.php, .tpl, .twg, etc).For unsupported types, use response(...)->render(...) for manual handling.

final public view(string $template, string $type = self::HTML): self

Parameters:

Return Value:

self - Return instance of template view class.

Throws:

• \Luminova\Exceptions\InvalidArgumentException - If $type is not a supported view type.

Example:

Usage in Controller:

// /app/Controllers/Http/FooController.php

// Render view and return status
$status = $this->app->view->view('profile', View::HTML)
    ->render(['id' => 1]);

// Render view and return content
$content = $this->app->view->view('settings', View::JSON)
    ->response(['tab' => 'privacy']);

// Render view and return promise object
$promise = $this->app->view->view('invoice', View::HTML)
    ->promise(['orderId' => 101]);

// Return template filesystem information
$info = $this->app->view->view('index', View::HTML)
    ->info();

Direct Usage:

$view = new View(app: $application);

render

Render and immediately send the view output.

This method renders view content with an optional parameters to make globally availablewithin the template view file.

final public render(array<string,mixed> $options = [], int $status = 200): int

Parameters:

Return Value:

int - Return one of the following status codes:

• STATUS_SUCCESS if the view is handled successfully,
• STATUS_SILENCE if failed, silently terminate without error page allowing you to manually handle the state.

Throws:

• \Luminova\Exceptions\RuntimeException - If the view rendering fails.

Example:

Display template view with options:

// /app/Controllers/Http/FooController.php

public function fooView(): int 
{
    return $this->app->view->view('name')
        ->render([...], 200);
}

respond

Render the view and return the output as a string.

This method renders selected template view and return the rendered contents string.

final public respond(array<string,mixed> $options = [], int $status = 200): ?string

Parameters:

Return Value:

string|null - Return the compiled view contents or null if no content.

Throws:

• \Luminova\Exceptions\RuntimeException - If the view rendering fails.

Example:

Display your template view or send as an email:

// /app/Controllers/Http/MailController.php

public function mailView(): int 
{
    $content = $this->app->view->view('name')
        ->respond(['foo' => 'bar'], 200);

    Mailer::to('[email protected]')->send($content);
}

promise

Return a promise that resolves with rendered view contents.

Renders the template view file and returns a promise that resolves with the rendered contents, or rejects if the template is missing or rendering fails.

final public promise(array<string,mixed> $options = [], int $status = 200): PromiseInterface

Parameters:

Return Value:

Luminova\Interface\PromiseInterface - Return a promise that resolves with rendered view contents or rejects with an error.

Example:

Display your template view or send as an email:

// /app/Controllers/Http/FooController.php

public function fooView(): int 
{
    $content = $this->app->view->view('name')
        ->promise(['foo' => 'bar'])
        ->then(function(string $content) {
            Mailer::to('[email protected]')->send($content);
        })->catch(function(Exception $e) {
            logger('debug', $e->getMessage());
        });
}

info

Returns metadata about the specified view template.

Provides useful diagnostic and contextual information about a template file without rendering.

final public info(?string $key = null): mixed

Parameters:

Return Value:

array<string,mixed>|mixed - Return the value for that key (null if not found), otherwise return metadata array.

Example:

$info = $this->app->view->view('dashboard')
    ->info();

// Get the modified
$modified = $this->app->view->view('dashboard')
    ->info('modified');

exists

Check if a template view file exists.

final public exists(): bool

Return Value:

bool - Return true if the template view file exists, false otherwise.

Example:

if($this->app->view->view('admin')->exists()){
    // Yes
}

export

Export a class instance or fully qualified name for later access in templates.

This allows registering services, classes, or any custom objectso that it can be accessed in the template via its alias.

Alternatively you can access public/protected properties and methods in application class directly using $this->app->property or $self->app->property.

final public export(object|string $target, ?string $alias = null, bool $shared = false): true

Parameters:

Return Value:

bool - Returns true if imported, otherwise throw error.

Throws:

• \Luminova\Exceptions\RuntimeException - If arguments are invalid or alias already exists.

Usages:

// /app/Application.php

class Application extends CoreApplication
{
    protected ?Session $session = null;

    protected function onCreate(): void 
    {
        $this->session = new Session();
        $this->session->setStorage('users');
        $this->session->start();

        $this->view->export($this->session, 'session');
    }
} 

Note: If $target is not an object, it treated as a class name to be instantiated later.

Exports Access:

Exported properties are accessed using the specified $alias. If no alias is set, the class basename is used by default.

$this->session
// or
$self->session

You can also access exported methods similarly:

$this->getExport('session')
// or
$self->getExport('session')

header

Set a single response header.

This allows you to add a response header for template rendering,

final public header(string $key, mixed $value): self

Parameters:

Return Value:

self - Return instance of template view class.

Example:

$this->app->view->header('Content-Type', 'application/json');

headers

Set multiple response headers at once.

This allows you to add a response headers for template rendering,

final public headers(array<string,mixed> $headers): self

Parameters:

Return Value:

self - Return instance of template view class.

Example:

$this->app->view->headers([
    'Cache-Control' => 'no-cache',
    'Content-Type' => 'text/html; charset=utf-8',
]);

setModule

Sets the HMVC module name for the current controller class.

This identifies the module that the controller belongs to, typically matching the folder name under app/Modules/<Module>.

For example, a controller located atapp/Modules/Blog/Controllers/PostController.php should use 'Blog' as the module name.

Use an empty string if the controller is not part of root module (i.e., global scope).

final public setModule(string $module = ''): self

Parameters:

Return Value:

self - Return instance of template view class.

Throws:

• \Luminova\Exceptions\RuntimeException - If the module name contains invalid characters (e.g., slashes).

Example:

// /app/Modules/Blog/Controllers/Http/ExampleController.php

namespace App\Modules\Blog\Controllers\Http;

use Luminova\Base\BaseController;

class ExampleController extends BaseController
{
    protected function onCreate(): void
    {
        $this->app->view->setModule('Blog');
    }

    //...
}

Note:This method is intended for HMVC design pattern only, and should be called once in the controller’s __construct or onCreate method—before rendering any views.

setFolder

Sets the view subfolder used to locate view files within the application template view directory.

Valid base locations include:

• resources/Views/ - MVC View directory.
• app/Modules/Views/ - HMVC root view directory.
• app/Modules/<Module>/Views/ - HMVC custom module view directory.

final public setFolder(string $path): self

Parameters:

Return Value:

self - Return instance of template view class.

Notes:

• When used in a controller's onCreate or __construct, all views for that controller will be searched in this folder.
• When used in the application's onCreate or __construct, it sets the default folder for all views.
• When used in a controller method before rendering, only that method's view resolution is affected.

Example:

In this example, the setFolder method is used to direct the framework to look for template files in a custom directory (resources/Views/example/) for all views within a specific controller.

// /app/Controllers/Http/ExampleController.php

namespace App\Controllers\Http;

use Luminova\Base\BaseController;

class ExampleController extends BaseController
{
    protected function onCreate(): void
    {
        $this->app->view->setFolder('example');
    }

    public function show(): int
    {
        return $this->view('show');
    }

    public function foo(): int
    {
        // Overrides the default folder for the current method.
        $this->app->view->setFolder('example2');

        return $this->view('foo');
    }
}

setUriPathDepth

Set URI relative parent directories depth.

This method allows you to manually set how many parent directories (../) to prepend to asset and link paths.

It overrides Luminova's default auto-detection based on the current URI depth.Use it when working with nested views or custom routes that require explicit relative path control.

Example depth values:

• 1 → ../
• 2 → ../../

final public setUriPathDepth(int $depth): self

Parameters:

Return Value:

self - Return instance of template view class.

Useful when custom routing or nested views affect the correct relative path for assets.

Example:

Force asset paths to go up one directory:

// /app/Controllers/Http/ExampleController.php

namespace App\Controllers\Http;

use Luminova\Base\BaseController;

class ExampleController extends BaseController
{
    #[Route('app/account', methods: ['GET'])]
    protected function example(): void
    {
        // Override auto depth detection to use only one "../"
        $this->app->view->setUriPathDepth(1);

        return $this->view('account');
    }
}

In the corresponding view file:

// /resources/View/account.php

echo asset('images/logo.png');
// OR
echo "{$this->_asset}images/logo.png";
// Generates: ../assets/images/logo.png

echo href('account/foo');
// OR
echo "{$this->_href}account/foo";
// Generates: ../account/foo

Normally, accessing https://example.com/app/account would trigger auto-detection of ../../ in development environment like XAMPP due to the URI depth (public/app/account).But since we explicitly set the depth to 1, only a single ../ is prepended to asset and link paths.

codeblock

HTML codeblock minification behavior.

This method allows you to configure whether HTML <code> blocks should be excluded from minificationand optionally display a copy button.

final public codeblock(bool $minify, bool $button = false): self

Parameters:

Return Value:

self - Return instance of template view class.

noCaching

Exclude specific templates from being cached.

By default when page.caching = true is enabled in env, all view templates are cached and reused.This method allows you to exclude one or more templates name from caching it rendered content. Useful for selectively exclusion, ensuring that dynamic content is always up-to-date.

final public noCaching(string|string[] $template): self

Parameters:

Return Value:

self - Return instance of template view class.

Example:

To disable caching for specific a view templates, example insert and edit will be excluded while allowing cache for other templates.

// /app/Application.php

namespace App;

use Luminova\Foundation\CoreApplication;

class Application extends CoreApplication
{
    protected function onCreate(): void
    {
        $this->view->noCaching(['insert', 'edit']);
    }
}

This can be configured either in your routes/<context>.php file, Application class or your view Controller class. > The recommended approach is within the application onCreate or __construct method.

cacheOnly

Specify templates that should be cached exclusively.

This method allows you to explicitly add one or more templates that should only be cached.

Unlike noCaching method, the cacheOnly method allows you to specify which view templates should be exclusively cached while others are ignored. This is useful when you want to ensure that only certain views are cache and excluded others entirely.

final public cacheOnly(string|string[] $template): self

Parameters:

Return Value:

self - Return instance of template view class.

Example:

Enable caching for only home, about, and contact views

// /app/Application.php

namespace App;

use Luminova\Foundation\CoreApplication;

class Application extends CoreApplication
{
    protected function onCreate(): void 
    {
        $this->view->cacheOnly(['home', 'about', 'contact']);
    }
}

Applicable Usage:If you have 100 views but only want to cache three of them (e.g,home, about, and contact). Using noCaching would mean listing all the other 97 views.Instead, use cacheOnly to list just the views you want cached. This way, only those three are cached, and everything else is automatically excluded.

cacheable

Enable or disable view caching globally at the controller or application level.

final public cacheable(bool $cacheable = true): self

Parameters:

Return Value:

self - Return instance of template view class.

If used in a controller’s onCreate() or __construct(), all views under that controller will follow this rule.If used in the application class, applies to all views globally.Useful in api context to manually handle caching.

Example:

The cacheable method can be called in the controller's or application's onCreate or __construct method.

// /app/Application.php

namespace App\Controllers\Http;

use Luminova\Foundation\CoreApplication;

class Application extends CoreApplication
{
    protected function onCreate(): void
    {
        $this->view->cacheable(false);
    }
}

The cacheable method provides a straightforward way to control view caching by setting the caching status globally or for specific controllers, you can ensure that dynamic content remains current without being cached.

cache

Enables view response caching for reuse on future requests.

When called, this method marks the response to be cached. You can optionallyspecify a custom expiration time; otherwise, the default from the .env config will be used.

final public cache(\DateTimeInterface|int|null $expiry = null): self

Parameters:

Return Value:

self - Return instance of template view class.

Example:

Basic usage with conditional caching.

// /app/Controllers/Http/FooController.php

public function fooView(): int 
{
    $cache = $this->app->view->cache(60); // Cache for 60 seconds

    if ($cache->expired()) {
        $heavy = $model->doHeavyProcess();

        return $cache->view('foo')
            ->render(['data' => $heavy]);
    }

    return $cache->reuse(); // Reuse the previously cached response
}

delete

Deletes the cache entry for the current request view.

final public delete(?string $version = null): bool

Parameters:

Return Value:

bool - Return true if the cache entry was deleted; false otherwise.

clear

Clears all view cache entries.

final public clear(?string $version = null): int

Parameters:

Return Value:

int - Return the number of deleted cache entries.

Example:

Clear all cache entries for the current application version.

$total = $this->clear();

Clear cache entries for a specific application version.

$total = $this->clear('1.0.0');

expired

Check if page cache has expired.

Note: the expiration check we use the time used while saving cache.

final public expired(?string $type = self::HTML): bool

Parameters:

Return Value:

bool - Returns true if cache doesn't exist or expired.

Throws:

• \Luminova\Exceptions\RuntimeException - Throw if the cached version doesn't match with the current view type.

Note:

Before calling this method, you must first call cache method instantiate it for use.

For the expiration check, we use the expiration set in env while saving cache, also don't worry about the cache key as it handled internally to save your precious time.

reuse

Reuse previously cached view content if available.

final public reuse(): int

Return Value:

int - Returns one of the following status codes:

• STATUS_SUCCESS if cache was found and successfully reused,
• STATUS_SILENCE if no valid cache was found — silent exit, allowing manual fallback logic.

Throws:

• \Luminova\Exceptions\RuntimeException - If called without first calling cache() method.

Example:

public function homepage(): int
{
    // Enable caching for 2 minutes
    $this->app->view->cache(120); 

    if ($this->app->view->reuse() === STATUS_SUCCESS) {
        // Cache hit, response already sent
        return STATUS_SUCCESS; 
    }

    $data = $model->getHomepageData();
    return $this->app->view->view('home')
        ->render(['data' => $data]);
}

onExpired

Conditionally renew cached view if expired, otherwise reuse it.

final public onExpired(string $type, Closure $renew, mixed ...$arguments): int

Parameters:

Return Value:

int - Return the status code:

• Status code from the callback if cache is expired or bypassed,
• Otherwise, status code from reuse() if valid cache is used.

Example:

public function books(): int 
{
    return $this->app->view->cache(300)->onExpired(View::HTML, function(string $group): int {
        return $this->view('books', [
         'group' => $group,
            'books' => [
               ['id' => 100, 'name' => 'Basic Programming'],
               ['id' => 1001, 'name' => 'Advanced Programming']
         ]
        ]);
    }, 'programming');
}

redirect

Redirect to a different URI or route.

final public redirect(string $uri, int $status = 302): never

Parameters:

link

Generate a relative URI from the public root directory.

This method creates a relative path for routes or public assets (e.g., CSS, JS, images)starting from the controller’s public directory. In production, it returns a root-relative path.In development, it calculates the relative path based on URI segments.

final public static link(string $route = '', ?int $depth = null): string

Parameters:

Return Value:

string - Return a relative or root-based URL to the file or route.

Example:

<link href="<?= $this->link('assets/css/main.css') ?>" rel="stylesheet">
<a href="<?= $this->link('about') ?>">About Us</a>

hasOption

Checks if a given name exists as a view option.

Useful for determining whether a value was set in the current view context via configuration options.

final public hasOption(string $name): bool

Parameters:

Return Value:

bool - Returns true if the option exists, otherwise false.

isExported

Checks if a given property exists as an exported alias.

Useful for determining whether a value was made available to thecurrent view via the export() method.

final public isExported(string $name): bool

Parameters:

Return Value:

bool - Returns true if the export exists, otherwise false.

getExport

Retrieves a property exported from the application context.

final public getExport(string $name): mixed

Parameters:

Return Value:

mixed|null - Return the export value, or null if not found.

getOption

Retrieves a value from the view's context options.

final public getOption(string $key): mixed

Parameters:

Return Value:

mixed|null - Returns the option value if set; otherwise, checks for the key prefixed with _ and returns that value if found. Returns null if neither exists.

Note: Supports fallback to prefixed keys for flexibility and backward compatibility.

getExports

Returns all exported application properties available to the view.

final public getExports(): array<string,mixed>

Return Value:

array<string,mixed> - Return an associative array of exported properties.

getOptions

Returns all view context options extracted for the view.

final public getOptions(): array<string,mixed>

Return Value:

array<string,mixed> - Return an associative array of view context options.

getTemplate

Get the template filename.

By default, returns the resolved template name (which may differ from the originalif a fallback like 404 was used).

Pass false to get the original template name exactly as specified in the controller.

final public getTemplate(bool $resolved = true): string

Parameters:

Return Value:

string - Return the current view template file basename.

getStatusCode

Get the current HTTP status code.

Useful when you need to access the same status code that was used to render the template directly from inside the template itself.

final public getStatusCode(): string

Return Value:

int - Return the HTTP status code (e.g., 200, 404, 500).

toTitle

Converts the current view template name to a formatted page title.

Replaces underscores, dashes, hyphens, and commas with spaces, capitalizes words,and optionally appends the application name as a suffix.

final public toTitle(bool $suffix = false): string

Parameters:

Return Value:

string - Return the formatted page title.