What's the difference between Laravel's @yield and @include?

I'm learning Laravel (starting at version 5.3) and those two look very much alike, the only difference I know is that @include inject parent's variables and can also send other variables.

  • What's the difference between @yield and @include?
  • When should I use @yield?
  • When should I use @include?

@yield is mainly used to define a section in a layout. When that layout is extended with @extends, you can define what goes in that section with the @section directive in your views.

The layout usually contains your HTML, head, body, header and footers. You define an area (@yield) within the layout that your pages which are extending the template will put their content into.

In your master template you define the area. For example:

<body>
     @yield('content')
</body>

Lets say your home page extends that layout

@extends('layouts.app')

@section('content')
     // home page content here
@endsection

Any HTML you define in the content section on your homepage view in the 'content' section will be injected into the layout it extended in that spot.

@include is used for reusable HTML just like a standard PHP include. It does not have that parent/child relationship like @yield and @section.

I highly suggest reading the documentation on Blade Templates on the Laravel site for a more comprehensive overview

https://laravel.com/docs/5.0/templates


@include and @yield are two completely different types of operations to import code into the current file.

@include - import the contents of a separate file into the current file at the location in which it is placed. i.e.:

Layout file:

< some html or other script >

@include('include.file_name') // "include." indicates the subdirectory that the file is in

< more html or other script >

Include File ( a blade file with a block of code ):

< some cool code here >

The contents of 'file_name' ( also a blade file ) is then imported in where the @include directive is located.

@yield imports code from a "section" in the child file ( the "view" blade file. ) i.e.:

Layout file:

< some html or other script >

@yield('needed_section_name')

< more html or other script >

The following section is needed in the "view" blade file that is set to "extend" that layout file.

"View" blade file:

@extends('layout.file_name')
... code as neeeded

@section('needed_section_name')
< some cool code here >
@stop

...
more code as needed

Now the layout file will import in the section of code that matches the naming used.

More on the subject here....


The difference between @yield and @include is how you use them.

If you have a static kind of content, like a navbar, this part of the page will always be in the same place in the layout. When you use @include in the layout file, the navbar will be put once per layout. But if you use @yield you will be enforced to make a @section of the navbar on every page that @extends the layout.

@yield is, on the other hand, a better choice when content is changing on all the pages but you still want to use the same layout everywhere. If you use @include you'll have to make a new layout for every page, because of the difference of content.


Today I was trying to figure out this difference as well, and where to use each, and why would I want to use one over the other. Please be warned this answer is verbose and probably very over-explained.

Snapey from the Laracasts forums got me started thinking about them properly: https://laracasts.com/discuss/channels/laravel/whats-the-difference-between-atinclude-and-atyield

First off, @include is going to include an entire file, just like the PHP include function. That's great if you're just dumping an entire file of content into the <body> of your page, for example the following is going to include everything inside of 'content.blade.php':

<!-- layout.blade.php -->

<body>

@include('content')

</body>
<!-- content.blade.php -->
<div>
    <div>
        <p>Hey this is my content.</p>
    </div>
    <div>
        <span>and stuff</span>
    </div>
</div>

But @yield, in conjunction with @extends and the @section and @endsection directives, will allow you to have your content chunked into separate sections, but kept all in one file. Then you can @yield it into the layout in separate chunks. The visual that comes to mind is shuffling one half of a deck of cards into the other half, in a classic "riffle" shuffle:

<!-- content.blade.php -->

@extends('layout')

@section('top_content')
    <h1>Hey I'm the title</h1>
@endsection

@section('middle_content')
    <p>Hey how's it going</p>
@endsection


@section('other_content')
    <p>It's over now.</p>
@endsection
<!-- layout.blade.php -->

<body>

    <div>
        @yield('top_content')
    </div>

    <p>Some static content</p>

    <div>
        @yield('middle_content')
    </div>

    <p>Some more static content</p>

    <div>
        @yield('other_content')
    </div>

    <div>Static footer content of some kind</div>

</body>

Secondly and maybe more importantly, the flow of control is sort of inverted, in a way that makes everything much more coherent. In the first example, with @include, you'd be calling the layout file with the view helper, in sort of a top-down way. For example this might be your code:

Route::get('/', function () {
    return view('layout');
});

But with @yield and @extends, (as in the second example) you call the content file itself, and the content file will first look at the @extends directive to drape itself with the layout file, like it is putting on a coat. So it happens in reverse, in a sense, like bottom-up. Then the @yield directives inject the content as specified. The content file is who you are talking to in your router/controller:

Route::get('/', function () {
    return view('content');
});

You call the content view, it looks at the @extends directive to pick the layout, and then the @yield directives in the layout file inject the matching @section sections into the layout.

So this way is much more useful because in practice you'll be referring to different content when you refer to different views.

If you were only using the @include statement to build your views, then you'd have to pass a different content slug to the layout file that you are calling every time, maybe like this:

Route::get('/welcome', function () {
    return view('layout', ['content' => 'welcome']);
});

Route::get('/profile', function () {
    return view('layout', ['content' => 'profile']);
});
<!-- layout.blade.php -->

<body>

@include($content)

</body>

And that seems like a mess to me.

That all being said, @include seems like a great way to include a little snippet in your layout file (the one called by the @extends directive), like the nav bar, or the footer, or something you just want to separate out of your layout file for organizational purposes.


@yield should be used when your contents will be changed @include should be used for contents that wont change. e.g header, footer