Sending Response Headers in Laravel

We already covered this topic quite a bit in Chapter 10, but here’s a quick refresher. Once you have a response object, you can add a header using header($headerName, $headerValue), as seen in Example 13-5.

Route::get('dogs', function () {
    return response(Dog::all())
        ->header('X-Greatness-Index', 12);
});

Nice and easy.

Reading Request Headers in Laravel

If we have an incoming request, it’s also simple to read any given header. Example 13-6 illustrates this.

Route::get('dogs', function (Request $request) {
    var_dump($request->header('Accept'));
});

Now that you can read incoming request headers and set headers on your API responses, let’s take a look at how you might want to customize your API.

Sorting Your API Results

First, let’s set up the ability to sort our results. We start in Example 13-10 with the ability to sort by only a single column, and in only a single direction.

// Handles /dogs?sort=name
Route::get('dogs', function (Request $request) {
    // Get the sort query parameter (or fall back to default sort "name")
    $sortColumn = $request->input('sort', 'name');
    return Dog::orderBy($sortColumn)->paginate(20);
});

We add the ability to invert it (e.g., ?sort=-weight) in Example 13-11.

// Handles /dogs?sort=name and /dogs?sort=-name
Route::get('dogs', function (Request $request) {
    // Get the sort query parameter (or fall back to default sort "name")
    $sortColumn = $request->input('sort', 'name');

    // Set the sort direction based on whether the key starts with -
    // using Laravel's starts_with() helper function
    $sortDirection = starts_with($sortColumn, '-') ? 'desc' : 'asc';
    $sortColumn = ltrim($sortColumn, '-');

    return Dog::orderBy($sortColumn, $sortDirection)
        ->paginate(20);
});

Finally, we do the same for multiple columns (e.g., ?sort=name,-weight) in Example 13-12.

// Handles ?sort=name,-weight
Route::get('dogs', function (Request $request) {
    // Grab the query parameter and turn it into an array exploded by ,
    $sorts = explode(',', $request->input('sort', ''));

    // Create a query
    $query = Dog::query();

    // Add the sorts one by one
    foreach ($sorts as $sortColumn) {
        $sortDirection = starts_with($sortColumn, '-') ? 'desc' : 'asc';
        $sortColumn = ltrim($sortColumn, '-');

        $query->orderBy($sortColumn, $sortDirection);
    }

    // Return
    return $query->paginate(20);
});

As you can see, it’s not the simplest process ever, and you’ll likely want to build some helper tooling around the repetitive processes, but we’re building up the customizability of our API piece by piece using logical and simple features.

Filtering Your API Results

Another common task in building APIs is filtering out all but a certain subset of data. For example, the client might ask for a list of the dogs that are Chihuahuas.

The JSON API doesn’t give us any great ideas for syntax here, other than that we should use the filter query parameter. Let’s think along the lines of the sort syntax, where we’re putting everything into a single key—maybe ?filter=breed:chihuahua. You can see how to do this in Example 13-13.

Route::get('dogs', function () {
    $query = Dog::query();

    $query->when(request()->filled('filter'), function ($query) {
        [$criteria, $value] = explode(':', request('filter'));
        return $query->where($criteria, $value);
    });

    return $query->paginate(20);
});

Note that in Example 13-13 we’re using the request() helper instead of injecting an instance of the $request. Both work the same, but sometimes the request() helper can be easier when you’re working inside of a closure so you don’t have to pass variables in manually.

And, just for kicks, in Example 13-14 we allow for multiple filters, like ?filter=breed:chihuahua,color:brown.

Route::get('dogs', function (Request $request) {
    $query = Dog::query();

    $query->when(request()->filled('filter'), function ($query) {
        $filters = explode(',', request('filter'));

        foreach ($filters as $filter) {
            [$criteria, $value] = explode(':', $filter);
            $query->where($criteria, $value);
        }

        return $query;
    });

    return $query->paginate(20);
});

Writing Your Own Transformer

The general concept of a transformer is that we are going to run every instance of our model through another class that transforms its data to a different state. It might add fields, rename fields, delete fields, manipulate fields, add nested children, or whatever else. Let’s start with a simple example (Example 13-15).

