⬡ Lacelium
⌘K
Version 2.x ▾

Views & Templating

Introduction

Of course, it's not practical to return entire HTML documents directly from your routes and controllers. Thankfully, views provide a convenient way to place all of our HTML in separate files.

Views separate your controller / application logic from your presentation logic and are stored in the app/Views directory. Lacelium utilizes Twig 3.x as its primary templating engine, offering a clean, readable syntax and robust escaping security.

Creating & Rendering Views

A view file typically contains HTML along with Twig template tags. For example, a simple view might look like this:



    
        
Hello, {{ name }}!

To return this view from a controller, call the render method on BaseController:

public function index(): Response
{
    return $this->render('greeting.twig', [
        'name' => 'James',
    ]);
}

Passing Data to Views

As you saw in the previous examples, you may pass an array of data to views as the second argument to the render method. When passing information in this manner, the data should be an array with key / value pairs.

return $this->render('users/profile.twig', [
    'user' => $user,
    'orders' => $orders,
    'unreadNotificationsCount' => 3,
]);

Inside your view, you can access each value using its corresponding array key:

User Profile: {{ user.name }}


Email: {{ user.email }}


Pending notifications: {{ unreadNotificationsCount }}

Twig Syntax Fundamentals

Displaying Data

You may display data passed to your Twig views by wrapping the variable in curly braces:

Hello, {{ name }}.

By default, Twig automatically escapes all variables to protect against Cross-Site Scripting (XSS). If you explicitly want to render raw, unescaped HTML, use the raw filter:

{{ content|raw }}

Conditionals

You may construct if statements using the {% if %}, {% elseif %}, {% else %}, and {% endif %} tags:

{% if records|length === 1 %}
    I have one record!
{% elseif records|length > 1 %}
    I have multiple records!
{% else %}
    I don't have any records!
{% endif %}

Loops

You may iterate over arrays or collections using the {% for %} tag:

    
{% for user in users %}
    
  • {{ loop.index }}. {{ user.name }} ({{ user.email }})
    • 
{% else %}
    
  • No users found.
    • 
{% endfor %}

Template Inheritance

Template inheritance is one of the most powerful features of Twig. It allows you to build a base "skeleton" layout that contains all the common elements of your site (navigation, headers, footers) and define "blocks" that child templates can override.

Defining a Layout




    
        {% block title %}Default Title{% endblock %}
        
    
    
        

        

            {% block content %}{% endblock %}

Extending a Layout


{% extends "shared/layouts/base.twig" %}

{% block title %}My Task List{% endblock %}

{% block content %}
    
Tasks

    
    
        {% for task in tasks %}
            
  • {{ task.title }}
    • 
        {% endfor %}
    

{% endblock %}

Global View Helpers

Lacelium automatically registers several global functions and variables across all Twig templates:

  • app_config('key', 'default'): Access configuration options.
  • app_locale(): Return the active translation locale.
  • csrf_field(): Generate hidden input with CSRF token.
  • uuidV4(): Generate a fresh UUID string.
  • base_path: Root URL path for asset references.

Next Steps