Laravel’s kernel

The kernel is the core router of every Laravel application, responsible for taking in a user request, processing it through middleware, handling exceptions and passing it to the page router, and then returning the final response. Actually, there are two kernels, but only one is used for each page request. One of the routers handles web requests (the HTTP kernel) and the other handles console, cron, and Artisan requests (the console kernel). Each has a handle() method that’s responsible for taking in an Illuminate Request object and returning an Illuminate Response object.

The kernel runs all of the bootstraps that need to run before every request, including determining which environment the current request is running in (staging, local, production, etc.) and running all of the service providers. The HTTP kernel additionally defines the list of middleware that will wrap each request, including the core middleware responsible for sessions and CSRF protection.

boot(), register(), and deferring on service providers

Service providers have two important methods: boot() and register(). There’s also a DeferrableProvider interface (5.8+) or a $defer property (5.7 and earlier) that you might choose to use. Here’s how they work.

First, all of the service providers’ register() methods are called. This is where you’ll want to bind classes and aliases to the container. You don’t want to do anything in register() that relies on the entire application being bootstrapped.

Second, all of the service providers’ boot() methods are called. You can now do any other bootstrapping here, like binding event listeners or defining routes—anything that may rely on the entire Laravel application having been bootstrapped.

If your service provider is only going to register bindings in the container (i.e., teach the container how to resolve a given class or interface), but not perform any other bootstrapping, you can “defer” its registrations, which means they won’t run unless one of their bindings is explicitly requested from the container. This can speed up your application’s average time to bootstrap.

If you want to defer your service provider’s registrations, in 5.8+, first implement the IlluminateContractsSupportDeferrableProvider interface; or, in 5.7 and earlier, first give it a protected $defer property and set it to true; and then, in all versions, give the service provider a provides() method that returns a list of bindings the provider provides, as shown in Example 10-1.

...
use IlluminateContractsSupportDeferrableProvider;

class GitHubServiceProvider extends ServiceProvider implements DeferrableProvider
{
    public function provides()
    {
        return [
            GitHubClient::class,
        ];
    }

Now that we’ve covered the application bootstrap, let’s take a look at the Request object, the most important output of the bootstrap.

Basic user input

The basic user input methods make it simple to get information that the users themselves explicitly provide—likely through submitting a form or an Ajax component. When I reference “user-provided input” here, I’m talking about input from query strings (GET), form submissions (POST), or JSON. The basic user input methods include the following:

all()

Returns an array of all user-provided input.

input(fieldName)

Returns the value of a single user-provided input field.

only(fieldName|[array,of,field,names])

Returns an array of all user-provided input for the specified field name(s).

except(fieldName|[array,of,field,names])

Returns an array of all user-provided input except for the specified field name(s).

exists(fieldName)

Returns a Boolean indicating whether the field exists in the input. has() is an alias.

filled(fieldName)

Returns a Boolean indicating whether the field exists in the input and is not empty (that is, has a value).

json()

Returns a ParameterBag if the page had JSON sent to it.

json(keyName)

Returns the value of the given key from the JSON sent to the page.

Example 10-3 gives a few quick examples of how to use the user-provided information methods from a request.

// form
<form method="POST" action="/form">
    @csrf
    <input name="name"> Name<br>
    <input type="submit">
</form>

// Route receiving the form
Route::post('form', function (Request $request) {
    echo 'name is ' . $request->input('name') . '<br>';
    echo 'all input is ' . print_r($request->all()) . '<br>';
    echo 'user provided email address: ' . $request->has('email') ? 'true' : 'false';
});

User and request state

The user and request state methods include input that wasn’t explicitly provided by the user through a form:

method()

Returns the method (GET, POST, PATCH, etc.) used to access this route.

path()

Returns the path (without the domain) used to access this page; for example, http://www.myapp.com/abc/def would return abc/def.

url()

Returns the URL (with the domain) used to access this page; for example, http://www.myapp.com/abc would return http://www.myapp.com/abc.

is()

Returns a Boolean indicating whether or not the current page request fuzzy-matches a provided string (e.g., /a/b/c would be matched by $request->is('*b*'), where * stands for any characters); uses a custom regex parser found in Str::is().

ip()

Returns the user’s IP address.

header()

Returns an array of headers (e.g., ['accept-language' => ['en-US,en;q=0.8']]), or, if passed a header name as a parameter, returns just that header.

server()

Returns an array of the variables traditionally stored in $_SERVER (e.g., REMOTE_ADDR), or, if passed a $_SERVER variable name, returns just that value.

secure()

Returns a Boolean indicating whether this page was loaded using HTTPS.

pjax()

Returns a Boolean indicating whether this page request was loaded using Pjax.

wantsJson()

Returns a Boolean indicating whether this request has any /json content types in its Accept headers.

isJson()

Returns a Boolean indicating whether this page request has any /json content types in its Content-Type header.

accepts()

Returns a Boolean indicating whether this page request accepts a given content type.

Files

So far, all of the input we’ve covered is either explicit (retrieved by methods like all(), input(), etc.) or defined by the browser or referring site (retrieved by methods like pjax()). File inputs are similar to explicit user input, but they’re handled much differently:

file()

Returns an array of all uploaded files, or, if a key is passed (the file upload field name), returns just the one file.

allFiles()

Returns an array of all uploaded files; useful as opposed to file() because of clearer naming.

hasFile()

Returns a Boolean indicating whether a file was uploaded at the specified key.

Every file that’s uploaded will be an instance of SymfonyComponentHttpFoundationFileUploadedFile, which provides a suite of tools for validating, processing, and storing uploaded files.

Take a look at Chapter 14 for more examples of how to handle uploaded files.

Persistence

The request can also provide functionality for interacting with the session. Most session functionality lives elsewhere, but there are a few methods that are particularly relevant to the current page request:

flash()

Flashes the current request’s user input to the session to be retrieved later, which means it’s saved to the session but disappears after the next request.

flashOnly()

Flashes the current request’s user input for any keys in the provided array.

flashExcept()

Flashes the current request’s user input, except for any keys in the provided array.

old()

Returns an array of all previously flashed user input, or, if passed a key, returns the value for that key if it was previously flashed.

flush()

Wipes all previously flashed user input.

cookie()

Retrieves all cookies from the request, or, if a key is provided, retrieves just that cookie.

hasCookie()

Returns a Boolean indicating whether the request has a cookie for the given key.

The flash*() and old() methods are used for storing user input and retrieving it later, often after the input is validated and rejected.

Setting headers

We define a header on a response by using the header() fluent method, like in Example 10-5. The first parameter is the header name, and the second is the header value.

Adding cookies

We can also set cookies directly on the Response object if we’d like. We’ll cover Laravel’s cookie handling a bit more in Chapter 14, but take a look at Example 10-6 for a simple use case for attaching cookies to a response.

