https://github.com/elcobvg/lumen-realworld-example-app
Exemplary real world backend API built with Lumen + MongoDB
https://github.com/elcobvg/lumen-realworld-example-app
crud demo-app jwt lumen lumen-framework mongodb realworld rest-api
Last synced: 2 months ago
JSON representation
Exemplary real world backend API built with Lumen + MongoDB
- Host: GitHub
- URL: https://github.com/elcobvg/lumen-realworld-example-app
- Owner: elcobvg
- Created: 2018-01-02T23:06:00.000Z (over 7 years ago)
- Default Branch: master
- Last Pushed: 2019-05-16T10:15:03.000Z (about 6 years ago)
- Last Synced: 2025-03-28T17:11:10.434Z (3 months ago)
- Topics: crud, demo-app, jwt, lumen, lumen-framework, mongodb, realworld, rest-api
- Language: PHP
- Size: 232 KB
- Stars: 50
- Watchers: 3
- Forks: 30
- Open Issues: 0
-
Metadata Files:
- Readme: readme.md
Awesome Lists containing this project
README
# 
> ### Lumen + MongoDB codebase containing real world examples (CRUD, auth, advanced patterns, etc) that adheres to the [RealWorld](https://github.com/gothinkster/realworld) spec and API.
### [Demo](https://lumen-realworld.herokuapp.com/) [RealWorld](https://github.com/gothinkster/realworld)
This codebase was created to demonstrate a fully functional REST API built with **Lumen + MongoDB**, including CRUD operations, authentication, routing, pagination, and more.
It borrows heavily from the [excellent Laravel implementation](https://github.com/gothinkster/laravel-realworld-example-app) by [SandeeshS](https://github.com/SandeeshS).
For more information on how this works with other frontends/backends, head over to the [RealWorld](https://github.com/gothinkster/realworld) repo.
Hope you'll find this example helpful. Pull requests are welcome!
----------
# Getting started
## Installation
Please check the official Lumen installation guide for server requirements before you start. [Official Documentation](https://lumen.laravel.com/docs/5.5/installation)
Clone the repository
git clone [email protected]:elcobvg/lumen-realworld-example-app.git
Switch to the repo folder
cd lumen-realworld-example-app
Install all the dependencies using composer
composer install
Copy the example env file and make the required configuration changes in the .env file
cp .env.example .env
Generate a new application key
Since Lumen doesn't have the `php artisan key:generate` command, there's a custom route `http://localhost:8000/appKey` to help you generate an application key.
Generate a new JWT authentication secret key
php artisan jwt:secret
Run the database migrations (**Set the database connection in .env before migrating**)
php artisan migrate
Start the local development server
php -S localhost:8000 -t public
You can now access the server at http://localhost:8000
**TL;DR command list**
git clone git@elcobvg/lumen-realworld-example-app.git
cd lumen-realworld-example-app
composer install
cp .env.example .env
php artisan key:generate
php artisan jwt:secret
**Make sure you set the correct database connection information before running the migrations** [Environment variables](#environment-variables)
php artisan migrate
php -S localhost:8000 -t public
## Database seeding
**Populate the database with seed data with relationships which includes users, articles, comments, tags, favorites and follows. This can help you to quickly start testing the api or couple a frontend and start using it with ready content.**
Run the database seeder and you're done
php artisan db:seed
***Note*** : It's recommended to have a clean database before seeding. You can refresh your migrations at any point to clean the database by running the following command
php artisan migrate:refresh
## API Specification
This application adheres to the api specifications set by the [Thinkster](https://github.com/gothinkster) team. This helps mix and match any backend with any other frontend without conflicts.
> [Full API Spec](https://github.com/gothinkster/realworld/tree/master/api)
More information regarding the project can be found here https://github.com/gothinkster/realworld
----------
# Code overview
## Dependencies
- [laravel-mongodb](https://github.com/jenssegers/laravel-mongodb) - MongoDB based Eloquent model and Query builder
- [jwt-auth](https://github.com/tymondesigns/jwt-auth) - For authentication using JSON Web Tokens
- [laravel-cors](https://github.com/barryvdh/laravel-cors) - For handling Cross-Origin Resource Sharing (CORS)
## Folders
- `app/Models` - Contains all the Eloquent models
- `app/Http/Controllers` - Contains all the api controllers
- `app/Http/Middleware` - Contains the JWT auth middleware
- `app/Providers` - Contains the JWT auth service provider
- `app/RealWorld/Favorite` - Contains the files implementing the favorite feature
- `app/RealWorld/Filters` - Contains the query filters used for filtering api requests
- `app/RealWorld/Follow` - Contains the files implementing the follow feature
- `app/RealWorld/Paginator` - Contains the pagination class used to paginate the result
- `app/RealWorld/Slug` - Contains the files implementing slugs to articles
- `config` - Contains all the application configuration files
- `database/factories` - Contains the model factory for all the models
- `database/migrations` - Contains all the database migrations
- `database/seeds` - Contains the database seeder
- `routes` - Contains all the api routes defined in web.php file
- `tests` - Contains all the application tests
- `tests/Feature/Api` - Contains all the api tests
## Environment variables
- `.env` - Environment variables can be set in this file
***Note*** : You can quickly set the database information and other variables in this file and have the application fully working.
----------
# Testing API
Run the Lumen development server
php -S localhost:8000 -t public
The api can now be accessed at
http://localhost:8000/api
Request headers
| **Required** | **Key** | **Value** |
|---------- |------------------ |------------------ |
| Yes | Content-Type | application/json |
| Yes | X-Requested-With | XMLHttpRequest |
| Optional | Authorization | Token {JWT} |
Refer the [api specification](#api-specification) for more info.
----------
# Authentication
This applications uses JSON Web Token (JWT) to handle authentication. The token is passed with each request using the `Authorization` header with `Token` scheme. The JWT authentication middleware handles the validation and authentication of the token. Please check the following sources to learn more about JWT.
- https://jwt.io/introduction/
- https://self-issued.info/docs/draft-ietf-oauth-json-web-token.html
----------
# Cross-Origin Resource Sharing (CORS)
This applications has CORS enabled by default on all API endpoints. The CORS allowed origins can be changed by setting them in the config file. Please check the following sources to learn more about CORS.
- https://developer.mozilla.org/en-US/docs/Web/HTTP/Access_control_CORS
- https://en.wikipedia.org/wiki/Cross-origin_resource_sharing
- https://www.w3.org/TR/cors