search

allysonsilva / laravel-artisan-domain-contexts

A Laravel Package for using Artisan commands in Domain Contexts
MIT License
31 stars 4 forks source link
artisan-commands bounded-contexts console ddd domain-contexts laravel

readme

Laravel Artisan Domain Contexts

Social Card of Laravel Artisan Domain Contexts

PHP Version Laravel Version CI Status PHPCS - GitHub Workflow Status PHPMD - GitHub Workflow Status PHPStan - GitHub Workflow Status Coverage Status Code Quality/Consistency Latest Version Total Downloads MIT Licensed

Table of Contents

Overview

This package provides the ability to use artisan commands in different domain contexts. It allows to work interactively in the migration commands and seeders, choosing which class should be executed.

Concepts

What is "Domain"?

See the article for a better understanding!

What is "Contexts"?

See the article for better understanding!

Questions

Should I use this package in the default Laravel framework?

No, because the files handled by artisan are already in their default folders.

When should I use this package?

🚀 Installation

Requirements

The package has been developed and tested to work with the following minimum requirements:

Laravel version Compatibility

Laravel PHP Package Maintained
9.x 8.0 ^2.0 ✅
8.70 8.0 ^1.0 ✅

Install the Package

You can install the package via Composer:

composer require allysonsilva/laravel-artisan-domain-contexts

Publish the Config

You can then publish the package's config file by using the following command:

php artisan vendor:publish --tag="context-config"

🔧 Configuration

  1. Create a folder, inside the app folder with the same name as the config of config('context.folders.domain')

  2. Add trait to app/Console/Kernel.php file with usage options in all Laravel commands:

    use Illuminate\Console\Scheduling\Schedule;
use Illuminate\Foundation\Console\Kernel as ConsoleKernel;
+use Allyson\ArtisanDomainContext\Concerns\ArtisanConsoleTrait;

class Kernel extends ConsoleKernel
{
+    use ArtisanConsoleTrait;