    return response($content)
        ->cookie('signup_dismissed', true);

View responses

In Chapter 4, I used the global view() helper to show how to return a template—for example, view('view.name.here') or something similar. But if you need to customize the headers, HTTP status, or anything else when returning a view, you can use the view() response type as shown in Example 10-7.

Route::get('/', function (XmlGetterService $xml) {
    $data = $xml->get();
    return response()
        ->view('xml-structure', $data)
        ->header('Content-Type', 'text/xml');
});

Download responses

Sometimes you want your application to force the user’s browser to download a file, whether you’re creating the file in Laravel or serving it from a database or a protected location. The download() response type makes this simple.

The required first parameter is the path for the file you want the browser to download. If it’s a generated file, you’ll need to save it somewhere temporarily.

The optional second parameter is the filename for the downloaded file (e.g., export.csv). If you don’t pass a string here, it will be generated automatically. The optional third parameter allows you to pass an array of headers. Example 10-8 illustrates the use of the download() response type.

public function export()
{
    return response()
        ->download('file.csv', 'export.csv', ['header' => 'value']);
}

public function otherExport()
{
    return response()->download('file.pdf');
}

If you wish to delete the original file from the disk after returning a download response, you can chain the deleteFileAfterSend() method after the download() method:

public function export()
{
    return response()
        ->download('file.csv', 'export.csv')
        ->deleteFileAfterSend();
}

File responses

The file response is similar to the download response, except it allows the browser to display the file instead of forcing a download. This is most common with images and PDFs.

The required first parameter is the filename, and the optional second parameter can be an array of headers (see Example 10-9).

public function invoice($id)
{
    return response()->file("./invoices/{$id}.pdf", ['header' => 'value']);
}

JSON responses

JSON responses are so common that, even though they’re not really particularly complex to program, there’s a custom response for them as well.

JSON responses convert the passed data to JSON (with json_encode()) and set the Content-Type to application/json. You can also optionally use the setCallback() method to create a JSONP response instead of JSON, as seen in Example 10-10.

public function contacts()
{
    return response()->json(Contact::all());
}

public function jsonpContacts(Request $request)
{
    return response()
        ->json(Contact::all())
        ->setCallback($request->input('callback'));
}

public function nonEloquentContacts()
{
    return response()->json(['Tom', 'Jerry']);
}

Redirect responses

Redirects aren’t commonly called on the response() helper, so they’re a bit different from the other custom response types we’ve discussed already, but they’re still just a different sort of response. Redirects, returned from a Laravel route, send the user a redirect (often a 301) to another page or back to the previous page.

You technically can call a redirect from response(), as in return response()->redirectTo('/'). But more commonly, you’ll use the redirect-specific global helpers.

There is a global redirect() function that can be used to create redirect responses, and a global back() function that is a shortcut to redirect()->back().

Just like most global helpers, the redirect() global function can either be passed parameters or be used to get an instance of its class that you then chain method calls onto. If you don’t chain, but just pass parameters, redirect() performs the same as redirect()->to(); it takes a string and redirects to that string URL. Example 10-11 shows some examples of its use.

return redirect('account/payment');
return redirect()->to('account/payment');
return redirect()->route('account.payment');
return redirect()->action('AccountController@showPayment');

// If redirecting to an external domain
return redirect()->away('https://tighten.co');

// If named route or controller needs parameters
return redirect()->route('contacts.edit', ['id' => 15]);
return redirect()->action('ContactController@edit', ['id' => 15]);

You can also redirect “back” to the previous page, which is especially useful when handling and validating user input. Example 10-12 shows a common pattern in validation contexts.

public function store()
{
    // If validation fails...
    return back()->withInput();
}

Finally, you can redirect and flash data to the session at the same time. This is common with error and success messages, like in Example 10-13.

Route::post('contacts', function () {
    // Store the contact

    return redirect('dashboard')->with('message', 'Contact created!');
});

Route::get('dashboard', function () {
    // Get the flashed data from session--usually handled in Blade template
    echo session('message');
});

Custom response macros

You can also create your own custom response types using macros. This allows you to define a series of modifications to make to the response and its provided content.

Let’s recreate the json() custom response type, just to see how it works. As always, you should probably create a custom service provider for these sorts of bindings, but for now we’ll just put it in AppServiceProvider, as seen in Example 10-14.

...
class AppServiceProvider
{
    public function boot()
    {
        Response::macro('myJson', function ($content) {
            return response(json_encode($content))
                ->withHeaders(['Content-Type' => 'application/json']);
        });
    }

Then, we can use it just like we would use the predefined json() macro:

return response()->myJson(['name' => 'Sangeetha']);

This will return a response with the body of that array encoded for JSON, with the JSON-appropriate Content-Type header.

The Responsable interface

If you’d like to customize how you’re sending responses and a macro doesn’t offer enough space or enough organization, or if you want any of your objects to be capable of being returned as a “response” with their own logic of how to be displayed, the Responsable interface (introduced in Laravel 5.5) is for you.

The Responsable interface, IlluminateContractsSupportResponsable, dictates its implementors must have a toResponse() method. This needs to return an Illuminate Response object. Example 10-15 illustrates how to create a Responsable object.

...
use IlluminateContractsSupportResponsable;

class MyJson implements Responsable
{
    public function __construct($content)
    {
        $this->content = $content;
    }

