Aurora

Glow Templates

Aurora comes with its own template engine, designed with simplicity, speed and extensibility in mind: the Glow engine.

Glow incorporates the best features from Latte, Twig and Blade in a lightweight package, with the following highlights:

Block reusing and inheritance — Reuse blocks for a better file organization and mantainability of your templates
Automatic escaping — Sanitize output and help avoid common attacks, like XSS
Filters (lower, upper, title, etc.) — Filter the content of variables with an assortment of built-in functions
Directives (if, foreach, switch, etc.) — Replace PHP constructs with easier to understand code
Caching — Boost the performance by caching the compiled templates

To get started, we will create a simple template hierarchy on the resources/templates directory. First create a subdirectory named shared.

Enter the newly created folder and create a file named layout.glow with the following content:

<!DOCTYPE html>
<html lang="en">
    <head>
        <meta charset="UTF-8">
        <meta name="viewport" content="width=device-width, initial-scale=1.0">
        {# Title #}
        <title>{% yield title %}</title>
        {# Stylesheets #}
        <link rel="stylesheet" type="text/css" href="https://cdnjs.cloudflare.com/ajax/libs/twitter-bootstrap/5.1.1/css/bootstrap.min.css">
        <link rel="stylesheet" type="text/css" href="@asset('css/app.css')">
    </head>
    <body class="{% yield slugs %}">
        {# Page content #}
        {% yield content %}
        {# Scripts #}
        <script type="text/javascript" src="https://cdnjs.cloudflare.com/ajax/libs/jquery/3.6.0/jquery.min.js"></script>
        <script type="text/javascript" src="@asset('js/app.js')"></script>
    </body>
</html>

This is your main block, called layout. Please note the three yield calls: these are the places where we we will insert our content blocks for the title, slug and page content. We've added Bootstrap and jQuery for a quick start.

Now, create a new file on the resources/templates directory named page-index.glow with the following content:

{% extends shared/layout %}

{% block title %}Welcome{% endblock %}
{% block slugs %}page-index{% endblock %}

{% block content %}
    {% include shared/header %}

    <section>
        <div class="container">
            <div class="m-3">
                {# Page title #}
                <h2 class="title">
                    <span>Welcome</span>
                </h2>
                {# Page content #}
                <div class="content">
                    @if ($content)
                        {{ $content }}
                    @else
                        <p><em>No content to show</em></p>
                    @endif
                </div>
            </div>
        </div>
    </section>

    {% include shared/footer %}
{% endblock %}

This is your page-index template. First notice that we used the extends function to inherit page-index from shared/layout.

Then there come two simple blocks, title and slugs. Remember them from the main layout? Well, they are simple blocks that we are using to assign the page title and slugs (body classes for CSS styling). As you can see, is as easy as opening a block tag, placing its contents and then closing the tag, the general structure is:

{% block <name> %}<content>{% endblock %}

You can also have multine blocks, as we did with the content block, in this case you open and close the tags around the content:

{% block <name> %}
    <content>
{% endblock %}

The next interesting point is that we are including a shared header too with {% include shared/header %}, so as you may have guessed, you will need to create a header.glow file in the resources/templates/shared directory. While you're at it, create a footer.glow too:

In header.glow:

<header>
    <div class="container">
        <div class="m-3">
            <h1><a href="@url('/')">App name</a></h1>
        </div>
    </div>
</header>

In footer.glow:

<footer>
    <div class="container">
        <div class="m-3">
            <div class="text-center">
                <p class="text-muted"><small>Copyright &copy; {{ date('Y') }}. All Rights Reserved.</small></p>
            </div>
        </div>
    </div>
</footer>

Returning to the our page-index template, you may have noticed that there are a couple lines like this {# Page title #}. They are comments and will be removed from the compiled template, so you can use them to explain or document your templates knowing that they are not going to be present on the final result.

Next there is a conditional tag that goes like:

@if ($content)
    {{ $content }}
@else
    <p><em>No content to show</em></p>
@endif

Glow supports a few tags to ease the use of conditionals, loops, etc., for example if you wanna iterate a collection you can do:

@foreach ($collection as $key => $item)
    <article>
        <h3>{{ $item->name }}</h3>
    </article>
@endforeach

Finally, you have an output tag: {{ $content }}. Output tags take the contents of a variable, escape them and output the result in place; they are useful for example when you want to extract properties from a variable but want to make sure that the contents of that property are sanitized.

Also output tags support filters, for example {{ $item->name|uppercase }} will apply the uppercase() function to the contents of $item->name.

At the bottom of your template you will find another include for the shared/footer block and the endblock tag.

Now just render your template by attaching it to a route in app/Http/App.php:

class App extends WebApp {

    function start() {
        router()->get('/index', function(ServerRequestInterface $request, ResponseInterface $response) {
            $content = view('page-index')->with('content', 'Lorem ipsum dolor sit amet')->render();
            $response->getBody()->write($content);
        });
    }
}

You may also use a controller or the view() method if you like.

Glow reference

Directives

Directives are special constructs that control the flow and logic of the template after being compiled; they are refered to by an @ symbol.

The available directives are:

`if`, `else`, `endif`

They create conditional blocks by evaluating something, for example:

@if ($error)
    <div class="error {{ $error->type }}">Something happened: {{ $error->message }}!</div>
@endif

Or with else:

@if ($user)
    <p>Hey, welcome back {{ $user->nicename }}!</p>
@else
    <p>Hey, welcome guest!</p>
@endif

`for`, `foreach`, `endforeach`, `endfor`

The next group of directives are good for iterating lists or creating loops, for example, to iterate 5 times:

@for ($cards = 1; $cards <= 5; $cards++)
    <div class="card">
        <h3>Card {{ $card }}</h3>
    </div>
@endfor

And for collections:

@foreach ($messages as $message)
    <div class="message">
        <h3>{{ $message->title }}</h3>
        <p>{{ $message->contents }}</p>
        <date>{{ $message->created }}</date>
    </div>
@endforeach

It is also possible to use @break to exit the entire loop or @continue to skip to the next iteration:

@foreach ($messages as $message)
    @continue ($message->status == 'Read') {# Skip messages already seen #}
    <div class="message">
        <h3>{{ $message->title }}</h3>
        <p>{{ $message->contents }}</p>
        <date>{{ $message->created }}</date>
    </div>
@endforeach

`while`

Another way of iterating is with the @while directive that will check against a condition:

@while ( $comments->next() )
    <div class="comment">
        <h3>{{ $comment->from }}</h3>
        <p>{{ $comment->contents }}</p>
    </div>
@endwhile

Also support breaking:

@while ( $comment = $comments->next() )
    <div class="comment">
        <h3>{{ $comment->from }}</h3>
        <p>{{ $comment->contents }}</p>
    </div>
    @break ( $comment->isLast() ) {# Exit on the last comment #}
@endwhile

`switch`, `case`, `default`, `break`, `endswitch`

Sometimes you need to check for multiple possible values for a variables and act accordingly, this is where the switch directive comes handy:

@switch ($user->type)
    @case ('administrator')
        {% include users/form-administrator %}
    @break
    @case ('subscriber')
        {% include users/form-subscriber %}
    @break
    @case ('collaborator')
        {% include users/form-collaborator %}
    @break
    @default
        <p>Your user role is not valid</p>
    @break
@endswitch

`isset`, `empty`

These two are utility directives to check if a variable has been set or if it is empty

@isset ($user)
    {# Show user profile button #}
    <a href="@url('/profile')">Edit profile</a>
@endisset

With empty:

@empty ($user->nicename)
    <p>You haven't set your display name yet, <a href="@url('/profile')">click here</a> to edit your profile.</p>
@endempty

`asset`, `url`

In case you need to generate an absolute URL with base in your application's URL:

<a href="@url('/profile')">Edit profile</a>

Similarly, @asset does the same, but for assets in your public directory:

<script type="text/javascript" src="@asset('js/app.js')"></script>

`csrf`, `method`

Finally, there are two special directives for forms, @csrf that outputs the current anti-CSRF token and @method that outputs a _method override for put or delete requests made on the browser:

<form action="@url('users/profile')" method="post">
    @csrf
</form>

<form action="@url('users/profile')" method="post">
    @method('put')
</form>

Filters

The filters allow you to apply a quick filter to the value of a variable; to use them, add a pipe | after the variable name and then the filter name:

{{ $message->title|title }} {# Apply a Title Case filter #}

The available filters are:

escape — Escape the value
urlencode — URL-encode the value
lower — Lower-case the value
upper — Upper-case the value
title — Title-case the value
striptags — Strip tags from the value
trim — Trim the value, optionally specify a trim character, {{ 'foot'|trim('t') }} will output foo
reverse — Reverse the value
replace — Replace a substring in the value, {{ 'foo'|replace('oo', 'aa') }} will output faa
join — Join an array, you must specify the glue character, for example {{ ['foo', 'bar']|join(', ') }} will output foo, bar
implode — Alias for join
split — Split a string; this is not meant to be used standalone, usually you'll want to stack it with join to change the delimiter, for example {{ 'foo,bar'|split(',')|join('|') }} will output foo|bar
explode — Alias for split
json_encode — Encode the value into JSON
json_decode — Decode the string into a JSON object, not meant to be used standalone as the resulting object will not be printed-out
base64_encode — Encode the value using Base64
base64_decode — Decode the string using Base64, again, this is not meant to be used standalone as the resulting object will not be printed-out
length — Get the length of a string variable
format — Format a numeric variable using number_format, for example {{ pi()|format(2) }} will output 3.14 (don't use that rounded form of π or you may crash the universe)
abs — Get the absolute value of the variable, {{ -5|abs }} will output 5
min — Get the maximum value, in this case you must specify the upper bound, {{ 5|max(2) }} will output 5
max — Get the minimum value, in this case you must specify the upper bound, {{ 5|min(2) }} will output 2
clamp — Clamp a value between upper and lower bounds, {{ 5|clamp(2, 3) }} will output 3

Next up, the Job Queue.

Glow Templates

Glow reference

Tags

`block`

`include`

`extends`

`yield`

Directives

`if`, `else`, `endif`

`for`, `foreach`, `endforeach`, `endfor`

`while`

`switch`, `case`, `default`, `break`, `endswitch`

`isset`, `empty`

`asset`, `url`

`csrf`, `method`

Filters

Glow Templates

Glow reference

Tags

block

include

extends

yield

Directives

if, else, endif

for, foreach, endforeach, endfor

while

switch, case, default, break, endswitch

isset, empty

asset, url

csrf, method

Filters

`block`

`include`

`extends`

`yield`

`if`, `else`, `endif`

`for`, `foreach`, `endforeach`, `endfor`

`while`

`switch`, `case`, `default`, `break`, `endswitch`

`isset`, `empty`

`asset`, `url`

`csrf`, `method`