/lumen-6-api-base

Lumen 6 LTS Starter Project for fast REST API creation using JWT Authentication.

Primary LanguagePHP

Lumen 6 (8.x is latest, but this is the LTS version) API Project Starter Setup

This is a boilerplate/start Lumen project setup using the Long Term Support version of Laravel's Lumen micro-framework laravel/lumen^6.3.4. This setup is optimized for quickly and easily getting a new REST API started with only minimal configuration required. This is an amalgamation of personal experience and insight from other developers through blog articles, documentation, tutorials, laracasts, and OSI projects. Suggestions and pull requests are totally encouraged!

Thanks for checking it out! Need-4-Steve

Base Features

Useful Plugins

if you'r using composer v1.x check this project

composer global require hirak/prestissimo

TODO

  • Still need to add some unit testing
  • Add a Vue.js Frontend Generator Option

To use the documentation generator for your API

apidoc -i App/Http/Controller/Api/v1 -o public/apidoc

To List All of the API Routes

php artisan api:route

Use Artisan Generators

By default lumen doesn't support the useful laravel/artisan generators, but with this extension, we can use the following commands to create whatever you need:

key:generate         Set the application key

make:cast            Create a new custom Eloquent cast class
make:channel         Create a new channel class
make:command         Create a new Artisan command
make:controller      Create a new controller class
make:event           Create a new event class
make:exception       Create a new custom exception class
make:factory         Create a new model factory
make:job             Create a new job class
make:listener        Create a new event listener class
make:mail            Create a new email class
make:middleware      Create a new middleware class
make:migration       Create a new migration file
make:model           Create a new Eloquent model class
make:notification    Create a new notification class
make:pipe            Create a new pipe class
make:policy          Create a new policy class
make:provider        Create a new service provider class
make:request         Create a new form request class
make:resource        Create a new resource
make:seeder          Create a new seeder class
make:test            Create a new test class

notifications:table  Create a migration for the notifications table

schema:dump          Dump the given database schema

Additional Useful Commands

clear-compiled    Remove the compiled class file
serve             Serve the application on the PHP development server
tinker            Interact with your application
optimize          Optimize the framework for better performance
route:list        Display all registered routes.

Test:

php artisan make:model MyModel

LINKS

Installation

1. Install the starter repo

Using GIT

git clone https://github.com/need-4-steve/lumen-6-api-base.git api
cd api
composer install
cp .env.example .env
php artisan jwt:secret

Using HTTPS

gh repo clone GeekyAnts/laravel-lumen-jwt-boilerplate api
cd api
composer install
cp .env.example .env
php artisan jwt:secret

Alternatively:

  1. Using your browser of choice, go to https://github.com/need-4-steve/lumen-6-api-base/
  2. Click the green "Code" button
  3. Download ZIP or Open with GitHub Desktop
  4. Extract *.zip file to preferred installation directory, if downloaded as ZIP
  5. Open command line to installation directory
  6. bash composer install
  7. Copy the file .env.example and paste in the same directory, then rename to .env
  8. bash php artisan jwt:secret
  9. PROFIT!

2. Configuration

Edit the .env file and configure to match your dev environment.

nano .env
# edit all DB_* fields
# configure values to match the appropriate values for database access
  
# edit APP_KEY field
# key:generate is abandoned in lumen, but you can generate a key yourself
# using any of the following commands:
php -r "echo md5(uniqid());"
php -r "echo str_random(32);" 
# or whatever you want to generate a 32 character (128-bit) string，
# you could also jsut use jwt:secret, and cut and paste it into the APP_KEY field,
# then jwt:secret again to generate a new JWT secret
php artisan migrate --seed

3. Up and Running

PHP's built-in server

php -S localhost:8000 -t public
# or
php artisan serve

Docker Container

The easiest way to use docker for this lumen version is to install laravel/sail.

composer require laravel/sail --dev
# the command below will publish the docker-compose.yml file in your project root
php artisan sail:install
# make any changes you want to make, then fire it up!
./vendor/bin/sail up

Refer to the Laravel Sail documentation for more information.

Deploy to Production Environment

In a production environment, omit the composer dev packages:

composer install --no-dev

Routes

There is jsut 1 built-in route to this starter framework.

Authorization Endpoint

The login route returns an access token to make any other request.

route uri : http://{base_uri}/api/v1/auth http verb : post params : { email: "youremail@domain.com", password: "userpassword" }

FAQs

About JWT
  • There is no session and auth guard in lumen 6, so modify config/auth.php.
  • The User Model class must implement Tymon\JWTAuth\Contracts\JWTSubject
How to use mail
  • composer require illuminate/mail and guzzlehttp/guzzle
  • register email service in bootstrap/app.php or register whatever provider
  • add mail.php & services.php in config
    • HINT: just copy them from laravel
  • add MAIL_DRIVER key with appropriate value in .env file
How to use the transformer classes

Transformers are application layers that help you format your resource responses and their relationships. Basically, they wrap your responses as JSON most of the time but other logic can go there to based on your needs. Check out this blog post for more info!

transformer data serializer

dingo/api uses Fractal for transformer resources. Learn more by checking out Fractals Serializer documentation http://fractal.thephpleague.com/serializers/。

You can set your own serializer like this (NOTE: DataArray is the default assigned type)：

bootstrap/app.php

$app['Dingo\Api\Transformer\Factory']->setAdapter(function ($app) {
  $fractal = new League\Fractal\Manager;
  // $serializer = new League\Fractal\Serializer\JsonApiSerializer();
  $serializer = new League\Fractal\Serializer\ArraySerializer();
  // $serializer = new App\Serializers\NoDataArraySerializer();
  $fractal->setSerializer($serializer);,
  return new Dingo\Api\Transformer\Adapter\Fractal($fractal);
});