I am happy to announce that we have now added Lumen to Stormpath’s PHP integrations. This integration requires minimal setup and about five minutes to get a PHP backend up and running for your mobile applications – exciting! With our Lumen integration, you can quickly set up user registration and user authentication using OAuth tokens.

This tutorial will teach you how to set up a new Lumen project and configure it for use in your mobile application. I will teach you how to install Lumen in a couple of different ways and guide you through the configuration and setup of your Lumen project.

For this tutorial, I am going to teach you how to create a new lumen project all the way to your first call with one of our mobile SDKs. I will take you through your first call to authenticate a user using the /oauth/token endpoint to return OAuth tokens for all future requests against your application. We have also provided middleware for you to use to check for authenticated users on a route.

Let’s get started! You can sign up for a free Stormpath account here.

Lumen Tutorial Overview

This tutorial assumes a few items:

  • A basic understanding of what Lumen is. We’ll learn together how it works.
  • Development environment with PHP 5.6 or greater
  • OpenSSL PHP Extension installed
  • PDO PHP Extension installed
  • Mbstring PHP Extension installed
  • Basic Command Line Knowledge
  • Composer installed
  • Git installed and configured

Install Lumen

Lumen is built with the same principle as Laravel, to make things easy for developers. The installation of Lumen, and Laravel, is one of the easiest things I have ever come across for frameworks. There are a 2 main ways to install Lumen for your project and I will cover both of them here

Install Lumen with Composer

Composer is a great tool and the tool of choice here at Stormpath for all of our PHP integrations. The process with composer can be done with a single line of code run from your terminal;

Understanding what the snippet of code does for you is important. The first part, composer create-project tells composer that you are going to be creating a new project with the following parameters. -prefer-dist forces installation from package dist. Doing it this way can speed up the process and also prevent errors if you have not set up git correctly. The next part tells composer what package you want to use, in our case, laravel/lumen. Finally lumen-stormpath-mobile-backend is the location you want composer to install the project in. This can be anything you want it to be, but for this tutorial, we will use this location for all examples.

Install Lumen with Lumen Installer

My personal preference when installing Lumen or Laravel is to use the dedicated installers. These installers make it much simpler to quickly start a new project. Installing the installers can be done from composer. To make them available from anywhere on the system, we need to install them as a global dependency. Doing so requires one extra command from the typical composer require.

This will run composer and require the laravel/lumen-installer which can be found on github and require it globally. Once composer is done installing the lumen-installer package, you will then be able to run the following from anywhere on your system to create a new lumen project. Once you do this once, you will never have to do it again for any future Lumen projects.

The one thing to keep in mind when doing the preceding command is you need to be in the parent folder of where you want the project to be installed. A folder will be created with the name you give it in the folder you are in when running this command.

During the installation, the lumen command will issue a few different commands for you. This will download the newest stable version of Lumen and run a composer install command, prepping Lumen for you on your system. Once this is done, you now have Lumen installed.

Test Lumen Installation

The final step of creating your Lumen project is to test it to make sure it is working. If you are familiar with Laravel, you know of php artisan. One of the nice tools from the Laravel environment is the php artisan serve command which spins up a server for you. Sadly, this was not carried over into the Lumen framework, but that is ok because PHP has a built in server from their command line tool. Change your directory in terminal to the /public folder of the project then run

Running this command will tell PHP to start its internal server using the hostname localhost on port 8000. You can pick any hostname/ip and port combination you would like. For this tutorial, we will assume localhost:8000 as our point of entry for the mobile backend.

The artisan command is a command line tool that has a lot of helper command line tools that are built into Lumen and Laravel.

Install Stormpath Lumen Package

The goal at Stormpath is to create useful tools that are easy to use and understand. The Stormpath Lumen package is no exception. With very few lines of code changes, only 1 line if you don’t count the composer edits, you can install the stormpath-lumen package and get it running to accept requests.

Set Up Composer To Install Stormpath Lumen

The first step in this process is to edit the composer.json file from your project. Open the file and find the require section. This section sets the packages that are required for your project to run. Once you find the section, add the following;

Stormpath follows SemVer for releases. At the time of writing this article, the stormpath/lumen package was at release 0.1.1. The require statement will install anything that is in the 0.x series. Once stormpath/lumen has a 1.x release, you will have to update your require statement to reflect that change. Because of the SemVer versioning, when 1.0.0 is released, it may introduce breaking backwards compatibility changes. Because of this, and as a general practice, you should never blindly update your composer dependencies without testing them first.