  3. Inside the domain folder (config('context.folders.domain')), is where you can find Laravel components (such as migrations, seeders, models, jobs, etc). The names of the folders, where the classes are, are in the config of config('context.folders.components').

📖 Usage

To use commands by context, the following options have been added to Laravel commands:

Some options are only available in a certain command, but the --context option is present in all commands in the list below!

The list of standard laravel commands that were handled by adding these options can be seen table below.

Understanding the --context option

This option is present in all commands listed below!

When this option is passed in the command, then the component/class/resource is manipulated or created, according to the resource type setting in config('context.folders.components').

To change the path/name of the folder where the class should be manipulated or created, see the config in config('context.folders.components').

Example

So, for example, to create a middleware in a given context, in this case, in the user context, the command can be: php artisan make:middleware --context=User YourMiddleware.

A middleware class was created in app/Domain/User/Http/Middlewares/YourMiddleware.php.

If the config of config('context.folders.components.middlewares') has the value of Http/AnotherFolder instead of Http/Middlewares (default), and the previous command is executed, then the class would be created in app/Domain/User/Http/AnotherFolder/YourMiddleware.php.

Understanding the --context-namespace option

This option will only be used in the make commands, with that, see and explanation about it.

Understanding the --all-contexts option

When this option is passed in the command, then it will be executed non-interactively, that is, it will execute the context-specific filtered classes.

This option is not present in the make commands only in the migration and db:seed commands. See the table below.

It has the same behavior as the --force option.

Understanding the --only-default option

By default, migrations commands are executed in all contexts when no options are passed. To run migrations commands in Laravel's default folder (database/migrations) use this option.

This option is only in the migration and db:seed commands. It is not present in the make commands.

Understanding the --multi-databases option

This option is only present in migration commands!

By default the migration commands are run on the database configured in the DB_DATABASE env, so you can only use one database in the command. With this option, you can use multiple databases for the same command via the config config('context.migrations.databases')

When this option is passed, then the command will be executed on different databases according to the config of config('context.migrations.databases').

The config of config('context.migrations.databases') refers to the name of the database that the operation will be performed on.

List of commands using contexts

Commands Additional Command Options
--context --context-namespace --all-contexts --only-default --multi-databases
make:cast ✔️ ✔️
make:channel ✔️ ✔️
make:command ✔️ ✔️
make:event ✔️ ✔️
make:exception ✔️ ✔️
make:factory ✔️ ✔️
make:factory ✔️ ✔️
make:job ✔️ ✔️
make:listener ✔️ ✔️
make:mail ✔️ ✔️
make:middleware ✔️ ✔️
make:migration ✔️ ✔️
make:model ✔️ ✔️
make:notification ✔️ ✔️
make:observer ✔️ ✔️
make:policy ✔️ ✔️
make:provider ✔️ ✔️
make:request ✔️ ✔️
make:resource ✔️ ✔️
make:rule ✔️ ✔️
make:seeder ✔️ ✔️
migrate:fresh ✔️ ✔️
migrate:refresh ✔️ ✔️ ✔️
migrate:reset ✔️ ✔️ ✔️ ✔️
migrate:rollback ✔️ ✔️ ✔️ ✔️
migrate:status ✔️ ✔️ ✔️ ✔️
migrate ✔️ ✔️ ✔️ ✔️
db:seed ✔️ ✔️ ✔️

🏗 make commands

Make commands, create files in a given context or Laravel's default folder when no context is specified.

All the make commands that are listed in the table above, have 2 options in their command, which are:

To change the name of the component folder in which the class is created, see the following config config('context.folders.components').

Examples

The example commands below will use the following folder organization:

app/
├── Domain
│   ├── Foo
│   ├── Post
└── └── User

How to create a [MIGRATION] in a specific context?

Use the following command below as an example, passing the --context option with the name of the context in which the migration will be created.

The migration files will be saved in the config folder config('context.folders.components.migrations') in the context folder, according to the --context option of the command.

php artisan make:migration --context=Post create_posts_table

A new migration has been created at: app/Domain/Post/Database/Migrations/2022_xx_xx_xxxxxx_create_posts_table.php

The file path parts are:

How to create a [JOB] in a specific context?

In the same way as explained earlier in the case of migration, the --context option is also used to create a new job in a specific context.

php artisan make:job --context=Foo MyJob

A new job has been created at: app/Domain/Foo/Jobs/MyJob.php

The file path parts are:

How to create a class/component with a custom namespace?

Use the --context-namespace option to customize the class namespace prefix.

If you want to create a model with a specific namespace, Use the following command below as an example.

php artisan make:model --context=Post --context-namespace=PostDomain Post

The previous command will create a model in the path: app/Domain/Post/Models/Post.php

With the following content:

<?php

+namespace PostDomain\Models;

use Illuminate\Database\Eloquent\Factories\HasFactory;
use Illuminate\Database\Eloquent\Model;

class Post extends Model
{
    use HasFactory;
}

The namespace for the above class is: namespace PostDomain\Models.

How to create class in Laravel's default folder?

To create the class in the default Laravel folder, don't use/pass the --context option!

The following command will create the class in Laravel's default folder at app/Events/MyEvent.php.

php artisan make:event YourEvent

migrate commands

The migration commands are executed interactively, and you can even select each individual migration, or all migrations in a given context to perform the operation.

The following are the options that may be on commands:

To see the migration commands in action, let's use the folder organization below as an example and see the expected results:

app
└── Domain
    ├── Foo
    │   └── Database
    │       ├── Migrations
    │       │   ├── 2022_02_30_000000_create_baz_table.php
    │       │   └── 2022_02_30_000000_create_foo_table.php
    │       └── Seeders
    │           ├── BazTableSeeder.php
    │           └── FooTableSeeder.php
    ├── Post
    │   └── Database
    │       ├── Migrations
    │       │   ├── 2022_02_30_000000_create_posts_1_table.php
    │       │   ├── 2022_02_30_000000_create_posts_2_table.php
    │       │   └── 2022_02_30_000000_create_posts_3_table.php
    │       └── Seeders
    │           ├── PostsTableSeeder1.php
    │           ├── PostsTableSeeder2.php
    │           └── PostsTableSeeder3.php
    └── User
        └── Database
            ├── Migrations
            │   ├── 2022_02_30_000000_create_users_1_table.php
            │   ├── 2022_02_30_000000_create_users_2_table.php
            │   └── 2022_02_30_000000_create_users_3_table.php
            └── Seeders
                ├── UsersTableSeeder1.php
                ├── UsersTableSeeder2.php
                └── UsersTableSeeder3.php

Understanding the behavior of migrate:fresh and migrate:refresh

Both work in the same way / Summary:

See the questions and answers below for better understanding:

📹 Demo migrate:fresh

See the demo below for better understanding:

📹 Demo migrate:refresh

See the demo below for better understanding:

Understanding the behavior of migrate:reset, migrate:rollback, migrate:status and migrate

Summary of all commands:

See the questions and answers below for better understanding:

The $command variable, can be one of the items ['migrate:reset', 'migrate:rollback', 'migrate:status', 'migrate'].

📹 Demo migrate:reset

See the demo below for better understanding:

📹 Demo migrate:rollback

See the demo below for better understanding:

db:seed command

Three options are found in the command:

See the questions and answers below for better understanding:

📹 Demo db:seed

See the demo below for better understanding:

🧪 Testing

composer test:unit

📝 Changelog

Please see CHANGELOG for more information about the changes on this package.

🤝 Contributing

Please see CONTRIBUTING for details.

🔒 Security

If you discover any security related issues, please email github@allyson.dev instead of using the issue tracker.

🏆 Credits

License

The MIT License (MIT). Please see License File for more information.