{"id":13545523,"url":"https://github.com/lucidarch/laravel","last_synced_at":"2025-12-30T06:12:29.140Z","repository":{"id":55862054,"uuid":"42098946","full_name":"lucidarch/laravel","owner":"lucidarch","description":"[DEPRECATED] See https://github.com/lucidarch/lucid","archived":true,"fork":false,"pushed_at":"2020-10-26T15:28:16.000Z","size":530,"stargazers_count":373,"open_issues_count":0,"forks_count":66,"subscribers_count":30,"default_branch":"master","last_synced_at":"2025-11-27T15:23:53.757Z","etag":null,"topics":["architecture","laravel","lucid-architecture","microservices","microservices-architecture","php","scalable-applications","software-architecture","software-engineering","software-philosophy"],"latest_commit_sha":null,"homepage":"https://lucidarch.dev","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/lucidarch.png","metadata":{"files":{"readme":"readme.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null},"funding":{"github":null,"patreon":"mulkave","open_collective":null,"ko_fi":null,"tidelift":null,"community_bridge":null,"liberapay":null,"issuehunt":null,"otechie":null,"custom":null}},"created_at":"2015-09-08T08:10:46.000Z","updated_at":"2025-09-29T14:51:30.000Z","dependencies_parsed_at":"2022-08-15T08:00:43.686Z","dependency_job_id":null,"html_url":"https://github.com/lucidarch/laravel","commit_stats":null,"previous_names":[],"tags_count":28,"template":false,"template_full_name":null,"purl":"pkg:github/lucidarch/laravel","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lucidarch%2Flaravel","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lucidarch%2Flaravel/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lucidarch%2Flaravel/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lucidarch%2Flaravel/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/lucidarch","download_url":"https://codeload.github.com/lucidarch/laravel/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lucidarch%2Flaravel/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":27701840,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-12-13T02:00:09.769Z","response_time":147,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["architecture","laravel","lucid-architecture","microservices","microservices-architecture","php","scalable-applications","software-architecture","software-engineering","software-philosophy"],"created_at":"2024-08-01T11:01:04.886Z","updated_at":"2025-12-13T06:48:37.662Z","avatar_url":"https://github.com/lucidarch.png","language":"PHP","funding_links":["https://patreon.com/mulkave"],"categories":["PHP"],"sub_categories":[],"readme":"## Lucid\n\nThe Lucid Architecture is a software architecture that consolidates code-base maintenance as the application scales,\nfrom becoming overwhelming to handle, gets us rid of rotting code that will later become legacy code, and translate\nthe day-to-day language such as Feature and Service into actual, physical code.\n\nRead more about the [Lucid Architecture Concept](https://medium.com/vine-lab/the-lucid-architecture-concept-ad8e9ed0258f).\n\nIf you prefer a video, watch the announcement of The Lucid Architecture at LaraconEU 2016:\n\n##### The Lucid Architecture for Building Scalable Applications - Laracon EU 2016\n[![Abed Halawi - The Lucid Architecture for Building Scalable Applications](http://img.youtube.com/vi/wSnM4JkyxPw/0.jpg)](http://www.youtube.com/watch?v=wSnM4JkyxPw \"Abed Halawi - The Lucid Architecture for Building Scalable Applications\")\n\n\n### Join The Community on Slack\n[![Slack Status](https://lucid-slack.herokuapp.com/badge.svg)](https://lucid-slack.herokuapp.com)\n\n## Index\n- [Installation](#installation)\n- [Introduction](#introduction)\n    - [Components](#components)\n        - [Service](#service)\n        - [Feature](#feature)\n        - [Job](#job)\n    - [Data](#data)\n    - [Foundation](#foundation)\n- [Getting Started](#getting-started)\n- [Microservices](#microservices)\n\n## Installation\n\n### 8.x\nTo start your project with Lucid right away, run the following command:\n\n```\ncomposer create-project lucid-arch/laravel my-project\n```\n\nThis 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:\n\n\n#### 7.x\n\n```\ncomposer create-project lucid-arch/laravel=7.x my-project-7.x\n```\n\n##### 6.x\n```\ncomposer create-project lucid-arch/laravel=6.x my-project-6.x\n```\n\n##### 5.5\n```\ncomposer create-project lucid-arch/laravel=5.5.x my-project-5.5\n```\n\n## Introduction\n\n### Directory Structure\n```\nsrc\n├── Data\n├── Domains\n    └── * domain name *\n            ├── Jobs\n├── Foundation\n└── Services\n    └── * service name *\n        ├── Console\n        ├── Features\n        ├── Http\n        ├── Providers\n        ├── Tests\n        ├── database\n        └── resources\n```\n\n### Components\n| Component | Path | Description |\n|---------|--------| ----------- |\n| Service | src/Service/[service] | Place for the [Services](#service) |\n| Feature | src/Services/[service]/Features/[feature] | Place for the [Features](#feature) of [Services](#service) |\n| Job | src/Domains/[domain]/Jobs/[job] | Place for the [Jobs](#job) that expose the functionalities of Domains |\n| Data | src/Data | Place for models, repositories, value objects and anything data-related |\n| Foundation | src/Foundation | Place for foundational (abstract) elements used across the application |\n\n\n#### Service\nEach part of an application is a service (i.e. Api, Web, Backend). Typically, each of these will have their way of\nhandling and responding to requests, implementing different features of our application, hence, each of them will have\ntheir own routes, controllers, features and operations. A Service will seem like a sub-installation of a Laravel\napplication, though it is just a logical grouping than anything else.\n\nTo better understand the concept behind Services, think of the terminology as:\n\"Our application exposes data through an Api service\", \"You can manipulate and manage the data through the Backend service\".\n\nOne other perk of using Lucid is that it makes the transition process to a Microservices architecture simpler,\nwhen the application requires it. See [Microservices](#microservices).\n\n##### Service Directory Structure\n\nImagine we have generated a service called **Api**, can be done using the `lucid` cli by running:\n\n\u003e You might want to [Setup](#setup) to be able to use the `lucid` command.\n\n```\nlucid make:service api\n```\n\nWe will get the following directory structure:\n\n```\nsrc\n└── Services\n    └── Api\n        ├── Console\n        ├── Features\n        ├── Http\n        │   ├── Controllers\n        │   ├── Middleware\n        │   ├── Requests\n        │   └── routes.php\n        ├── Providers\n        │   ├── ApiServiceProvider.php\n        │   └── RouteServiceProvider.php\n        ├── Tests\n        │   └── Features\n        ├── database\n        │   ├── migrations\n        │   └── seeds\n        └── resources\n            ├── lang\n            └── views\n                └── welcome.blade.php\n```\n\n#### Feature\n\nA Feature is exactly what a feature is in our application (think Login feature, Search for hotel feature, etc.) as a class.\nFeatures are what the Services' controllers will serve, so our controllers will end up having only one line in our methods, hence,\nthe thinnest controllers ever! Here's an example of generating a feature and serving it through a controller:\n\n\u003e You might want to [Setup](#setup) to be able to use the `lucid` command.\n\n\u003e IMPORTANT! You need at least one service to be able to host your features. In this example we are using the Api\nservice generated previously, referred to as `api` in the commands.\n\n```\nlucid make:feature SearchUsers api\n```\n\nAnd we will have `src/Services/Api/Features/SearchUsersFeature.php` and its test `src/Services/Api/Tests/Features/SearchUsersFeatureTest.php`.\n\nInside the Feature class, there's a `handle` method which is the method that will be called when we dispatch that feature,\nand it supports dependency injection, which is the perfect place to define your dependencies.\n\nNow we need a controller to serve that feature:\n```\nlucid make:controller user api\n```\n\nAnd our `UserController` is in `src/Services/Api/Http/Controllers/UserController.php` and to serve that feature,\nin a controller method we need to call its `serve` method as such:\n\n```\nnamespace App\\Services\\Api\\Http\\Controllers;\n\nuse App\\Services\\Api\\Features\\SearchUsersFeature;\n\nclass UserController extends Controller\n{\n    public function index()\n    {\n        return $this-\u003eserve(SearchUsersFeature::class);\n    }\n}\n```\n#### Views\nTo access a service's view file, prepend the file's name with the service name followed by two colons `::`\n\nExample extending view file in blade:\n```\n@extends('servicename::index')\n```\n\nUsage with jobs is similar:\n```php\nnew RespondWithViewJob('servicename::user.login')\n```\n\n`RespondWithJsonJob` accepts the following parameters:\n```php\nRespondWithViewJob($template, $data = [], $status = 200, array $headers = []);\n```\n\nUsage of template with data:\n```php\n$this-\u003erun(new RespondWithViewJob('servicename::user.list', ['users' =\u003e $users]));\n```\nOr\n```php\n$this-\u003erun(RespondWithViewJob::class, [\n    'template' =\u003e 'servicename::user.list',\n    'data' =\u003e [\n        'users' =\u003e $users\n    ],\n]);\n```\n\n#### Job\nA Job is responsible for one element of execution in the application, and play the role of a step in the accomplishment\nof a feature. They are the stewards of reusability in our code.\n\nJobs live inside Domains, which requires them to be abstract, isolated and independent from any other job be it\nin the same domain or another - whatever the case, no Job should dispatch another Job.\n\nThey can be ran by any Feature from any Service, and it is the *only way* of communication between services and domains.\n\n*Example:* Our `SearchUsersFeature` has to perform the following steps:\n\n- Validate user search query\n- Log the query somewhere we can look at later\n- If results were found\n    - Log the results for later reference (async)\n    - Increment the number of searches on the found elements (async)\n    - Return results\n- If no results were found\n    - Log the query in a \"high priority\" log so that it can be given more attention\n\nEach of these steps will have a job in its name, implementing only that step. They must be generated in their corresponding\ndomains that they implement the functionality of, i.e. our `ValidateUserSearchQueryJob` has to do with user input,\nhence it should be in the `User` domain. While logging has nothing to do with users and might be used in several other\nplaces so it gets a domain of its own and we generate the `LogSearchResultsJob` in that `Log` domain.\n\nTo generate a Job, use the `make:job \u003cjob\u003e \u003cdomain\u003e` command:\n\n```\nlucid make:job SearchUsersByName user\n```\n\nSimilar to Features, Jobs also implement the `handle` method that gets its dependencies resolved, but sometimes\nwe might want to pass in input that doesn't necessarily have to do with dependencies, those are the params of the job's\nconstructor, specified here in `src/Domains/User/Jobs/SearchUsersByNameJob.php`:\n\n```php\nnamespace App\\Domains\\User\\Jobs;\n\nuse Lucid\\Foundation\\Job;\n\nclass SearchUsersByNameJob extends Job\n{\n    private $query;\n    private $limit;\n\n    public function __construct($query, $limit = 25)\n    {\n        $this-\u003equery = $query;\n        $this-\u003elimit = $limit;\n    }\n\n    public function handle(User $user)\n    {\n        return $user-\u003ewhere('name', $this-\u003equery)-\u003etake($this-\u003elimit)-\u003eget();\n    }\n}\n```\n\nNow we need to run this and the rest of the steps we mentioned in `SearchUsersFeature::handle`:\n\n```php\npublic function handle(Request $request)\n{\n    // validate input - if not valid the validator should\n    // throw an exception of InvalidArgumentException\n    $this-\u003erun(new ValidateUserSearchQueryJob($request-\u003einput()));\n\n    $results = $this-\u003erun(SearchUsersJob::class, [\n        'query' =\u003e $request-\u003einput('query'),\n    ]);\n\n    if (empty($results)) {\n        $this-\u003erun(LogEmptySearchResultsJob::class, [\n            'date' =\u003e new DateTime(),\n            'query' =\u003e $request-\u003equery(),\n        ]);\n\n        $response = $this-\u003erun(new RespondWithJsonErrorJob('No users found'));\n    } else {\n        // this job is queueable so it will automatically get queued\n        // and dispatched later.\n        $this-\u003erun(LogUserSearchJob::class, [\n            'date' =\u003e new DateTime(),\n            'query' =\u003e $request-\u003einput(),\n            'results' =\u003e $results-\u003elists('id'), // only the ids of the results are required\n        ]);\n\n        $response = $this-\u003erun(new RespondWithJsonJob($results));\n    }\n\n    return $response;\n}\n```\n\nAs you can see, the sequence of steps is clearly readable with the least effort possible when following each `$this-\u003erun`\ncall, and the signatures of each Job are easy to understand.\n\nA few things to note regarding the implementation above:\n\n- There is no difference between running a job by instantiating it like `$this-\u003erun(new SomeJob)` and\npassing its class name `$this-\u003erun(SomeJob::class)`\nit is simply a personal preference for readability and writing less code, when a Job takes only one parameter\nit's instantiated.\n- The order of parameters that we use when calling a job with its class name is irrelevant to their order in the\nJob's constructor signature. i.e.\n```php\n$this-\u003erun(LogUserSearchJob::class, [\n    'date' =\u003e new DateTime(),\n    'query' =\u003e $request-\u003einput(),\n    'resultIds' =\u003e $results-\u003elists('id'), // only the ids of the results are required\n]);\n```\n```php\nclass LogUserSearchJob\n{\n    public function __construct($query, array $resultIds, DateTime $date)\n    {\n        // ...\n    }\n}\n```\nThis will work perfectly fine, as long as the key name (`'resultIds' =\u003e ...`) is the same as the variable's name in the constructor (`$resultIds`)\n- Of course, we need to create and import (`use`) our Job classes with the correct namespaces, but we won't do that here\nsince this is only to showcase and not intended to be running, for a working example see [Getting Started](#getting-started).\n\n## Data\nData is not really a component, more like a directory for all your data-related classes such as Models, Repositories,\nValue Objects and anything that has to do with data (algorithms etc.).\n\n## Foundation\nThis is a place for foundational elements that act as the most abstract classes that do not belong in any of the\ncomponents, currently holds the `ServiceProvider` which is the link between the services and the framework (Laravel).\nYou might never need or use this directory for anything else, but in case you encountered a case where a class\nneeds to be shared across all components and does belong in any, feel free to use this one.\n\nEvery service must be registered inside the foundation's service provider after being created for Laravel to know about it,\nsimply add `$this-\u003eapp-\u003eregister([service name]ServiceProvider::class);` to the `register` methods of the\nfoundation's `ServiceProvider`. For example, with an Api Service:\n\n```php\n// ...\nuse App\\Services\\Api\\Providers\\ApiServiceProvider;\n// ...\npublic function register()\n{\n    $this-\u003eapp-\u003eregister(ApiServiceProvider::class);\n}\n```\n\n## Getting Started\nThis project ships with the [Lucid Console](https://github.com/lucid-architecture/laravel-console) which provides an interactive\nuser interface and a command line interface that are useful for scaffolding and exploring Services, Features, and Jobs.\n\n### Setup\nThe `lucid` executable will be in `vendor/bin`. If you don't have `./vendor/bin/` as part of your `PATH` you will\nneed to execute it using `./vendor/bin/lucid`, otherwise add it with the following command to be able to simply\ncall `lucid`:\n\n```\nexport PATH=\"./vendor/bin:$PATH\"\n```\n\nFor a list of all the commands that are available run `lucid` or see the [CLI Reference](https://github.com/lucid-architecture/laravel-console).\n\n#### Launching the Interactive Console (UI)\n\n1. Serve Application\nOne way is to use the built-in server by running:\n```bash\nphp artisan serve\n```\n\u003e Any other method would also work (Apache, Nginx, etc...)\n2. Run `php artisan vendor:publish --provider=\"Lucid\\Console\\LucidServiceProvider\"`\n3. Visit your application at */lucid/dashboard*\n\n### 1. Create a Service\n\n##### CLI\n```\nlucid make:service Api\n```\n\n##### UI\n\n\n\nUsing one of the methods above, a new service folder must've been created under `src/Services` with the name `Api`.\n\nThe **Api** directory will initially contain the following directories:\n\n```\nsrc/Services/Api\n├── Console         # Everything that has to do with the Console (i.e. Commands)\n├── Features        # Contains the Api's Features classes\n├── Http            # Routes, controllers and middlewares\n├── Providers       # Service providers and binding\n├── database        # Database migrations and seeders\n└── resources       # Assets, Lang and Views\n```\n\nOne more step is required for Laravel to recognize the service we just created.\n\n#### Register Service\n\n- Open `src/Foundation/Providers/ServiceProvider`\n- Add `use App\\Services\\Api\\Providers\\ApiServiceProvider`\n- In the `register` method add `$this-\u003eapp-\u003eregister(ApiServiceProvider::class)`\n\n### 2. Create a Feature\n\n##### CLI\n```\nlucid make:feature ListUsers api\n```\n\n##### UI\n\nUsing one of the methods above, the new Feature can be found at `src/Services/Api/Features/ListUsersFeature.php`.\nNow you can fill up a bunch of jobs in its `handle` method.\n\n### 3. Create a Job\nThis project ships with a couple of jobs that can be found in their corresponding domains under `src/Domains`\n\n##### CLI\n```\nlucid make:job GetUsers user\n```\n\n##### UI\n\nUsing one of the methods above, the new Job can be found at `src/Domains/User/Jobs/GetUsers` and now you can fill\nit with functionality in the `handle` method. For this example we will just add a static `return` statement:\n\n```php\npublic function handle()\n{\n    return [\n        ['name' =\u003e 'John Doe'],\n        ['name' =\u003e 'Jane Doe'],\n        ['name' =\u003e 'Tommy Atkins'],\n    ];\n}\n```\n\n### 4. All Together\nBack to the Feature we generated earlier, add `$this-\u003erun(GetUsersJob)` (remember to `use` the job with the correct\nnamespace `App\\Domains\\User\\Jobs\\GetUsersJob`).\n\n##### Run The Job\nIn **ListUsersFeature::handle(Request $request)**\n\n```php\npublic function handle(Request $request)\n{\n    $users = $this-\u003erun(GetUsersJob::class);\n\n    return $this-\u003erun(new RespondWithJsonJob($users));\n}\n```\n\nThe `RespondWithJsonJob` is one of the Jobs that were shipped with this project, it lives in the `Http` domain and is\nused to respond to a request in a structured JSON format.\n\n##### Serve The Feature\nTo be able to serve that Feature we need to create a route and a controller that does so.\n\nGenerate a plain controller with the following command\n\n```\nlucid make:controller user api --plain\n```\n\nAdd the `get` method to it:\n\n```php\nclass UserController extends Controller\n{\n    public function get()\n    {\n        return $this-\u003eserve(ListUsersFeature::class);\n    }\n}\n```\n\nWe just need to create a route that would delegate the request to our `get` method:\n\nIn `src/Services/Api/Http/routes.php` you will find the route group `Route::group(['prefix' =\u003e 'api'], function() {...`\nAdd the `/users` route within that group.\n\n```php\nRoute::get('/users', 'UserController@get');\n```\n\nNow if you visit `/api/users` you should see the JSON structure.\n\n## Microservices\nIf you have been hearing about microservices lately, and wondering how that works and would like to plan your next project\nbased on microservices, or build your application armed and ready for the shift when it occurs, Lucid is your best bet.\nIt has been designed with scale at the core and the microservice transition in mind, it is no coincidence that the\ndifferent parts of the application that will (most probably) later on become the different services with the microservice\narchitecture are called **Service**. However, [it is recommended](http://martinfowler.com/bliki/MonolithFirst.html)\nthat only when your monolith application grow so large that it becomes crucial to use microservices for the sake of\nthe progression and maintenance of the project, to do the shift; because once you've built your application using Lucid,\nthe transition to a microservice architecture will be logically simpler to plan and physically straight-forward\nto implement. There is a [microservice counterpart](https://github.com/lucid-architecture/laravel-microservice)\nto Lucid that you can check out [here](https://github.com/lucid-architecture/laravel-microservice).\n\nWith more on the means of transitioning from a monolith to a microservice.\n\n### Event Hooks\n\nLucid exposes event hooks that allow you to listen on each dispatched feature, operation or job. This is especially useful for tracing:\n\n```php\nuse Illuminate\\Support\\Facades\\Event;\nuse Lucid\\Foundation\\Events\\FeatureStarted;\nuse Lucid\\Foundation\\Events\\OperationStarted;\nuse Lucid\\Foundation\\Events\\JobStarted;\n\nEvent::listen(FeatureStarted::class, function (FeatureStarted $event) {\n    // $event-\u003ename\n    // $event-\u003earguments\n});\n\nEvent::listen(OperationStarted::class, function (OperationStarted $event) {\n    // $event-\u003ename\n    // $event-\u003earguments\n});\n\nEvent::listen(JobStarted::class, function (JobStarted $event) {\n    // $event-\u003ename\n    // $event-\u003earguments\n});\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flucidarch%2Flaravel","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flucidarch%2Flaravel","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flucidarch%2Flaravel/lists"}