apt get life

Life around technology

You are here: Home / Archives for Laravel

Getting started with Laravel 5 & Dingo API: 1. Setting up the environment

by

In this series, I’m going to be writing about the creation of an API with Laravel 5.2 and Dingo API. The tutorial will focus around a fictional company that receives orders for garments from a number of 3rd party suppliers. 3rd parties place orders for items via the API, which then get dispatched to a recipient.

Setting Up a New Environment

So, the first thing to do is create a new environment for development. I’ll be using a Linux operating system to do development without using Laravel’s Homestead. You can of course use Homestead if that’s your preferred development method, but I can’t stand virtual machines eating system resources.

Installing pre-requisites

First off, you need to get the latest viable version of PHP and git for your OS. I’m using a Linux Mint 17.2, so I’ll be using apt-get.

sudo apt-get install php5-cli git mysql-server mysql-client

MySQL

MySQL will need to be configured. Set a memorable but secure root password. You can optionally create a limited user account (highly recommended), but since this is a local development environment I’ll just be using root credentials to allow it access to the database.

Create a database for the project. I’m calling mine “api” in order to remain as simple as possible.

Install Composer

I don’t intend to cover the installation of composer here, but you can find out up to date information from their website getcomposer.org. This is required to complete the rest of the guide.

Install Laravel

You should be able to install Laravel globally using composer:

composer global require "laravel/installer"

If you have any problems I’d suggest going to the Laravel website and checking for up to date installation instructions.

Recommended Tools

Just quickly, I use either Sublime text (paid for) or Atom (free and open source) for development. I’ll be focusing on Atom as it’s more accessible due to it’s open source development. Atom is great out of the box, but take a look at plugins to make it far more powerful as a development tool.

It’s also worth downloading Postman from the Chrome app store, unless you’re a curl lover it just makes things easier later.

Setting up the Project

Open up a new terminal and create a new Laravel application called api:

laravel new api

You’ll get some output about crafting a new application, just let it do it’s thing. Once finished and dropped back to the command prompt, go into the new directory and launch Atom in the current directory.

cd api
atom .

Now, probably the first thing we want to do is get some version control going on in case we screw up. Let’s create a new git repository here, and commit the current files.

git init
git add -A
git commit -m "initial laravel setup"

Next, lets grab Dingo API, which we’ll be using in the project to perform our REST requests.

composer require dingo/api:1.0.x@dev

Composer will go and do the heavy lifting, grabbing dependencies and setting up dingo for us.

We now want to make some changes to the config in Laravel, so using Atom open “config/app.php” and add a line to the bottom of the service providers array.

'providers' => [
    // ... leave other lines intact, just add the below...
    // Add a provider for Dingo API
    Dingo\Api\Provider\LaravelServiceProvider::class
],

Now lets run vendor publish to get the api config file setup.

php artisan vendor:publish --provider="Dingo\Api\Provider\LaravelServiceProvider"

Great, so we have laravel and dingo installed. Lets just run through some configuration settings for dingo. Open up “config/api.php”. Hopefully this file has enough comments in it that you’ll understand what you need to change for your implementation. For this guide I’m simply going to edit a few variables to have an API prefix and enable debugging:

'prefix' => env('API_PREFIX', 'api'),

'debug' => env('API_DEBUG', true),

One more thing we need to do. Earlier you created a database called “api” and hopefully a user with a password who has permissions over that database. If not do that now. Then, open up the .env file in the Laravel installation and enter the details in the under the DB_ section:

DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=api
DB_USERNAME=user
DB_PASSWORD=secret

This will be used for MySQL connections later.

Okay, we’ve reached a good point to commit our changes to git

git add -A
git commit -m "setup dingo API"

That’s basically it for setup, lets start crafting an API!

The Beginnings: First API Hook

Lets jump straight into Atom and load the “routes.php” file. At the very bottom of the file, lets add in a call to the Dingo API Router.

$api = app('Dingo\Api\Routing\Router');

$api->version('v1', function ($api) {
    $api->get('/', function() {
        return ['test' => true];
    });
});

Now if you save the file and run the application – I’ll use PHP to serve it locally – you’ll be able to visit the page to get the response.

php artisan serve
#Laravel development server started on http://localhost:8000/

now go to http://localhost:8000/api/ in your web browser, or better yet using postman and you should see the response:

{"test":true}

Great, so what have we done here? Well first, we’ve created a new route for the v1 API. At the moment it’s just using the base URL “/api/” but we will change that later. We’ve specified that we will respond to a get request for a “v1” API request and return an array, which Dingo was nice enough to turn into JSON. This isn’t very useful yet, so next time we will start looking at how to do more interesting things.