Gigwerk API

Gigwerk API

The Gigwerk REST API powers all of our client side applications:

• Gigwerk Mobile App
• Cookie Cutter Business App
• Business Dashboard

This application is built using Laravel.

Local Setup

Homestead is the development environment the backend API uses to ensure consistency between environments you must use it in order to contribute to the backend.

Mac Setup:

System Requirements

• Download Homebrew
• Download VirtualBox6.X
• Download Vagrant

Install PHP & Composer

In your terminal run the following commands:

brew install php
brew install composer

Create a Directory & Setup Git Tracking

git init
git remote add origin https://your_username:your_password@github.com/gigwerk-io/api.git
git fetch
git pull origin master

Install Dependencies & Setup Virtual Machine

composer install
php vendor/bin/homestead make
ssh-keygen -t rsa -b 4096 -C "your_email@example.com"

Update Homestead.yml (autogenerated)

Here is my homestead.yml file:

ip: 192.168.10.10
memory: 2048
cpus: 2
provider: virtualbox
ssl: true

authorize: ~/.ssh/id_rsa.pub

keys:
  - ~/.ssh/id_rsa

folders:
  - map: ~/Sites/business-api
    to: /home/vagrant/code

sites:
  - map: api.gigwerk.test
    to: /home/vagrant/code/public
    php: "7.4"
    schedule: true

databases:
  - gigwerk
  - gigwerk_testing

features:
  - mariadb: false
  - ohmyzsh: true
  - webdriver: false
  - minio: true
    buckets:
      -   name: gigwerk-images
          policy: public
      -   name: gigwerk-private
          policy: none
name: gigwerk
hostname: gigwerk

You can copy everything here and place it into your Homestead.yml, though you will want to ensure path names are correct.

Start Virtual Machine

vagrant up
vagrant ssh

Provision Virtual Machine

cd ~/code/
cp .env.example .env
php artisan key:generate
php artisan migrate --seed

Start Supervisor Daemon

Run sudo vim /etc/supervisor/conf.d/homestead.conf then paste this:

[program: homestead]
command=php /home/vagrant/code/artisan queue:work --tries=1
stdout_logfile=/home/vagrant/code/storage/logs/supervisord.log
redirect_stderr=true
autostart=true
autorestart=true

After that run:

sudo supervisorctl
reread
add homestead
start homestead 

If it's saying that it's already started, don't panic.

Configure Redis

We use Redis as our NoSQL Database for key pair values.

Restart redis server and exit your server by running: sudo /etc/init.d/redis-server restart

To ensure you're redis is configured run: redis-cli to see if redis is running.

Setup Minio

Next you have to setup Minio, a local S3 bucket emulator. Use the username: homestead, password: secret and create a bucket called gigwerk.

Configure Hosts File

This should happen automatically, but if it doesn't go to: /etc/hosts and paste this:

192.168.10.10 api.gigwerk.test

Be sure the ip address isn't being used more than once.

SSL Certificate

sudo cp /etc/nginx/ssl/api.gigwerk.test.crt ~/code/certs/

Then in a separate terminal run:

open ~/code/certs/api.gigwerk.test.crt

This will open up keychain where you will then want to click on the api.gigwerk.test certficate and trust it.

Ready To Go

Go to https://api.gigwerk.test

Tools for development

Minio

Minio allows you to mock Amazon S3 locally without actually interacting with S3. Go to here then login.

ACCESS_KEY: homestead
SECRET_KEY: secretkey

Supervisor

Supervisor is a daemon that allows you to run your queues. Visit here to view locally.

Mailhog

Mailhog allows you to view your outgoing mail without actually sending it. Visit here to view locally.

Code Quality

PHPStan

PHPStan focuses on finding errors in your code without actually running it. In order to run it just run ./vendor/bin/phpstan analyse

CS-Fixer

PHP-CS-Fixer is tool that fixes your code to follow standards; whether you want to follow PHP coding standards as defined in the PSR-1, PSR-2, etc. In order to run it just run ./vendor/bin/php-cs-fixer .

Coding Standards

These are the best practices while coding for the FAVR API

Use IoC container

Please use dependency injection and the IOC container when needing to access services. Stay away from Facades as they are anti-pattern. Read more here why not to use Facades.

Bad Practice

<?php
namespace App\Http\Controllers;
use Illuminate\Support\Facades\Auth;
class ExampleController extends Controller
{
    /**
     * Create a new controller instance.
     *
     * @return void
     */
    public function __construct()
    {
        //
    }
    public function foo()
    {
        $user = Auth::user(); // bad practice
        $user->doStuff();
    }
}

Good Practice

<?php
namespace App\Http\Controllers;
use App\Models\User;
use Illuminate\Contracts\Auth\Guard;
use Illuminate\Support\Facades\Auth;
class ExampleController extends Controller
{
    /**
     * @var \Illuminate\Contracts\Auth\Authenticatable|null | User
     */
    private $user;
    /**
     * Create a new controller instance.
     *
     * @return void
     */
    public function __construct(Guard $guard)
    {
        $this->user = $guard->user();
    }
    public function foo()
    {
        $this->user->doStuff();
    }
}

Do not get data from the .env file directly

Pass the data to config files instead and then use the config() helper function to use the data in an application.

Bad Practice:

$apiKey = env('API_KEY');

Good Practice:

// config/api.php
'key' => env('API_KEY');
// Use the data
$apiKey = config('api.key');

Version Control

We use commitizen to ensure we properly describe our commits to prevent generic messages like "Updated the code"

API Documentation

In order to generate your API documentation run php artisan docs:generate then visit here.