Laravel

Lucid

The Lucid Architecture is a software architecture that consolidates code-base maintenance as the application scales, from becoming overwhelming to handle, gets us rid of rotting code that will later become legacy code, and translate the day-to-day language such as Feature and Service into actual, physical code.

Read more about the Lucid Architecture Concept.

If you prefer a video, watch the announcement of The Lucid Architecture at LaraconEU 2016:

The Lucid Architecture for Building Scalable Applications - Laracon EU 2016

Join The Community on Slack

Index

• Installation
• Introduction
  • Components
    • Service
    • Feature
    • Job
  • Data
  • Foundation
• Getting Started
• Microservices

Installation

8.x

To start your project with Lucid right away, run the following command:

composer create-project lucid-arch/laravel my-project

This will give you a Laravel 8 installation with Lucid out-of-the-box. If you wish to download other versions of Laravel you may specify it as well:

7.x

composer create-project lucid-arch/laravel=7.x my-project-7.x

6.x

composer create-project lucid-arch/laravel=6.x my-project-6.x

5.5

composer create-project lucid-arch/laravel=5.5.x my-project-5.5

Introduction

Directory Structure

src
├── Data
├── Domains
    └── * domain name *
            ├── Jobs
├── Foundation
└── Services
    └── * service name *
        ├── Console
        ├── Features
        ├── Http
        ├── Providers
        ├── Tests
        ├── database
        └── resources

Components

| Component | Path | Description | |---------|--------| ----------- | | Service | src/Service/[service] | Place for the Services | | Feature | src/Services/[service]/Features/[feature] | Place for the Features of Services | | Job | src/Domains/[domain]/Jobs/[job] | Place for the Jobs that expose the functionalities of Domains | | Data | src/Data | Place for models, repositories, value objects and anything data-related | | Foundation | src/Foundation | Place for foundational (abstract) elements used across the application |

Service

Each part of an application is a service (i.e. Api, Web, Backend). Typically, each of these will have their way of handling and responding to requests, implementing different features of our application, hence, each of them will have their own routes, controllers, features and operations. A Service will seem like a sub-installation of a Laravel application, though it is just a logical grouping than anything else.

To better understand the concept behind Services, think of the terminology as: "Our application exposes data through an Api service", "You can manipulate and manage the data through the Backend service".

One other perk of using Lucid is that it makes the transition process to a Microservices architecture simpler, when the application requires it. See Microservices.

Service Directory Structure

Imagine we have generated a service called Api, can be done using the lucid cli by running:

You might want to Setup to be able to use the lucid command.

lucid make:service api

We will get the following directory structure:

src
└── Services
    └── Api
        ├── Console
        ├── Features
        ├── Http
        │   ├── Controllers
        │   ├── Middleware
        │   ├── Requests
        │   └── routes.php
        ├── Providers
        │   ├── ApiServiceProvider.php
        │   └── RouteServiceProvider.php
        ├── Tests
        │   └── Features
        ├── database
        │   ├── migrations
        │   └── seeds
        └── resources
            ├── lang
            └── views
                └── welcome.blade.php

Feature

A Feature is exactly what a feature is in our application (think Login feature, Search for hotel feature, etc.) as a class. Features are what the Services' controllers will serve, so our controllers will end up having only one line in our methods, hence, the thinnest controllers ever! Here's an example of generating a feature and serving it through a controller:

You might want to Setup to be able to use the lucid command.

IMPORTANT! You need at least one service to be able to host your features. In this example we are using the Api service generated previously, referred to as api in the commands.

lucid make:feature SearchUsers api

And we will have src/Services/Api/Features/SearchUsersFeature.php and its test src/Services/Api/Tests/Features/SearchUsersFeatureTest.php.

Inside the Feature class, there's a handle method which is the method that will be called when we dispatch that feature, and it supports dependency injection, which is the perfect place to define your dependencies.

Now we need a controller to serve that feature:

lucid make:controller user api

And our UserController is in src/Services/Api/Http/Controllers/UserController.php and to serve that feature, in a controller method we need to call its serve method as such:

namespace App\Services\Api\Http\Controllers;

use App\Services\Api\Features\SearchUsersFeature;

class UserController extends Controller
{
    public function index()
    {
        return $this->serve(SearchUsersFeature::class);
    }
}

Views

To access a service's view file, prepend the file's name with the service name followed by two colons ::

Example extending view file in blade:

@extends('servicename::index')

Usage with jobs is similar:

new RespondWithViewJob('servicename::user.login')

RespondWithJsonJob accepts the following parameters:

RespondWithViewJob($template, $data = [], $status = 200, array $headers = []);

Usage of template with data:

$this->run(new RespondWithViewJob('servicename::user.list', ['users' => $users]));

Or

$this->run(RespondWithViewJob::class, [
    'template' => 'servicename::user.list',
    'data' => [
        'users' => $users
    ],
]);

Job

A Job is responsible for one element of execution in the application, and play the role of a step in the accomplishment of a feature. They are the stewards of reusability in our code.

Jobs live inside Domains, which requires them to be abstract, isolated and independent from any other job be it in the same domain or another - whatever the case, no Job should dispatch another Job.

They can be ran by any Feature from any Service, and it is the only way of communication between services and domains.

Example: Our SearchUsersFeature has to perform the following steps:

• Validate user search query
• Log the query somewhere we can look at later
• If results were found
  • Log the results for later reference (async)
  • Increment the number of searches on the found elements (async)
  • Return results
• If no results were found
  • Log the query in a "high priority" log so that it can be given more attention

Each of these steps will have a job in its name, implementing only that step. They must be generated in their corresponding domains that they implement the functionality of, i.e. our ValidateUserSearchQueryJob has to do with user input, hence it should be in the User domain. While logging has nothing to do with users and might be used in several other places so it gets a domain of its own and we generate the LogSearchResultsJob in that Log domain.

To generate a Job, use the make:job <job> <domain> command:

lucid make:job SearchUsersByName user

Similar to Features, Jobs also implement the handle method that gets its dependencies resolved, but sometimes we might want to pass in input that doesn't necessarily have to do with dependencies, those are the params of the job's constructor, specified here in src/Domains/User/Jobs/SearchUsersByNameJob.php:

namespace App\Domains\User\Jobs;

use Lucid\Foundation\Job;

class SearchUsersByNameJob extends Job
{
    private $query;
    private $limit;

    public function __construct($query, $limit = 25)
    {
        $this->query = $query;
        $this->limit = $limit;
    }

    public function handle(User $user)
    {
        return $user->where('name', $this->query)->take($this->limit)->get();
    }
}

Now we need to run this and the rest of the steps we mentioned in SearchUsersFeature::handle:

public function handle(Request $request)
{
    // validate input - if not valid the validator should
    // throw an exception of InvalidArgumentException
    $this->run(new ValidateUserSearchQueryJob($request->input()));

    $results = $this->run(SearchUsersJob::class, [
        'query' => $request->input('query'),
    ]);

    if (empty($results)) {
        $this->run(LogEmptySearchResultsJob::class, [
            'date' => new DateTime(),
            'query' => $request->query(),
        ]);

        $response = $this->run(new RespondWithJsonErrorJob('No users found'));
    } else {
        // this job is queueable so it will automatically get queued
        // and dispatched later.
        $this->run(LogUserSearchJob::class, [
            'date' => new DateTime(),
            'query' => $request->input(),
            'results' => $results->lists('id'), // only the ids of the results are required
        ]);

        $response = $this->run(new RespondWithJsonJob($results))