    public function toResponse()
    {
        return response(json_encode($this->content))
            ->withHeaders(['Content-Type' => 'application/json']);
    }

Then, we can use it just like our custom macro:

return new MyJson(['name' => 'Sangeetha']);

This probably looks like a lot of work relative to the response macros we covered earlier. But the Responsable interface really shines when you’re working with more complicated controller manipulations. One common example is to use it to create view models (or view objects), like in Example 10-16.

...
use IlluminateContractsSupportResponsable;

class GroupDonationDashboard implements Responsable
{
    public function __construct($group)
    {
        $this->group = $group;
    }

    public function budgetThisYear()
    {
        // ...
    }

    public function giftsThisYear()
    {
        // ...
    }

    public function toResponse()
    {
        return view('groups.dashboard')
            ->with('annual_budget', $this->budgetThisYear())
            ->with('annual_gifts_received', $this->giftsThisYear());
    }

It starts to make a little bit more sense in this context—move your complex view preparation into a dedicated, testable object, and keep your controllers clean. Here’s a controller that uses that Responsable object:

...
class GroupController
{
    public function index(Group $group)
    {
        return new GroupDonationsDashboard($group);
    }

Understanding middleware’s handle() method

First, remember that middleware are layered one on top of another, and then finally on top of the app. The first middleware that’s registered gets first access to a request when it comes in, then that request is passed to every other middleware in turn, then to the app; then the resulting response is passed outward through the middleware, and finally this first middleware gets last access to the response when it goes out.

Let’s imagine we’ve registered BanDeleteMethod as the first middleware to run. That means the $request coming into it is the raw request, unadulterated by any other middleware. Now what?

Passing that request to $next() means handing it off to the rest of the middleware. The $next() closure just takes that $request and passes it to the handle() method of the next middleware in the stack. It then gets passed on down the line until there are no more middleware to hand it to, and it finally ends up at the application.

Next, how does the response come out? This is where it might be hard to follow. The application returns a response, which is passed back up the chain of middleware—because each middleware returns its response. So, within that same handle() method, the middleware can decorate a $request and pass it to the $next() closure, and can then choose to do something with the output it receives before finally returning that output to the end user. Let’s look at some pseudocode to make this clearer (Example 10-18).

...
class BanDeleteMethod
{
    public function handle($request, Closure $next)
    {
        // At this point, $request is the raw request from the user.
        // Let's do something with it, just for fun.
        if ($request->ip() === '192.168.1.1') {
            return response('BANNED IP ADDRESS!', 403);
        }

        // Now we've decided to accept it. Let's pass it on to the next
        // middleware in the stack. We pass it to $next(), and what is
        // returned is the response after the $request has been passed
        // down the stack of middleware to the application and the
        // application's response has been passed back up the stack.
        $response = $next($request);

        // At this point, we can once again interact with the response
        // just before it is returned to the user
        $response->cookie('visited-our-site', true);

        // Finally, we can release this response to the end user
        return $response;
    }
}

Finally, let’s make the middleware do what we actually promised (Example 10-19).

...
class BanDeleteMethod
{
    public function handle($request, Closure $next)
    {
        // Test for the DELETE method
        if ($request->method() === 'DELETE') {
            return response(
                "Get out of here with that delete method",
                405
            );
        }

        $response = $next($request);

        // Assign cookie
        $response->cookie('visited-our-site', true);

        // Return response
        return $response;
    }
}

Binding global middleware

Both bindings happen in app/Http/Kernel.php. To add a middleware as global, add its class name to the $middleware property, as in Example 10-20.

// app/Http/Kernel.php
protected $middleware = [
    AppHttpMiddlewareTrustProxies::class,
    IlluminateFoundationHttpMiddlewareCheckForMaintenanceMode::class,
    AppHttpMiddlewareBanDeleteMethod::class,
];

Binding route middleware

Middleware intended for specific routes can be added as a route middleware or as part of a middleware group. Let’s start with the former.

Route middleware are added to the $routeMiddleware array in app/Http/Kernel.php. It’s similar to adding them to $middleware, except we have to give one a key that will be used when applying this middleware to a particular route, as seen in Example 10-21.

// app/Http/Kernel.php
protected $routeMiddleware = [
    'auth' => AppHttpMiddlewareAuthenticate::class,
    ...
    'ban-delete' => AppHttpMiddlewareBanDeleteMethod::class,
];

We can now use this middleware in our route definitions, like in Example 10-22.

// Doesn't make much sense for our current example...
Route::get('contacts', 'ContactController@index')->middleware('ban-delete');

// Makes more sense for our current example...
Route::prefix('api')->middleware('ban-delete')->group(function () {
    // All routes related to an API
});

Using middleware groups

Laravel 5.2 introduced the concept of middleware groups. They’re essentially pre-packaged bundles of middleware that make sense to be together in specific contexts.

Out of the box there are two groups: web and api. web has all the middleware that will be useful on almost every Laravel page request, including middleware for cookies, sessions, and CSRF protection. api has none of those—it has a throttling middleware and a route model binding middleware, and that’s it. These are all defined in app/Http/Kernel.php.

You can apply middleware groups to routes just like you apply route middleware to routes, with the middleware() fluent method:

Route::get('/', 'HomeController@index')->middleware('web');

You can also create your own middleware groups and add and remove route middleware to and from preexisting middleware groups. It works just like adding route middleware normally, but you’re instead adding them to keyed groups in the $middlewareGroups array.

You might be wondering how these middleware groups match up with the two default routes files. Unsurprisingly, the routes/web.php file is wrapped with the web middleware group, and the routes/api.php file is wrapped with the api middleware group.

The routes/* files are loaded in the RouteServiceProvider. Take a look at the map() method there (Example 10-23) and you’ll find a mapWebRoutes() method and a mapApiRoutes() method, each of which loads its respective files already wrapped in the appropriate middleware group.

// AppProvidersRouteServiceProvider
public function map()
{
    $this->mapApiRoutes();
    $this->mapWebRoutes();
}

protected function mapApiRoutes()
{
    Route::prefix('api')
         ->middleware('api')
         ->namespace($this->namespace)
         ->group(base_path('routes/api.php'));
}

protected function mapWebRoutes()
{
    Route::middleware('web')
         ->namespace($this->namespace)
         ->group(base_path('routes/web.php'));
}

As you can see in Example 10-23, we’re using the router to load a route group under the default namespace (AppHttpControllers) and with the web middleware group, and another under the api middleware group.