Route::get('users/{id}', function ($userId) {
    return (new UserTransformer(User::findOrFail($userId)));
});

class UserTransformer
{
    protected $user;

    public function __construct($user)
    {
        $this->user = $user;
    }

    public function toArray()
    {
        return [
            'id' => $this->user->id,
            'name' => sprintf(
                "%s %s",
                $this->user->first_name,
                $this->user->last_name
            ),
            'friendsCount' => $this->user->friends->count()
        ];
    }

    public function toJson()
    {
        return json_encode($this->toArray());
    }

    public function __toString()
    {
        return $this->toJson();
    }
}

As you can see in Example 13-15, transformers accept the model they’re transforming as a parameter and then manipulate that model—and its relationships—to create the final output that you want to send to the API.

Nesting and Relationships with custom transformers

Whether, and how, to nest relationships in APIs is an issue of much debate. Thankfully, people more experienced than me have written on this at length; I’d recommend reading Phil Sturgeon’s Build APIs You Won’t Hate (Leanpub) to learn more about this and about REST APIs in general.

There are a few primary ways to approach nesting relationships. These examples will assume your primary resource is a user and your related resource is a friend:

• Include related resources directly in the primary resource (e.g., the users/5 resource has its friends nested in it).

• Include just the foreign keys in the primary resource (e.g., the users/5 resource has an array of friend IDs nested in it).