This will tell composer to go out and find the package with the name stormpath/lumen at a version (release) that is in the 0.x series, but above or equal to version 0.1.0. Once you have this added to your composer.json file you can run composer update from the command line to bring in the dependency into your project. This will go out and download our files into you vendor folder and add it to the autoload magic of composer.

At this point, you may be asking, why not just run composer require stormpath/lumen. That is a great question and the answer comes down to some dependency conflicts and the way composer handles installing packages this way. You can find out all the details from a ticket we raised with Composer when we ran into this situation on their Github issues

Install the Package

As I stated before, this part requires only a single line of code to be added. We nee to tell Lumen to use the Stormpath Lumen service provider. This is done in a little bit of a different way than in Laravel. Open the file found at bootstrap/app.php and scroll down a little bit until you find the section of service providers. After all other services providers are defined (they will be commented out and that is fine), add the Stormpath Lumen service provider.

This will tell Lumen to load our service provider and initialize the Stormpath Lumen application.

Configure Application For Mobile API

Out of the box, the Stormpath Lumen package is already set up for an API, mobile or not. You will have to provide an API key to the service provider along with the application href from Stormpath. To do this, you first need to sign up with Stormpath. Once you do this, a confirmation email will be sent and then you can log into the Stormpath dashboard

Generate And Install API Keys

Once you are in the Dashboard for Stormpath, if it is a new account, you will need to click on Generate Api Keys on the right side of the screen. Once you do, you will be prompted to download a file which contains your keys. If it is an existing account, you can either use current API keys or click on Manage Api Keys on the right of the screen to generate new keys. Once you have your API keys, you need to install the API keys. To do so, open your .env file from the root of the Lumen project and add the following lines

Add Application Configuration

The next step is to add your application href to the Lumen project. You can find your application href from the Stormpath dashboard applications. Find the application you want to use for your Stormpath Lumen project, or create a new one. Once you find it or create one, click on the application name and copy the href on the screen. It should look something like https://api.stormpath.com/v1/applications/6t13J2kFopAcer3RoCrSeW. Open your .env file again and add the following

Once you have done both of the preceding steps, you need to restart your PHP server. Do this by pressing ctrl+c in the terminal to stop the current server, then run the command php -S localhost:8000 to start the server again. This will load in your new environment variables and you are ready to begin making calls to your application.

If you need to change any of the default functionality of the package, you can publish the default yaml configuration file that our package is using. from the command line and the root of your project, run php artisan stormpath:publish and this will generate a new file in the root of your project called stormpath.yaml. This file allows you to enable or disable features of the integration to fit your needs.

Authenticate Mobile Accounts

We are not ready to start making calls to the Stormpath Lumen backend. The Stormpath Lumen is an API only integration, meaning that it will only respond to you in JSON. All of the typical login and registration endpoints are set up and ready to accept requests.

The one route that would be a little different for mobile is the way authentication works. At first you may think to just send a post request to /login however this is not the recommend way of doing things. We suggest and allow a post request to be made to an /oauth/token route which will return to you an access_token and a refresh_token for you to use on all further requests. The request to this endpoint would look like the following

This will return a result that looks like the following

A refresh token will only be available if it is enabled on the stormpath application. This can be configured by visiting the application token policy. By default, refresh tokens are enabled, but we give you the option to disable them.

Protect Your Routes

Once you begin building out your mobile backend, we have provided a few middleware filters you can use on your routes. This middleware can be added to your route in the typical Lumen way and have already been initialized and available to you. For routes you want only authorized users to see, add the middleware stormpath.auth to the route. With this, passing in the access_token bearer token as an Authorization header, our integration will take over and make sure the user is authorized to view the route based on the token. For routes that you want only guests to see or access, you can use the stormpath.guest middleware. This will check to make sure the user has not passed in an access_token in the header.

Integrate With Stormpath Mobile SDKs

Our mobile SDK team has been hard at work to make sure their SDK’s work with all of our integrations. They have created some great SDK for iOS and Android which are now available for you to use. Our goal on the integrations we create is to make it possible for you to use and swap in any integration you want to use without much configuration change for your mobile application. We all use the same endpoints and naming conventions. This is to make it easy for you to get up and running with any integration we make. Find out more information on how to use these great SDK’s from the Android documentation or the iOS documentation.

Further Reading

Want to learn more about adding user authentication to PHP applications? Check out these posts:

I hope you enjoyed this tutorial and would love to hear your thoughts. Leave your comments below or you can contact us at support@stormpath.com. Keep up to date with what we are doing on Twitter @goStormpath.

-Brian