Lumen - ReactJS

Foundation for API-Centric Architecture with Lumen and ReactJS.

Try out the demo https://lumen-react.mosufy.com.

Kick-start your development for an api-centric web application with this repository! Built with OAuth2 for authorization and authentication.

Key Features

Lumen for RESTful API
OAuth2 for API authorization
ReactJS for web front-end

Other Features

[x] MVC with Repository Pattern
[x] Event-driven design
[x] Requests and Responses based on JSON API Specification
[ ] PHPDocumentor
[x] Codeception Code Coverage and API Tester
[x] Build status and Code Coverage Report with Travis CI and Codecov
[x] Mailgun transactional email integration with queues
[x] In-memory cache with memcached
[x] Message queue service with Redis
[x] Elasticsearch for fast and real-time search
[ ] Elasticsearch distributed index with replication for fail-overs (sharding with replication)
[x] Example TODO API resource endpoints
[x] Facade-free implementation
[ ] Eloquent-free implementation
[x] Jenkins-ready deployment
[x] Local setup using Vagrant and VirtualBox
[x] API access logs for possible rate limiting
[x] App logs saved to daily log file & database
[x] Multi-tenant environment
[ ] PHP-7 Support

Installation Instructions

Download and install VirtualBox and Vagrant

Vagrant - Contains VM installation instructions to closely mimic the production box
VirtualBox - Allows us to run a VM on our local machine

This version of VirtualBox and Vagrant works well on Mac OS X El Capitan Version 10.11.6. Newer versions might work too as long as both VirtualBox and Vagrant are compatible to each other.
- VirtualBox: Version 5.0.18 http://download.virtualbox.org/virtualbox/5.0.18/VirtualBox-5.0.18-106667-OSX.dmg
- Vagrant: Version 1.8.1 https://releases.hashicorp.com/vagrant/1.8.1/vagrant_1.8.1.dmg

Go to project root and type vagrant up

$ cd Documents/webapps/lumen-api
$ vagrant up

Vagrant will now begin setting up on your machine based on instructions on the Vagrantfile
- Setting up headless VM on VirtualBox
- Install required software on the VM based on deploy/vagrant/build.sh
- Creates database, run migration and seeder, etc. as per build.sh above

Setup should now be completed with this message

Done, rebooting
System reboot successful.
SSH to vagrant and run 'sudo /etc/init.d/vboxadd setup'. Then, 'vagrant reload' on Terminal.

Type vagrant ssh to SSH into the VM
```
$ vagrant ssh
```
Type sudo /etc/init.d/vboxadd setup to update the Guest Additions. This is required to allow VirtualBox access to the local project root folder
```
$ sudo /etc/init.d/vboxadd setup
```
Exit the VM and type vagrant reload to reload the VM with the newly installed Guest Additions
```
$ vagrant reload
```
SSH into vagrant to confirm that you are now able to access the local folder from VM
```
$ vagrant ssh
...
$ cd /var/www/lumenapi
$ ls -l
```
Above should list all the files as per your local project root folder
Create .env from existing .env.exmple
```
$ cp .env.example .env
```

Enjoy!

Accessing the API

It is recommended to download and use Postman to access all of the API endpoints.

To access the web app, enter the VM ip address in your hosts file. This ip address can be found in the Vagrantfile

$ vim /etc/hosts
...
10.1.2.100       api.lumenapi.local
...

You should now be able to access the local web app by typing http://api.lumenapi.local

Ping test endpoint: http://api.lumenapi.local/v1/services/ping

{"data":[{"type":"timestamp","id":null,"attributes":{"timestamp":{"date":"2016-08-29 17:38:37.000000","timezone_type":3,"timezone":"UTC"}}}]}

Accessing the Website (Front-End)

You should now be able to access the local website by typing http://lumenapi.local.

You may also register for a new account.

The front-end is powered by ReactJS. Learn ReactJS from the official documentation here.

Accessing the Database

It is recommended to download and use SequelPro to access the database.

Refer to the .env for the DB ip address. In any case, below is the DB credentials:

MySQL Host: 127.0.0.1
Username: lumenapi
Password: password
Database: lumenapi
Port: 3306
SSH Host: 10.1.2.100
SSH User: vagrant
SSH Key: `<project_root>/.vagrant/machines/default/virtualbox/private_key`

Elasticsearch

Elasticsearch is a distributed, open source search and analytics engine.

Importing indexes

Before we can begin to query, the index is required to be imported first.

$ php artisan elasticsearch:importIndex {--index=} {--type=}

Accessing the GUI

This build of vagrant comes with Elasticsearch GUI powered by Jettro Coenradie.

To access the GUI, simply access via http://<vm_ip_address>:9200/_plugin/gui/index.html#/dashboard.

Running Queued Jobs

Tasks that require a significant amount of time to process (like sending out an email), should be handled asynchronously. This can be handled by utilising Laravel Queues. To see events and queues in action, create an account by send a POST request to /account (see Postman collection).

Notice that the account has been created but the email is not sent. This is because the job is being sent to the queue. Run the queue listener:

$ php artisan queue:listen --queue=high,default,low

You will start to observe Processed: App\Jobs\SendMailer, indicating that the queued job has now been processed. No email has been sent out as the MAIL_PRETEND in .env is set to true.

The build.sh file for vagrant already comes with Supervisor to manage your queue workers. This will ensure that your queue listener will always be running.

To start/stop Supervisor, simply run these commands.

# Get the current status of Supervisor
$ sudo service supervisord status

# Start/Stop Supervisor
$ sudo service supervisord start|stop

Refer to the Lumen Queues to understand more of how Queue works.

Codeception Testing

Full suite testing the elegant and efficient way.

To run test cases

$ vendor/bin/codecept run

To run test cases with code coverage

Install Xdebug
```
$ sudo yum install php56w-pecl-xdebug
```
Run test with code coverage
```
$ vendor/bin/codecept run --coverage --coverage-xml --coverage-html
```
To view code coverage report, the file is located in tests/_output/coverage/index.html

Don't use Facades

First brought up as a Reddit post, and as agreed by Taylor Otwell himself as a bad practice, Laravel 5.0 and above are now having lesser dependence on facades. Taylor now provides alternatives to Facades in its Documentations. Read the original content and Taylor's response here.

Eloquent-free Implementation

Eloquent and Facades are known to slow down the performance. That is why Lumen is shiped out with Facades and Eloquent disabled. In this feature, we will explore other alternatives like Doctrine2 and others.

Author

For any issues with installation or getting this to work, send an email to: mosufy@gmail.com

Contributing

Fork and merge request!

License

This codebase is open-sourced software licensed under the MIT license

mosufy / lumen-react

readme