Chapter 4. Blade Templating

Compared to most other backend languages, PHP actually functions relatively well as a templating language. But it has its shortcomings, and it’s also just ugly to be using <?php inline all over the place, so you can expect most modern frameworks to offer a templating language.

Laravel offers a custom templating engine called Blade, which is inspired by .NET’s Razor engine. It boasts a concise syntax, a shallow learning curve, a powerful and intuitive inheritance model, and easy extensibility.

For a quick look at what writing Blade looks like, check out Example 4-1.

Example 4-1. Blade samples

<h1>{{ $group->title }}</h1>
{!! $group->heroImageHtml() !!}

@forelse ($users as $user)
    • {{ $user->first_name }} {{ $user->last_name }}<br>
@empty
    No users in this group.
@endforelse

As you can see, Blade uses curly braces for its “echo” and introduces a convention in which its custom tags, called “directives,” are prefixed with an @. You’ll use directives for all of your control structures and also for inheritance and any custom functionality you want to add.

Blade’s syntax is clean and concise, so at its core it’s just more pleasant and tidy to work with than the alternatives. But the moment you need anything of any complexity in your templates—nested inheritance, complex conditionals, or recursion—Blade starts to really shine. Just like the best Laravel components, it takes complex application requirements and makes them easy and accessible.

Additionally, since all Blade syntax is compiled into normal PHP code and then cached, it’s fast and it allows you to use native PHP in your Blade files if you want. However, I’d recommmend avoiding usage of PHP if at all possible—usually if you need to do anything that you can’t do with Blade or a custom Blade directive, it doesn’t belong in the template.

Using Twig with Laravel

Unlike many other Symfony-based frameworks, Laravel doesn’t use Twig by default. But if you’re just in love with Twig, there’s a Twig Bridge package that makes it easy to use Twig instead of Blade.

Echoing Data

As you can see in Example 4-1, {{ and }} are used to wrap sections of PHP that you’d like to echo. {{ $variable }} is similar to <?= $variable ?> in plain PHP.

It’s different in one way, however, and you might’ve guessed this already: Blade escapes all echoes by default using PHP’s htmlentities() to protect your users from malicious script insertion. That means {{ $variable }} is functionally equivalent to <?= htmlentities($variable) ?>. If you want to echo without the escaping, use {!! and !!} instead.

{{ and }} When Using a Frontend Templating Framework

You might’ve noticed that the echo syntax for Blade ({{ }}) is similar to the echo syntax for many frontend frameworks. So, how does Laravel know when you’re writing Blade versus Handlebars?