• Allow the user to query the related resource filtered by the originating resource (e.g., /friends?user=5, or “give me all friends who are related to user #5”).

• Create a subresource (e.g., /users/5/friends).

• Allow optional including (e.g., /users/5 does not include, but /users/5?include=friends does include; so does /users/5?include=friends,dogs).

Let’s assume for a minute that we want to (optionally) include related items. How would we do that? Our transformer example in Example 13-15 gives us a great head start. Let’s adjust it in Example 13-16 to add optional sub-resource including.

// E.g. myapp.com/api/users/15?include=friends,bookmarks
Route::get('users/{id}', function ($userId, Request $request) {
    // Get the include query parameter and split by commas
    $includes = explode(',', $request->input('include', ''));
    // Pass both user and includes to the user transformer
    return (new UserTransformer(User::findOrFail($userId), $includes));
});

class UserTransformer
{
    protected $user;
    protected $includes;

    public function __construct($user, $includes = [])
    {
        $this->user = $user;
        $this->includes = $includes;
    }

    public function toArray()
    {
        $append = [];

        if (in_array('friends', $this->includes)) {
            // If you have more than one include, you'll want to generalize this
            $append['friends'] = $this->user->friends->map(function ($friend) {
                return (new FriendTransformer($friend))->toArray();
            });
        }

        return array_merge([
            'id' => $this->user->id,
            'name' => sprintf(
                "%s %s",
                $this->user->first_name,
                $this->user->last_name
            )
        ], $append);
    }
...

We’ll learn more about the map() functionality when we look at collections in Chapter 17, but everything else in here should be pretty familiar.

In the route, we’re splitting the include query parameter by commas and passing it into our transformer. Currently our transformer can just handle the friends include, but it could be abstracted to handle others. If the user has requested the friends include, the transformer maps over each friend (using the hasMany friends relationship on the user model), passes that friend to the FriendTransformer, and includes the array of all transformed friends in the user response.

Creating a Resource Class

Let’s walk through this Dog example to see what it looks like to transform our API output. First, use the Artisan command make:resource to create your first resource.

php artisan make:resource Dog

This will create a new class in app/Http/Resources/Dog.php, which contains one method: toArray. You can see what the file looks like in Example 13-17.

<?php

namespace App\Http\Resources;

use Illuminate\Http\Resources\Json\JsonResource;

class Dog extends JsonResource
{
    /**
     * Transform the resource into an array.
     *
     * @param  \Illuminate\Http\Request  $request
     * @return array
     */
    public function toArray($request)
    {
        return parent::toArray($request);
    }
}

The toArray method we’re working with here has access to two important pieces of data. First, it has access to the Illuminate Request object, so we can customize our response based on query parameters and headers and anything else important. And second, it has access to the entire Eloquent object being transformed by calling its properties and methods on $this, as you can see in Example 13-18.

class Dog extends JsonResource
{
    public function toArray($request)
    {
        return [
            'id' => $this->id,
            'name' => $this->name,
            'breed' => $this->breed,
        ];
    }
}

To use this new resource, you’d want to update any API endpoint that returns a single Dog to wrap the response in your new Resource, like in Example 13-19.

use App\Dog;
use App\Http\Resources\Dog as DogResource;

Route::get('dogs/{dogId}', function ($dogId) {
    return new DogResource(Dog::find($dogId));
});

Resource Collections

Now, let’s talk about what happens if you have more than one of your entity returning from a given API endpoint. API resources can do that with the collection() method, as you can see in Example 13-20.

use App\Dog;
use App\Http\Resources\Dog as DogResource;

Route::get('dogs', function () {
    return DogResource::collection(Dog::all());
});

This method iterates over every entry that’s passed to it, transforms it with the DogResource API resource, and then returns the collection.

This will likely be enough for many APIs, but if you need to customize any of the structure or add metadata to your collection responses, you’ll want to instead create a custom API resource collection.

In order to do so, let’s reach for the make:resource Artisan command again, but this time we’ll name it DogCollection, which signals to Laravel this is an API resource collection, not just an API resource.

php artisan make:resource DogCollection

This will generate a new file very similar to the API resource, living at app/Http/Resources/DogCollection.php, which contains one method: toArray. You can see what the file looks like in Example 13-21.

<?php

namespace App\Http\Resources;

use Illuminate\Http\Resources\Json\ResourceCollection;

class DogCollection extends ResourceCollection
{
    /**
     * Transform the resource collection into an array.
     *
     * @param  \Illuminate\Http\Request  $request
     * @return array
     */
    public function toArray($request)
    {
        return parent::toArray($request);
    }
}

Just like the API resource, we have access to the request and the underlying data. But unlike the API resource, we’re dealing with a collection of items instead of just one, so we will access that (already-transformed) collection as $this->collection. Take a look at Example 13-22 for an example.

class DogCollection extends ResourceCollection
{
    public function toArray($request)
    {
        return [
            'data' => $this->collection,
            'links' => [
                'self' => route('dogs.index'),
            ],
        ];
    }
}

Nesting Relationships

One of the more complicated aspects of any API is how relationships are nested. The simplest way with API resources is to add a key to your returned array that’s set to an API resource collection, like in Example 13-23.

public function toArray()
{
    return [
        'name' => $this->name,
        'breed' => $this->breed,
        'friends' => DogResource::collection($this->friends),
    ];
}

You may also want this to be a conditional property; you can choose to only nest it if it’s asked for in the request, or only if it’s already been eager loaded on the Eloquent object that’s passed in. Take a look at Example 13-24.

public function toArray()
{
    return [
        'name' => $this->name,
        'breed' => $this->breed,
        // Only load this relationship if it's been eager loaded
        'bones' => BoneResource::collection($this->whenLoaded('bones')),
        // Or, only load this relationship if the URL asks for it
        'bones' => $this->when(
            $request->get('include') == 'bones',
            BoneResource::collection($this->bones)
        ),
    ];
}

Using Pagination with API Resources

Just like you can pass a collection of Eloquent models to a resource, you can also pass a paginator instance as well. Take a look at Example 13-25.

Route::get('dogs', function () {
    return new DogCollection(Dog::paginate(20));
});

If you pass a paginator instance, the transformed result will have additional links containing pagination information (first page, last page, prev page, and next page) and meta information about the entire collection.

You can take a look at Example 13-26 to see what this information looks like. In this example, I’ve set the items-per-page to 2 by calling Dog::paginate(2) so you can more easily see how the links work.

{
    "data": [
        {
            "name": "Pickles",
            "breed": "Chorkie",
        },
        {
            "name": "Gandalf",
            "breed": "Golden Retriever Mix",
        }
    ],
    "links": {
        "first": "http://gooddogbrant.com/api/dogs?page=1",
        "last": "http://gooddogbrant.com/api/dogs?page=3",
        "prev": null,
        "next": "http://gooddogbrant.com/api/dogs?page=2"
    },
    "meta": {
        "current_page": 1,
        "from": 1,
        "last_page": 3,
        "path": "http://gooddogbrant.com/api/dogs",
        "per_page": 2,
        "to": 2,
        "total": 5
    }
}

Conditionally Applying Attributes

You can also specify that certain attributes in your response should only be applied when a particular test is satisfied.

public function toArray($request)
{
    return [
        'name' => $this->name,
        'breed' => $this->breed,
        'rating' => $this->when(Auth::user()->canSeeRatings(), 12),
    ];
}

More Customizations for API Resources

The default shape of how the data property is wrapped might not be how you like it, or you may find yourself needing to add or customize metadata for the responses. Take a look at the docs for how to customize every aspect of your API responses.

A Brief Introduction to OAuth 2.0

OAuth is by far the most common auth system used in RESTful APIs. Unfortunately, it’s far too complex a topic for us to cover here in depth. For further reading, Matt Frost has written a great book on OAuth and PHP titled Integrating Web Services with OAuth and PHP (php[architect]).

Here’s the simplest concept behind OAuth: because APIs are stateless, we can’t rely on the same session-bassed authentication that we do in normal browser-based viewing sessions, where the user logs in and their authenticated state is saved to the session for subsequent views. Instead, the API client needs to make a single call to an authentication endpoint, perform some form of handshake to prove themselves, and then get back a token. Then, the client must send this token along with every future request (via the Authorization header, usually) to prove their identity.

There are a few different types of OAuth “grant”, which basically means that there are several different scenarios and types of interaction that can define that authentication “handshake”. Different projects and different sorts of end consumer will necessitate different grants.

If you’re working with Laravel 5.1 or 5.2, there’s a Laravel package called OAuth 2.0 Server for Laravel that makes it relatively easy to add a basic OAuth 2.0 authentication server to your Laravel application. It’s a Laravel convenience bridge to a PHP package called PHP OAuth 2.0 Server.

However, if you’re on Laravel 5.3 and higher, Passport gives you everything provided by that package and much more, with a simpler and more powerful API and interface.

Installing Passport

Passport is a separate package, so your first step is to install it. I’ll sum up the steps here, but you can get more in-depth installation instructions in the docs.

First, bring it in with Composer:

composer require laravel/passport

If you’re working with Laravel below 5.5, add Laravel\Passport\PassportServiceProvider::class to the providers array of config/app.php.

Passport imports a series of migrations, so run those with php artisan migrate to create the tables necessary for OAuth clients, scopes, and tokens.

Next, run the installer with php artisan passport:install. This is going to create encryption keys for the OAuth server (storage/oauth-private.key and storage/oauth-public.key) and insert OAuth clients into the database for our personal and password grant type tokens (which we’ll cover later).

You’ll need to import the Laravel\Passport\HasApiTokens trait into your User model; this will add OAuth client- and token-related relationships to each User, as well as a few token-related helper methods. Next, add a call to Laravel\Passport\Passport::routes() in the boot() method of the AuthServiceProvider. This will add the following routes:

• oauth/authorize

• oauth/clients

• oauth/clients/{client_id}

• oauth/personal-access-tokens

• oauth/personal-access-tokens/{token_id}

• oauth/scopes

• oauth/token

• oauth/token/refresh

• oauth/tokens

• oauth/tokens/{token_id}

Finally, look for the api guard in config/auth.php. By default this guard will use the token driver (which we’ll cover shortly), but we’ll change that to be the passport driver instead.

You now have a fully functional OAuth 2.0 server! You can create new clients with php artisan passport:client, and you have an API for managing your clients and tokens available under the /oauth route prefix.

To protect a route behind your Passport auth system, add the auth:api middleware to the route or route group, as shown in Example 13-27.

// routes/api.php
Route::get('/user', function (Request $request) {
    return $request->user();
})->middleware('auth:api');

In order to authenticate to these protected routes, your client apps will need to pass a token (we’ll cover how to get one next) as a Bearer token in the Authorization header. Example 13-28 shows what this would look like if you were making a request using the Guzzle HTTP library.

$http = new GuzzleHttp\Client;
$response = $http->request('GET', 'http://tweeter.test/api/user', [
    'headers' => [
        'Accept' => 'application/json',
        'Authorization' => 'Bearer ' . $accessToken,
    ],
]);

Now, let’s take a closer look at how it all works.

Passport’s API

Passport exposes an API in your application under the /oauth route prefix. The API provides two primary functions: first, to authorize users with OAuth 2.0 authorization flows (/oauth/authorize and /oauth/token), and second, to allow users to manage their clients and tokens (the rest of the routes).

This is an important distinction, especially if you’re unfamiliar with OAuth. Every OAuth server needs to expose the ability for consumers to authenticate with your server; that’s the entire point of the service. But Passport also exposes an API for managing the state of your OAuth server’s clients and tokens. This means you can easily build a frontend to let your users manage their information in your OAuth application, and Passport actually comes with Vue-based manager components that you can either use or use for inspiration.

We’ll cover the API routes that allow you to manage clients and tokens, and the Vue components that Passport ships with to make it easy, but first let’s dig into the various ways your users can authenticate with your Passport-protected API.

Passport’s Available Grant Types

Passport makes it possible for you to authenticate users in four different ways. Two are traditional OAuth 2.0 grants (the password grant and authorization code grant) and two are convenience methods that are unique to Passport (the personal token and synchronizer token).

php artisan passport:client --password

 What should we name the password grant client?
   [My Application Password Grant Client]:
 > SpaceBook_internal

Password grant client created successfully.
Client ID: 3
Client Secret: Pg1EEzt18JAnFoUIM9n38Nqewg1aekB4rvFk2Pma

// Routes/web.php in the *consuming application*
Route::get('tweeter/password-grant-auth', function () {
    $http = new GuzzleHttp\Client;

    // Make call to "Tweeter", our Passport-powered OAuth server
    $response = $http->post('http://tweeter.test/oauth/token', [
        'form_params' => [
            'grant_type' => 'password',
            'client_id' => config('tweeter.id'),
            'client_secret' => config('tweeter.secret'),
            'username' => 'matt@mattstauffer.co',
            'password' => 'my-tweeter-password',
            'scope' => '',
        ],
    ]);

    $thisUsersTokens = json_decode((string) $response->getBody(), true);
    // do stuff with the tokens
});

Authorization code grant

The most common OAuth 2.0 auth workflow is also the most complex one Passport supports. Let’s imagine we’re developing an application that’s like Twitter but for sound clips; we’ll call it Tweeter. And we’ll imagine another website, a social network for science fiction fans, called SpaceBook. SpaceBook’s developer wants to let people embed their Tweeter data into their SpaceBook newsfeeds. We’re going to install Passport in our app Tweeter so that other apps—SpaceBook, for example—can allow their mutual users to authenticate with their Tweeter information.

In the authorization code grant type, each consuming website—SpaceBook, in this example—needs to create a “client” in our Passport-enabled app. In most scenarios, the other sites’ admins will have user accounts at Tweeter, and we’ll build tools for them to create clients there. But for starters, we can just manually create a client for the SpaceBook admins:

php artisan passport:client
Which user ID should the client be assigned to?:
 > 1 

 What should we name the client?:
 > SpaceBook
 Where should we redirect the request after authorization?
   [http://tweeter.test/auth/callback]:
 > http://spacebook.test/tweeter/callback

 New client created successfully.
 Client ID: 4
 Client secret: 5rzqKpeCjIgz3MXpi3tjQ37HBnLLykrgWgmc18uH

Every client needs to be assigned to a user in your app. Imagine Jill, user #1, is writing SpaceBook; she’ll be the “owner” of this client we’re creating.

Now we have the ID and secret for the SpaceBook client. At this point, SpaceBook can use this ID and secret to build tooling allowing an individual SpaceBook user (who is also a Tweeter user) to get an auth token from Tweeter for use when SpaceBook wants to make API calls to Tweeter on that user’s behalf. Example 13-30 illustrates this. (This and the following examples assume SpaceBook is a Laravel app, too; they also assume the Spacebook developers created a file at config/tweeter.php that returns the ID and secret we just created.)

Example 13-30. A consumer app redirecting a user to our OAuth server

// In SpaceBook's routes/web.php:
Route::get('tweeter/redirect', function () {
    $query = http_build_query([
        'client_id' => config('tweeter.id'),
        'redirect_uri' => url('tweeter/callback'),
        'response_type' => 'code',
        'scope' => '',
    ]);

    // Builds a string like:
    // client_id={$client_id}&redirect_uri={$redirect_uri}&response_type=code

    return redirect('http://tweeter.test/oauth/authorize?' . $query);
});

When users hit that route in SpaceBook, they’ll now be redirected to the /oauth/authorize Passport route on our Tweeter app. At this point they’ll see a confirmation page; you can use the default Passport confirmation page by running this command:

php artisan vendor:publish --tag=passport-views

This will publish the view to resources/views/vendor/passport/authorize.blade.php, and your users will see the page shown in Figure 13-1.

Figure 13-1. OAuth authorization code approval page

Once a user chooses to accept or reject the authorization, Passport will redirect that user back to the provided redirect_uri. In Example 13-30 we set a redirect_uri of url('tweeter/callback'), so the user will be redirected back to http://spacebook.test/tweeter/callback.

An approval request will contain a code that our consumer app’s callback route can now use to get a token back from our Passport-enabled app, Tweeter. A rejection request will contain an error. SpaceBook’s callback route might look something like Example 13-31.

Example 13-31. The authorization callback route in the sample consuming app

// In SpaceBook's routes/web.php:
Route::get('tweeter/callback', function (Request $request) {
    if ($request->has('error')) {
        // handle error condition
    }

    $http = new GuzzleHttp\Client;

    $response = $http->post('http://tweeter.test/oauth/token', [
        'form_params' => [
            'grant_type' => 'authorization_code',
            'client_id' => config('tweeter.id'),
            'client_secret' => config('tweeter.secret'),
            'redirect_uri' => url('tweeter/callback'),
            'code' => $request->code,
        ],
    ]);

    $thisUsersTokens = json_decode((string) $response->getBody(), true);
    // do stuff with the tokens
});

What the Spacebook developer doing here is building a Guzzle HTTP request to the /oauth/token Passport route on Tweeter. They then send a POST request containing the authorization code they received when the user approved access, and Tweeter will return a JSON response containing a few keys:

• access_token is the token SpaceBook will want to save for this user. This token is what the user will use to authenticate in future requests to Tweeter (using the Authorization header).

• refresh_token is a token SpaceBook will need if you decide to set your tokens to expire. By default, Passport’s access tokens last for one year.

• expires_in is the number of seconds until an access_token expires (needs to be refreshed).

• token_type is the type of token you’re getting back, which will be “Bearer”; this means you pass a header with all future requests with the name of “Authorization” and the value of “Bearer YOURTOKENHERE”.

You now have all the tools you need to perform basic authorization code flows. We’ll cover how to build an admin panel for your clients and tokens later, but first, let’s take a quick look at the other grant types.

php artisan passport:client --personal

 What should we name the personal access client?
   [My Application Personal Access Client]:
 > My Application Personal Access Client

Personal access client created successfully.

// Creating a token without scopes
$token = $user->createToken('Token Name')->accessToken;

// Creating a token with scopes...
$token = $user->createToken('My Token', ['place-orders'])->accessToken;

$.ajaxSetup({
    headers: {
        'X-CSRF-TOKEN': "{{ csrf_token() }}",
        'X-Requested-With': 'XMLHttpRequest'
    }
});

Managing Clients and Tokens with the Passport API and the Vue Components

Now that we’ve covered how to manually create clients and tokens and how to authorize as a consumer, let’s take a look at the aspects of the Passport API that make it possible to build user interface elements allowing your users to manage their clients and tokens.

/oauth/clients (GET, POST)
/oauth/clients/{id} (DELETE, PUT)
/oauth/personal-access-tokens (GET, POST)
/oauth/personal-access-tokens/{id} (DELETE)
/oauth/scopes (GET)
/oauth/tokens (GET)
/oauth/tokens/{id} (DELETE)

php artisan vendor:publish --tag=passport-components

require('./bootstrap');

Vue.component(
    'passport-clients',
    require('./components/passport/Clients.vue')
);

Vue.component(
    'passport-authorized-clients',
    require('./components/passport/AuthorizedClients.vue')
);

Vue.component(
    'passport-personal-access-tokens',
    require('./components/passport/PersonalAccessTokens.vue')
);

const app = new Vue({
    el: '#app'
});

<passport-clients></passport-clients>
<passport-authorized-clients></passport-authorized-clients>
<passport-personal-access-tokens></passport-personal-access-tokens>

Passport Scopes

If you’re familiar with OAuth, you probably noticed we haven’t talked about scopes. Everything we’ve covered so far can be customized by scope, but first let’s quickly cover what scopes are.

In OAuth, scopes are defined sets of privileges that are something other than “can do everything.” If you’ve ever gotten a GitHub API token before, for example, you might’ve noticed that some apps want access just to your name and email address, some want access to all of your repos, and some want access to your gists. Each of these is a “scope,” which allows both the user and the consumer app to define what access the consumer app needs to perform its job.

As shown in Example 13-34, you can define the scopes for your application in the boot() method of your AuthServiceProvider.

// AuthServiceProvider
use Laravel\Passport\Passport;
...
    public function boot()
    {
        ...

        Passport::tokensCan([
            'list-clips' => 'List sound clips',
            'add-delete-clips' => 'Add new and delete old sound clips',
            'admin-account' => 'Administer account details',
        ]);
    }

Once you have your scopes defined, the consumer app can define which scopes it’s asking for access to. Just add a space-separated list of tokens in the “token” field to the initial redirect, in the scope field, as shown in Example 13-35.

// In SpaceBook's routes/web.php:
Route::get('tweeter/redirect', function () {
    $query = http_build_query([
        'client_id' => config('tweeter.id'),
        'redirect_uri' => url('tweeter/callback'),
        'response_type' => 'code',
        'scope' => 'list-clips add-delete-clips'
    ]);

    return redirect('http://tweeter.test/oauth/authorize?' . $query);
});

When the user tries to authorize with this app, it’ll present the list of requested scopes. This way, the user will see the difference between “SpaceBook is requesting to see your email address” and “SpaceBook is requesting access to post as you and delete your posts and message your friends.”

You can check for scope using middleware or on the User instance.

Example 13-36 shows how to check on the User.

Route::get('/events', function () {
    if (auth()->user()->tokenCan('add-delete-clips')) {
        //
    }
});

There are two middleware you can use for this too, scope and scopes. To use these in your app, add them to $routeMiddleware in your app/Http/Kernel.php file:

'scopes' => \Laravel\Passport\Http\Middleware\CheckScopes::class,
'scope' => \Laravel\Passport\Http\Middleware\CheckForAnyScope::class,

You can now use the middleware as illustrated in Example 13-37. scopes requires all of the defined scopes to be on the user’s token in order for the user to access the route, while scope requires at least one of the defined scopes to be on the user’s token.

// routes/api.php
Route::get('clips', function () {
    // Access token has both the "list-clips" and "add-delete-clips" scopes
})->middleware('scopes:list-clips,add-delete-clips');

// or

Route::get('clips', function () {
    // Access token has at least one of the listed scopes
})->middleware('scope:list-clips,add-delete-clips')

If you haven’t defined any scopes, the app will just work as if they don’t exist. The moment you use scopes, however, your consumer apps will have to explicitly define which scopes they’re requesting access with. The one exception to this rule is that if you’re using the password grant type your consumer app can request the * scope, which gives the token access to everything.

Deploying Passport

The first time you deploy your Passport-powered app, the Passport API won’t function until you generate keys for the app. This can be accomplished by running php artisan passport:keys on your production server, which will generate the encryption keys Passport uses to generate tokens.

Triggering the Fallback Route

If you want to customize which route is returned when Laravel catches “not found” exceptions, you can update the exception handler using the respondWithRoute method.

// App\Exceptions\Handler.php
public function render($request, Exception $exception)
{
    if ($exception instanceof ModelNotFoundException && $request->isJson()) {
        return Route::respondWithRoute('api.fallback.404');
    }

    return parent::render($request, $exception);
}

Testing Passport

You can also use the actingAs method on the Passport Facade to test your scopes. Take a look at Example 13-40 to see a common pattern for testing scopes in Passport.

public function test_it_lists_all_clips_for_those_with_list_clips_scope()
{
    Passport::actingAs(
        factory(User::class)->create(),
        ['list-clips']
    );

    $response = $this->getJson('api/clips');
    $response->assertStatus(200);
}