Overview

Laravel HMVC RESTfull API boilerplate project

The project is based on the Laravel framework and it's main purpose is for creating large, modular and complex RESTfull API more easily.

Laravel version - 6.x

• Structure overview
• Doctrine
• Model
• Available endpoints

Installation

It is not included composer installation and configuration of web server and database.

Create the environment configurations

$ cp .env.example .env

Install dependencies

$ composer install

Generate application key

$ php artisan key:generate && php artisan config:clear

Run migrations, basically it is only for the oauth tables.

Laravel migrations are replaced with Doctrine2 schema sync.

$ php artisan migrate

Create need it tables by synchronizing Doctrine2 schemas.

For managing database tables must be used Doctrine2 instead default Laravel migrations which are hard to maintain when the project gets bigger.

$ php artisan doctrine:schema:update

Install passport.

Reference to Passport documentation

$ php artisan passport:install

Clear application cache

$ php artisan cache:clear && php artisan config:clear && php artisan config:cache

Set appropriate permissions on storage and bootstrap/cache like said in official documentation.

Start the server and API will be working on localhost.

Structure overview

HMVC stands for Hierarchical model–view–controller. The advantage of using HMVC is code Modularization, Organization and Reusability

In the app/Modules directory are located all modules. Each module has it's own MVC structure and it's dynamically loaded.

Every module must come with it's own configurations. Defining ServiceProviders, Routes, Configs, Commands etc are now done inside every module and each of them must be placed in the appropriate folder in order to be auto loaded, their is no need to be manually registered anymore in the application with an exception for the middleware which must be manually registered by some ServiceProvider from the specific module or in worst case scenario in Http/Kernel.php (I've had some issues with defining dynamically a middleware in routeMiddleware)

Doctrine

Doctrine is used ONLY for database migrations instead the default Laravel migrations. For working with the database like select, insert, update etc it's used Eloquent ORM which is the default for Laravel.

The reason why is choosed doctrine it's because that only a database table representation schema must be defined and doctrine will do the rest of the work like keeping track of changes and do auto migrations.

This is a basic example of an entity (schema)

<?php

namespace App\Modules\User\Entities;

use Doctrine\ORM\Mapping AS ORM;
use App\Model\Entity;

/**
 * @ORM\Entity
 * @ORM\Table(name="codew_user")
 */
class UserEntity extends Entity
{
    /**
     * @ORM\Column(name="username", type="string", length=250, nullable=false, unique=true)
     */
    protected $username;

    /**
     * @ORM\Column(name="password", type="string", length=250, nullable=false)
     */
    protected $password;
}

The entities are placed in Entities folder of each module.

After an entity is created the database must be synced. This is done by running this command:

$ php artisan doctrine:schema:update

And that's all. The table is created with all fields.

If we need to add/remove/edit a field, it must be done inside the entity and the update command must run again.

For Doctrine integration in Laravel is used this package

Model

Every tables in database could have a corresponding

• model
• repository Uses the repository pattern, it's an layer between application logic and database. This it the place where database queries must be.
• resource

Usage example

class Users extends Controller
{
    protected $userRepository;

    public function __construct(UserRepository $userRepository)
    {
        $this->userRepository = $userRepository;
    }

    /**
     * @param Request $request
     * @return JsonResponse
     */
    public function fetch(Request $request)
    {
        $users = $this->userRepository->fetchUsers();
        return response()->json(['user' => UserResource::collection($users)], 200);
    }
}

Available endpoints

Project comes with some available endpoints which can be used.

Method	URI	Action	Middleware
POST	api/oauth/token	Laravel\Passport\Http\Controllers\AccessTokenController@issueToken	throttle
POST	api/product	App\Modules\Shop\Controllers\Product@create	api,auth:api,role:ROLE_ADMIN
GET	api/product	App\Modules\Shop\Controllers\Product@fetchSingle	api
PUT	api/product/{id}	App\Modules\Shop\Controllers\Product@edit	api,auth:api,role:ROLE_ADMIN
DELETE	api/product/{id}	App\Modules\Shop\Controllers\Product@delete	api,auth:api,role:ROLE_ADMIN
GET	api/products	App\Modules\Shop\Controllers\Product@fetch	api
POST	api/user/signup	App\Modules\User\Controllers\Signup@createAccount	api
GET	api/users	App\Modules\User\Controllers\Users@fetch	api,auth:api,role:ROLE_ADMIN

License

MIT License

@Codenetz

Hristo Boyarov