Blade will ignore any {{ that’s prefaced with an @. So, it will parse the first of the following examples, but the second will be echoed out directly:

// Parsed as Blade; the value of $bladeVariable is echoed to the view
{{ $bladeVariable }}

// @ is removed, and "{{ handlebarsVariable }}" echoed to the view directly
@{{ handlebarsVariable }}

You can also wrap any large sections of script content with the @verbatim / @endverbatim directive.

Control Structures

Most of the control structures in Blade will be very familiar. Many directly echo the name and structure of the same tag in PHP.

There are a few convenience helpers, but in general, the control structures just look cleaner than they would in PHP.

Conditionals

First, let’s take a look at the control structures that allow for logic.

@if

Blade’s @if ($condition) compiles to <?php if ($condition): ?>. @else, @elseif, and @endif also compile to the exact same style of syntax in PHP. Take a look at Example 4-2 for some examples.

Example 4-2. @if, @else, @elseif, and @endif

@if (count($talks) === 1)
    There is one talk at this time period.
@elseif (count($talks) === 0)
    There are no talks at this time period.
@else
    There are {{ count($talks) }} talks at this time period.
@endif

Just like with the native PHP conditionals, you can mix and match these how you want. They don’t have any special logic; there’s literally a parser looking for something with the shape of @if ($condition) and replacing it with the appropriate PHP code.

@unless and @endunless

@unless, on the other hand, is a new syntax that doesn’t have a direct equivalent in PHP. It’s the direct inverse of @if. @unless ($condition) is the same as <?php if (! $condition). See it in use in Example 4-3.

Example 4-3. @unless and @endunless

@unless ($user->hasPaid())
    You can complete your payment by switching to the payment tab.
@endunless

Loops

Next, let’s take a look at the loops.

@for, @foreach, and @while

@for, @foreach, and @while work the same in Blade as they do in PHP; see Examples 4-4, 4-5, and 4-6.

Example 4-4. @for and @endfor

@for ($i = 0; $i < $talk->slotsCount(); $i++)
    The number is {{ $i }}<br>
@endfor

Example 4-5. @foreach and @endforeach

@foreach ($talks as $talk)
    • {{ $talk->title }} ({{ $talk->length }} minutes)<br>
@endforeach

Example 4-6. @while and @endwhile

@while ($item = array_pop($items))
    {{ $item->orSomething() }}<br>
@endwhile

@forelse

@forelse is a @foreach that also allows you to program in a fallback if the object you’re iterating over is empty. We saw it in action at the start of this chapter; Example 4-7 shows another example.

Example 4-7. @forelse

@forelse ($talks as $talk)
    • {{ $talk->title }} ({{ $talk->length }} minutes)<br>
@empty
    No talks this day.
@endforelse

$loop Within @foreach and @forelse

The @foreach and @forelse directives (introduced in Laravel 5.3) add one feature that’s not available in PHP foreach loops: the $loop variable. Used within a @foreach or @forelse loop, this variable will return a stdClass object with these properties:

index: The 0-based index of the current item in the loop; 0 would mean “first item”
iteration: The 1-based index of the current item in the loop; 1 would mean “first item”
remaining: How many items remain in the loop; if the current item is the first of three, this will be 2
count: The count of items in the loop
first: A boolean indicating whether this is the first item in the loop
last: A boolean indicating whether this is the last item in the loop
depth: How many “levels” deep this loop is: 1 for a loop, 2 for a loop within a loop, etc.
parent: A reference to the $loop variable for the parent loop item; if this loop is within another @foreach loop otherwise, null

Here’s an example of how to use it:

<ul>
@foreach ($pages as $page)
    <li>{{ $loop->iteration }}: {{ $page->title }}
        @if ($page->hasChildren())
        <ul>
        @foreach ($page->children() as $child)
            <li>{{ $loop->parent->iteration }}.{{ $loop->iteration }}:
                {{ $child->title }}</li>
        @endforeach
        </ul>
        @endif
    </li>
@endforeach
</ul>

Template Inheritance

Blade provides a structure for template inheritance that allows views to extend, modify, and include other views.

Here’s how inheritance is structured with Blade.

Defining Sections with @section/@show and @yield

Let’s start with a top-level Blade layout, like in Example 4-8. This is the definition of a generic page wrapper that we’ll later place page-specific content into.

Example 4-8. Blade layout

<!-- resources/views/layouts/master.blade.php -->
<html>
    <head>
        <title>My Site | @yield('title', 'Home Page')</title>
    </head>
    <body>
        <div class="container">
            @yield('content')
        </div>
        @section('footerScripts')
            <script src="app.js"></script>
        @show
    </body>
</html>

This looks a bit like a normal HTML page, but you can see we’ve yielded in two places (title and content), and we’ve defined a section in a third (footerScripts).

We have three Blade directives here that each look a little different: @yield('content') alone, @yield('title', 'Home Page') with a defined default, and @section ... @show with actual content in it.

All three function essentially the same. All three are defining that there’s a section with a given name (which is the first parameter). All three are defining that the section can be extended later. And all three are defining what to do if the section isn’t extended, either by providing a string fallback ('Home Page'), no fallback (which will just not show anything if it’s not extended), or an entire block fallback (in this case, <script src="app.js"></script>).

What’s different? Well, clearly, @yield('content') has no default content. But additionally, the default content in @yield('title') only will be shown if it’s never extended. If it is extended, its child sections will not have programmatic access to the default value. @section ... @show, on the other hand, is both defining a default and doing so in a way that its default contents will be available to its children, through @parent.

Once you have a parent layout like this, you can extend it in a new template file like in Example 4-9.

Example 4-9. Extending a Blade layout

<!-- resources/views/dashboard.blade.php -->
@extends('layouts.master')

@section('title', 'Dashboard')

@section('content')
    Welcome to your application dashboard!
@endsection

@section('footerScripts')
    @parent

    <script src="dashboard.js"></script>
@endsection

@show versus @endsection

You may have noticed that Example 4-8 uses @section ... @show, but Example 4-9 uses @section ... @endsection. What’s the difference?

Use @show when you’re defining the place for a section, in the parent template. Use @endsection when you’re defining the content for a template in a child template.

This child view will actually allow us to cover a few new concepts in Blade inheritance.

@extends

First, with @extends('layouts.master'), we define that this view should not be rendered on its own, but that it instead extends another view. That means its role is to define the content of various sections, but not to stand alone. It’s almost more like a series of buckets of content, rather than an HTML page. This line also defines that the view it’s extending lives at resources/views/layouts/master.blade.php.

Each file should only extend one other file, and the @extends call should be the first line of the file.

@section and @endsection

Second, with @section('title', 'Dashboard'), we provide our content for the first section, title. Since the content is so short, instead of using @section and @endsection we’re just using a shortcut. This allows us to pass the content in as the second parameter of @section and then move on. If it’s a bit disconcerting to see @section without @endsection, you could just use the normal syntax.

Third, with @section('content') and on, we use the normal syntax to define the contents of the content section. We’ll just throw a little greeting in for now. Note, however, that when you’re using @section in a child view, you end it with @endsection (or its alias @stop), instead of @show, which is reserved for defining sections in parent views.

@parent

Fourth, with @section('footerScripts') and on, we use the normal syntax to define the contents of the footerScripts section.

But remember, we actually defined that content (or, at least, its “default”) already in the master layout. So this time, we have two options: we can either overwrite the content from the parent view, or we can add to it.

You can see that we have the option to include the content from the parent by using the @parent directive within the section. If we didn’t, the content of this section would entirely overwrite anything defined in the parent for this section.

@include

Now that we’ve established the basics of inheritance, there are a few more tricks we can perform.

What if we’re in a view and want to pull in another view? Maybe we have a call-to-action “Sign up” button that we want to re-use around the site. And maybe we want to customize its button text every time we use it. Take a look at Example 4-10.

Example 4-10. Including view partials with @include

<!-- resources/views/home.blade.php -->
<div class="content" data-page-name="{{ $pageName }}">
    <p>Here's why you should sign up for our app: <strong>It's Great.</strong></p>

    @include('sign-up-button', ['text' => 'See just how great it is'])
</div>

<!-- resources/views/sign-up-button.blade.php -->
<a class="button button--callout" data-page-name="{{ $pageName }}">
    <i class="exclamation-icon"></i> {{ $text }}
</a>

@include pulls in the partial and, optionally, passes data into it. Note that not only can you explicitly pass data to an include via the second parameter of @include, but you can also reference any variables within the included file that are available to the including view ($pageName, in this example). Once again, you can do whatever you want, but I would recommend you consider always explicitly passing every variable that you intend to use, just for clarity.

You also use the @includeIf, includeWhen and includeFirst directives.

Example 4-11.

{{-- Include a view if it exists --}}
@includeIf('sidebars.admin', ['some' => 'data'])

{{-- Include a view if a passed variable is truth-y --}}
@includeWhen($user->isAdmin(), 'sidebars.admin', ['some' => 'data'])

{{-- Include the first view that exists from a given array of views --}}
@includeFirst(['customs.header', 'header'], ['some' => 'data'])

@each

You can probably imagine some circumstances in which you’d need to loop over an array or collection and @include a partial for each item. There’s a directive for that: @each.

Let’s say we have a sidebar composed of modules, and we want to include multiple modules, each with a different title. Take a look at Example 4-12.

Example 4-12. Using view partials in a loop with @each

<!-- resources/views/sidebar.blade.php -->
<div class="sidebar">
    @each('partials.module', $modules, 'module', 'partials.empty-module')
</div>

<!-- resources/views/partials/module.blade.php -->
<div class="sidebar-module">
    <h1>{{ $module->title }}</h1>
</div>

<!-- resources/views/partials/empty-module.blade.php -->
<div class="sidebar-module">
    No modules :(
</div>

Consider that @each syntax. The first parameter is the name of the view partial. The second is the array or collection to iterate over. The third is the variable name that each item (in this case, each element in the $modules array) will be passed to the view as. And the optional fourth parameter is the view to show if the array or collection is empty (or, optionally, you can pass a string in here that will be used as your template).

Stacks

One common pattern that can be difficult to manage using basic Blade includes is when each view in a Blade include hierarchy needs to add something to a certain section—almost like adding an entry onto an array.

The most common situation for this is when certain pages (and sometimes, more broadly, certain sections of a website) have specific unique CSS and JavaScript files they need to load. Imagine you have a site-wide “global” CSS file, a “jobs section” CSS file, and an “apply for a job” page CSS file.

Blade’s “stacks” are built for exactly this situation. In your parent template, you’ll define a “stack”, which is just a placeholder; then in each child template you can “push” entries onto that stack with @push/@endpush, which just add them to the bottom of the stack in the final render. You can also use @prepend/@endprepend to add them to the top of the stack.

Example 4-13. Using Blade stacks

<!-- resources/views/layouts/app.blade.php -->
<html>
<head><!-- the head --></head>
<body>
    <!-- the rest of the page.. -->
    <script src="/css/global.css"></script>
    <!-- the placeholder where stack content will be placed -->
    @stack('scripts')
</body>
</html>

<!-- resources/views/jobs.blade.php -->
@extends('layouts.app')

@push('scripts')
    <!-- push something to the bottom of the stack -->
    <script src="/css/jobs.css"></script>
@endpush

<!-- resources/views/jobs/apply.blade.php -->
@extends('jobs')

@prepend('scripts')
    <!-- push something to the top of the stack -->
    <script src="/css/jobs--apply.css"></script>
@endprepend

These would generate this:

<html>
<head><!-- the head --></head>
<body>
    <!-- the rest of the page.. -->
    <script src="/css/global.css"></script>
    <!-- the placeholder where stack content will be placed -->
    <script src="/css/jobs--apply.css"></script>
    <script src="/css/jobs.css"></script>
</body>
</html>

Components and Slots

Laravel offers another pattern for including content between views, which was introduced in 5.4: components and slots. Components make the most sense in contexts when you find yourself using view partials and passing large chunks of content into the partial as variables. Take a look at Example 4-14 for an example.

Example 4-14. Modal as an akward view partial

<!-- resources/views/partials/modal.blade.php -->
<div class="modal">
    <div>{{ $content }}</div>
    <div class="close button etc">...</div>
</div>

<!-- in another template -->
@include('partials.modal', [
    'body' => '<p>The password you have provided is not valid. Here are the rules
    for valid passwords: [...]</p><p><a href="#">...</a></p>'
])

This is too much for this variable, and it’s the perfect fit for a component.

Components with slots are view partials that are explicitly designed to have big chunks (“slots”) that are meant to get content from the including template. Take a look at Example 4-15 to see how to refactor Example 4-14 with components and slots.

Example 4-15. Modal as an more-appropriate component with slots

<!-- resources/views/partials/modal.blade.php -->
<div class="modal">
    <div>{{ $slot }}</div>
    <div class="close button etc">...</div>
</div>

<!-- in another template -->
@component('partials.modal')
    <p>The password you have provided is not valid.
    Here are the rulesfor valid passwords: [...]</p>

    <p><a href="#">...</a></p>
@endcomponent

As you can see in Example 4-15, the @component directive allows us to pull our HTML out of a cramped variable string and back into the template space. The $slot variable in our component template receives whatever content is passed between the @component and @endcomponent directives.

Multiple slots

The method we used in Example 4-15 is called the “default” slot; whatever you pass in between @component and @endcomponent is passed to the $slot variable. But you can also have more than just the default slot. Let’s imagine a modal with a title, like in Example 4-16.

Example 4-16. A modal view partial with two variables

<!-- resources/views/partials/modal.blade.php -->
<div class="modal">
    <div class="modal-header">{{ $title }}</div>
    <div>{{ $slot }}</div>
    <div class="close button etc">...</div>
</div>

You can use the @slot directive in your @component calls to pass content to slots other than the default, as you can see in Example 4-17.

Example 4-17. Passing more than one slot to a component

@component('partials.modal')
    @slot('title')
        Password validation failure
    @endslot

    <p>The password you have provided is not valid. Here are the rules for valid passwords: [...]</p>

    <p><a href="#">...</a></p>
@endcomponent

And if you have other variables in your view that don’t make sense as a slot, you can still pass an array of content as the second parameter to @component, just like you can with @include. Take a look at Example 4-18.

Example 4-18. Passing data to a component without slots

@component('partials.modal', ['class' => 'danger'])
    <!-- ... -->
@endcomponent

Aliasing a component to be a directive

There’s a clever trick you can use to make your components even easier to call: aliasing. Simple call Blade::component() on the Blade facade—the most common location is the boot() method of the AppServiceProvider—and pass it first the location of the component and second the name of your desired directive:

Example 4-19.

// AppServiceProvider@boot
Blade::component('partials.modal', 'modal')

<!-- in a template -->
@modal
    Modal content here
@endmodal

Importing facades

This is our first time working with a facade in a namespaced class. We’ll cover them in more depth later, but just know that if you use facades in namespaced classes, which is most classes in recent versions of Laravel, you might find errors showing that the facade cannot be found. This is because facades are just normal classes with normal namespaces, but Laravel does a bit of trickery to make them available at the root namespace.

So, in Example 4-19, we’d need to import the Illuminate\Support\Facades\Blade facade at the top of the file.

View Composers and Service Injection

As we covered in Chapter 3, it’s simple to pass data to our views from the route definition (see Example 4-20).

Example 4-20. Reminder on how to pass data to views

Route::get('passing-data-to-views', function () {
    return view('dashboard')
        ->with('key', 'value');
});

There are times, however, when you will find yourself passing the same data over and over to multiple views. Or, you might find yourself using a header partial or something similar that requires some data; will you now have to pass that data in from every route definition that might ever load that header partial?

Binding Data to Views Using View Composers

Thankfully, there’s a simpler way. The solution is called a view composer, and it allows you to define that any time a particular view loads, it should have certain data passed to it—without the route definition having to pass that data in explicitly.

Let’s say you have a sidebar on every page, which is defined in a partial named partials.sidebar (resources/views/partials/sidebar.blade.php) and then included on every page. This sidebar shows a list of the last seven posts that were published on your site. If it’s on every page, every route definition would normally have to grab that list and pass it in, like in Example 4-21.

Example 4-21. Passing sidebar data in from every route

Route::get('home', function () {
    return view('home')
        ->with('posts', Post::recent());
});

Route::get('about', function () {
    return view('about')
        ->with('posts', Post::recent());
});

That could get annoying quickly. Instead, we’re going to use view composers to “share” that variable with a prescribed set of views. We can do this a few ways, so let’s start simple and move up.

Sharing a variable globally

First, the simplest option: just globally “share” a variable with every view in your application like in Example 4-22.

Example 4-22. Sharing a variable globally

// Some service provider
public function boot()
{
    ...
    view()->share('recentPosts', Post::recent());
}

If you want to use view()->share(), the best place would be the boot() method of a service provider so that the binding runs on every page load. You can create a custom ViewComposerServiceProvider (see Chapter 11 for more about service providers), but for now just put it in App\Providers\AppServiceProvider in the boot() method.

Using view()->share() makes the variable accessible to every view in the entire application, however, so it might be overkill.

View-Scoped View Composers with Closures

The next option is to use a closure-based view composer to share variables with a single view, like in Example 4-23.

Example 4-23. Creating a closure-based view composer

view()->composer('partials.sidebar', function ($view) {
    $view->with('recentPosts', Post::recent());
});

As you can see, we’ve defined the name of the view we want it shared with in the first parameter (partials.sidebar) and then passed a closure to the second parameter; in the closure, we’ve used $view->with() to share a variable, but now only with a specific view.

View composers for multiple views

Anywhere a view composer is binding to a particular view (like in Example 4-23, which binds to partials.sidebar), you can pass an array of view names instead to bind to multiple views.

You can also use an asterisk in the view path, as in partials.*, or tasks.*.

view()->composer(
    ['partials.header', 'partials.footer'],
    function () {
        $view->with('recentPosts', Post::recent());
    }
);

view()->composer('partials.*', function () {
    $view->with('recentPosts', Post::recent());
});

View-Scoped View Composers with Classes

Finally, the most flexible but also most complex option is to create a dedicated class for your view composer.

First, let’s create the view composer class. There’s no formally defined place for view composers to live, but the docs recommend App\Http\ViewComposers. So, let’s create App\Http\ViewComposers\RecentPostsComposer like in Example 4-24.

Example 4-24. A view composer

<?php

namespace App\Http\ViewComposers;

use App\Post;
use Illuminate\Contracts\View\View;

class RecentPostsComposer
{
    public function compose(View $view)
    {
        $view->with('recentPosts', Post::recent());
    }
}

As you can see, when this composer is called, it runs the compose() method, in which we bind the posts variable to the result of running the Post model’s recent() method.

Like the other methods of sharing variables, this view composer needs to have a binding somewhere. Again, you’d likely create a custom ViewComposerServiceProvider, but for now, as seen in Example 4-25, we’ll just put it in the boot() method of App\Providers\AppServiceProvider.

Example 4-25. Registering a view composer in AppServiceProvider

public function boot()
{
    view()->composer(
        'partials.sidebar',
        \App\Http\ViewComposers\RecentPostsComposer::class
    );
}

Note that this binding is the same as a closure-based view composer, but instead of passing a closure, we’re passing the class name of our view composer. Now, every time Blade renders the partials.sidebar view, it’ll automatically run our provider and pass the view a recentPosts variable set to the results of the recent() method on our Post model.

Blade Service Injection

There are three primary types of data we’re most likely to inject into a view: collections of data to iterate over, single objects that we’re displaying on the page, and services that generate data or views.

With a service, the pattern will most likely look like Example 4-26, where we inject an instance of our analytics service into the route definition by typehinting it in the route’s method signature, and then pass it into the view.

Example 4-26. Injecting services into a view via the route definition constructor

Route::get('backend/sales', function (AnalyticsService $analytics) {
    return view('backend.sales-graphs')
        ->with('analytics', $analytics);
});

Just as with view composers, Blade’s service injection offers a convenient shortcut to reduce duplication in your route definitions. Normally, the content of a view using our analytics service might look like Example 4-27.

Example 4-27. Using an injected navigation service in a view

<div class="finances-display">
     {{ $analytics->getBalance() }} / {{ $analytics->getBudget() }}
</div>

Blade service injection makes it easy to inject an instance of a class from the container directly from the view, like in Example 4-28.

Example 4-28. Injecting a service directly into a view

@inject('analytics', 'App\Services\Analytics')

<div class="finances-display">
     {{ $analytics->getBalance() }} / {{ $analytics->getBudget() }}
</div>

As you can see, this @inject directive has actually made an $analytics variable available, which we’re using later in our view.

The first parameter of @inject is the name of the variable you’re injecting, and the second parameter is the class or interface that you want to inject an instance of. This is resolved just like when you type hint a dependency in a constructor elsewhere in Laravel; if you’re unfamiliar with how that works, check out Chapter 11 to learn more.

Just like view composers, Blade service injection makes it easy to make certain data or functionality available to every instance of a view, without having to inject it via the route definition every time.

Custom Blade Directives

All of the built-in syntax of Blade that we’ve covered so far—@if, @unless, and so on—are called directives. Each Blade directive is a mapping between a pattern (e.g., @if ($condition)) and a PHP output (e.g., <?php if ($condition): ?>).

Directives aren’t just for the core; you can actually create your own. You might think directives are good for making little shortcuts to bigger pieces of code—for example, using @button('buttonName') and having it expand to a larger set of button HTML. This isn’t a terrible idea, but for simple code expansion like this you might be better off including a view partial.

I’ve found custom directives to be the most useful when they simplify some form of repeated logic. Say we’re tired of having to wrap our code with @if (auth()->guest()) (to check if a user is logged in or not) and we want a custom @ifGuest directive. As with view composers, it might be worth having a custom service provider to register these, but for now let’s just put it in the boot() method of App\Providers\AppServiceProvider. Take a look at Example 4-29 to see what this binding will look like.

Example 4-29. Binding a custom Blade directive in a service provider

public function boot()
{
    Blade::directive('ifGuest', function () {
        return "<?php if (auth()->guest()): ?>";
    });
}

We’ve now registered a custom directive, @ifGuest, which will be replaced with the PHP code <?php if (auth()->guest()): ?>.

This might feel strange. You’re writing a string that will be returned and then executed as PHP. But what this means is that you can now take the complex, or ugly, or unclear, or repetitive aspects of your PHP templating code and hide them behind clear, simple, and expressive syntax.

Custom directive result caching

You might be tempted to do some logic to make your custom directive faster by performing an operation in the binding and then embedding the result within the returned string:

Blade::directive('ifGuest', function () {
    // Antipattern! Do not copy.
    $ifGuest = auth()->guest();
    return "<?php if ({$ifGuest}): ?>";
});

The problem with this idea is that it assumes this directive will be re-created on every page load. However, Blade caches aggressively, so you’re going to find yourself in a bad spot if you try this.

Parameters in Custom Blade Directives

What if you want to accept parameters in your custom logic? Check out Example 4-30.

Example 4-30. Creating a Blade directive with parameters

// Binding
Blade::directive('newlinesToBr', function ($expression) {
    return "<?php echo nl2br({$expression}); ?>";
});

// In use
<p>@newlinesToBr($message->body)</p>

The $expression parameter received by the closure represents whatever’s within the parentheses. As you can see, we then generate a valid PHP code snippet and return it.

$expression parameter scoping before Laravel 5.3

Before Laravel 5.3, the $expression parameter also included the parentheses themselves. So, in Example 4-30, $expression (which is $message->body in Laravel 5.3 and later) would have instead been ($message->body), and we would’ve had to write <?php echo nl2br{$expression}; ?>.

If you find yourself constantly writing the same conditional logic over and over, you should consider a Blade directive.

Example: Using Custom Blade Directives for a Multitenant App

So, let’s imagine we’re building an application that supports multitenancy, which means users might be visiting the site from www.myapp.com, client1.myapp.com, client2.myapp.com, or elsewhere.

Suppose we have written a class to encapsulate some of our multitenancy logic and named it Context. This class will capture information and logic about the context of the current visit, such as who the authenticated user is and whether the user is visiting the public website or a client subdomain.

We’ll probably frequently resolve that Context class in our views and perform conditionals on it, like in Example 4-31. The app('context') is a shortcut to get an instance of a class from the container, which we’ll learn more about in Chapter 11.

Example 4-31. Conditionals on context without a custom Blade directive

@if (app('context')->isPublic())
    &copy; Copyright MyApp LLC
@else
    &copy; Copyright {{ app('context')->client->name }}
@endif

What if we could simplify @if (app('context')->isPublic()) to just @ifPublic? Let’s do it. Check out Example 4-32.

Example 4-32. Conditionals on context with a custom Blade directive

// Binding
Blade::directive('ifPublic', function () {
    return "<?php if (app('context')->isPublic()): ?>";
});

// In use
@ifPublic
    &copy; Copyright MyApp LLC
@else
    &copy; Copyright {{ app('context')->client->name }}
@endif

Since this resolves to a simple if statement, we can still rely on the native @else and @endif conditionals. But if we wanted, we could also create a custom @elseIfClient directive, or a separate @ifClient directive, or really whatever else we want.

Easier custom directives for “if” statements

While custom Blade directives are powerful, the most common use for them are if statements. So there’s a simpler way to create custom “if” directives: Blade::if. Let’s take a look at refactoring Example 4-32 using the Blade::if method:

Example 4-33.

// Binding
Blade::if('ifPublic', function () {
    return (app('context'))->isPublic();
});

You’ll use the directives exactly the same, but as you can see, defining them is just a bit simpler. Instead of having to manually type out PHP braces, you can just write a closure that returns a boolean.

Testing

The most common method of testing views is through application testing, meaning that you’re actually calling the route that displays the views and ensuring the views have certain content (see Example 4-34). You can also click buttons or submit forms and ensure that you are redirected to a certain page, or that you see a certain error. (You’ll learn more about testing in Chapter 12.)

Example 4-34. Testing that a view displays certain content

// EventsTest.php
public function test_list_page_shows_all_events()
{
    $event1 = factory(Event::class)->create();
    $event2 = factory(Event::class)->create();

    $this->get('events')
        ->assertSee($event1->title)
        ->assertSee($event2->title);
}

You can also test that a certain view has been passed a particular set of data, which, if it accomplishes your testing goals, is less fragile than checking for certain text on the page. Example 4-35 demonstrates this approach.

Example 4-35. Testing that a view was passed certain content

// EventsTest.php
public function test_list_page_shows_all_events()
{
    $event1 = factory(Event::class)->create();
    $event2 = factory(Event::class)->create();

    $response = $this->get('events');

    $response->assertViewHas('events', Event::all());
    $response->assertViewHasAll([
        'events' => Event::all(),
        'title' => 'Events Page'
    ]);
    $response->assertViewMissing('dogs');
}

Note

In projects running versions of Laravel prior to 5.4 get and assertSee should be replaced by visit and see.

In 5.3, we gained the ability to pass a closure to $assertViewHas(), meaning we can customize how we want to check more complex data structures. Example 4-36 illustrates how we might use this.

Example 4-36. Passing a closure to assertViewHas()

// EventsTest.php
public function test_list_page_shows_all_events()
{
    $event1 = factory(Event::class)->create();

    $response = $this->get("events/{ $event->id }");

    $response->assertViewHas('event', function ($event) use ($event1) {
        return $event->id === $event1->id;
    });
}

TL;DR

Blade is Laravel’s templating engine. Its primary focus is a clear, concise, and expressive syntax with powerful inheritance and extensibility. Its “safe echo” brackets are {{ and }}, its unprotected echo brackets are {!! and !!}, and it has a series of custom tags called directives that all begin with @ (@if and @unless, for example).

You can define a parent template and leave “holes” in it for content using @yield and @section/@show. You can then teach its child views to extend it using @extends('parent.view.name'), and define their sections using @section/@endsection. You use @parent to reference the content of the block’s parent.

View composers make it easy to define that, every time a particular view or subview loads, it should have certain information available to it. And service injection allows the view itself to request data straight from the application container.

Previous Chapter

3. Routing and Controllers

Next Chapter

5. Database and Eloquent

Table of Contents for Laravel: Up & Running, 2nd Edition