├── src
    ├── stubs
    │   └── action.stub
    ├── Contracts
    │   ├── Configurable.php
    │   └── ShouldInterpreter.php
    ├── Exceptions
    │   ├── PreventLoop.php
    │   ├── ActionNotRegistered.php
    │   ├── UnallowedActionDuplication.php
    │   ├── PreventDeferQueueSameTime.php
    │   └── DependencyUnresolvable.php
    ├── config.php
    ├── Configurable
    │   ├── RescuedUsing.php
    │   ├── DeferUsing.php
    │   ├── LoggedUsing.php
    │   └── QueueUsing.php
    ├── ValueObjects
    │   └── Then.php
    ├── Concerns
    │   ├── UsingThen.php
    │   ├── UsingRescue.php
    │   ├── UsingDefer.php
    │   ├── UsingQueue.php
    │   └── UsingLogged.php
    ├── Facades
    │   └── Fraction.php
    ├── helpers.php
    ├── Support
    │   ├── FractionName.php
    │   ├── Bootable.php
    │   └── DependencyResolver.php
    ├── FractionServiceProvider.php
    ├── Handlers
    │   ├── AsDefer.php
    │   ├── AsQueue.php
    │   ├── AsSync.php
    │   └── Concerns
    │   │   └── ShareableInterpreter.php
    ├── Jobs
    │   └── FractionJob.php
    ├── FractionManager.php
    ├── Console
    │   ├── MakeActionCommand.php
    │   └── UnregisteredActionsCommand.php
    └── FractionBuilder.php
├── LICENSE
├── README.md
└── composer.json


/src/stubs/action.stub:
--------------------------------------------------------------------------------
1 | <?php
2 | 
3 | execute('{{ name }}', function () {
4 |     // ...
5 | });
6 | 


--------------------------------------------------------------------------------
/src/Contracts/Configurable.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | 
 3 | declare(strict_types=1);
 4 | 
 5 | namespace Fraction\Contracts;
 6 | 
 7 | interface Configurable
 8 | {
 9 |     /**
10 |      * Configure the interpreter with the given data.
11 |      */
12 |     public function configure(array $data): void;
13 | }
14 | 


--------------------------------------------------------------------------------
/src/Exceptions/PreventLoop.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | 
 3 | declare(strict_types=1);
 4 | 
 5 | namespace Fraction\Exceptions;
 6 | 
 7 | use Exception;
 8 | 
 9 | final class PreventLoop extends Exception
10 | {
11 |     public function __construct()
12 |     {
13 |         parent::__construct('The hook "then" cannot be used to invoke itself.');
14 |     }
15 | }
16 | 


--------------------------------------------------------------------------------
/src/Exceptions/ActionNotRegistered.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | 
 3 | declare(strict_types=1);
 4 | 
 5 | namespace Fraction\Exceptions;
 6 | 
 7 | use Exception;
 8 | 
 9 | final class ActionNotRegistered extends Exception
10 | {
11 |     public function __construct(string $action)
12 |     {
13 |         parent::__construct("The action [{$action}] is not registered.");
14 |     }
15 | }
16 | 


--------------------------------------------------------------------------------
/src/Exceptions/UnallowedActionDuplication.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | 
 3 | declare(strict_types=1);
 4 | 
 5 | namespace Fraction\Exceptions;
 6 | 
 7 | use Exception;
 8 | 
 9 | final class UnallowedActionDuplication extends Exception
10 | {
11 |     public function __construct(string $action)
12 |     {
13 |         parent::__construct("The action [{$action}] is already registered.");
14 |     }
15 | }
16 | 


--------------------------------------------------------------------------------
/src/Exceptions/PreventDeferQueueSameTime.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | 
 3 | declare(strict_types=1);
 4 | 
 5 | namespace Fraction\Exceptions;
 6 | 
 7 | use Exception;
 8 | 
 9 | final class PreventDeferQueueSameTime extends Exception
10 | {
11 |     public function __construct(string $action)
12 |     {
13 |         parent::__construct("The action [$action] cannot use defer and queue at the same time.");
14 |     }
15 | }
16 | 


--------------------------------------------------------------------------------
/src/Contracts/ShouldInterpreter.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | 
 3 | declare(strict_types=1);
 4 | 
 5 | namespace Fraction\Contracts;
 6 | 
 7 | use Illuminate\Container\Container;
 8 | 
 9 | interface ShouldInterpreter
10 | {
11 |     /**
12 |      * Handle the action.
13 |      */
14 |     public function handle(Container $container): mixed;
15 | 
16 |     /**
17 |      * Register the action's hooks.
18 |      */
19 |     public function then(array $then): self;
20 | }
21 | 


--------------------------------------------------------------------------------
/src/Exceptions/DependencyUnresolvable.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | 
 3 | declare(strict_types=1);
 4 | 
 5 | namespace Fraction\Exceptions;
 6 | 
 7 | use Exception;
 8 | 
 9 | /** @codeCoverageIgnore */
10 | final class DependencyUnresolvable extends Exception
11 | {
12 |     public function __construct(string $name, string $action)
13 |     {
14 |         parent::__construct("The dependency [{$name}] cannot be resolved for the action [{$action}].");
15 |     }
16 | }
17 | 


--------------------------------------------------------------------------------
/src/config.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | 
 3 | return [
 4 |     /*
 5 |     |--------------------------------------------------------------------------
 6 |     | Action Path
 7 |     |--------------------------------------------------------------------------
 8 |     |
 9 |     | This option defines the default path where the action files will be
10 |     | stored. You can change this path to suit your application's structure.
11 |     |
12 |     */
13 | 
14 |     'path' => base_path('app/Actions'),
15 | ];
16 | 


--------------------------------------------------------------------------------
/src/Configurable/RescuedUsing.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | 
 3 | declare(strict_types=1);
 4 | 
 5 | namespace Fraction\Configurable;
 6 | 
 7 | use Illuminate\Contracts\Support\Arrayable;
 8 | 
 9 | final readonly class RescuedUsing implements Arrayable
10 | {
11 |     public function __construct(
12 |         public mixed $default = null,
13 |     ) {
14 |         //
15 |     }
16 | 
17 |     /** {@inheritDoc} */
18 |     public function toArray(): array
19 |     {
20 |         return [
21 |             'default' => $this->default,
22 |         ];
23 |     }
24 | }
25 | 


--------------------------------------------------------------------------------
/src/ValueObjects/Then.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | 
 3 | declare(strict_types=1);
 4 | 
 5 | namespace Fraction\ValueObjects;
 6 | 
 7 | use Fraction\Exceptions\PreventLoop;
 8 | use Fraction\Support\FractionName;
 9 | use UnitEnum;
10 | 
11 | final class Then
12 | {
13 |     /**
14 |      * @throws PreventLoop
15 |      */
16 |     public function __construct(public string $action, public string|UnitEnum $then)
17 |     {
18 |         if (FractionName::format($action) === FractionName::format($then)) {
19 |             throw new PreventLoop();
20 |         }
21 |     }
22 | }
23 | 


--------------------------------------------------------------------------------
/src/Concerns/UsingThen.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | 
 3 | declare(strict_types=1);
 4 | 
 5 | namespace Fraction\Concerns;
 6 | 
 7 | use Fraction\ValueObjects\Then;
 8 | use UnitEnum;
 9 | 
10 | trait UsingThen
11 | {
12 |     /**
13 |      * The array of "then" hooks.
14 |      *
15 |      * @var array<int, string>
16 |      */
17 |     private ?array $then = [];
18 | 
19 |     /**
20 |      * Register a "then" hook.
21 |      */
22 |     public function then(string|UnitEnum $action): self
23 |     {
24 |         $this->then[] = new Then($this->action, $action);
25 | 
26 |         return $this;
27 |     }
28 | }
29 | 


--------------------------------------------------------------------------------
/src/Concerns/UsingRescue.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | 
 3 | declare(strict_types=1);
 4 | 
 5 | namespace Fraction\Concerns;
 6 | 
 7 | use Fraction\Configurable\RescuedUsing;
 8 | 
 9 | trait UsingRescue
10 | {
11 |     /**
12 |      * Indicates if the action should be rescued.
13 |      */
14 |     private ?RescuedUsing $rescued = null;
15 | 
16 |     /**
17 |      * Enable the action to be rescued.
18 |      *
19 |      * @return $this
20 |      */
21 |     public function rescued(mixed $default = null): self
22 |     {
23 |         $this->rescued = new RescuedUsing($default);
24 | 
25 |         return $this;
26 |     }
27 | }
28 | 


--------------------------------------------------------------------------------
/src/Configurable/DeferUsing.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | 
 3 | declare(strict_types=1);
 4 | 
 5 | namespace Fraction\Configurable;
 6 | 
 7 | use Illuminate\Contracts\Support\Arrayable;
 8 | 
 9 | final readonly class DeferUsing implements Arrayable
10 | {
11 |     public function __construct(
12 |         public ?string $name = null,
13 |         public ?bool $always = false,
14 |     ) {
15 |         //
16 |     }
17 | 
18 |     /** {@inheritDoc} */
19 |     public function toArray(): array
20 |     {
21 |         return [
22 |             'name'   => $this->name,
23 |             'always' => $this->always,
24 |         ];
25 |     }
26 | }
27 | 


--------------------------------------------------------------------------------
/src/Facades/Fraction.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | 
 3 | declare(strict_types=1);
 4 | 
 5 | namespace Fraction\Facades;
 6 | 
 7 | use Illuminate\Support\Facades\Facade;
 8 | 
 9 | /**
10 |  * @method static \Fraction\FractionBuilder register(string|\UnitEnum $action, \Closure $closure)
11 |  * @method static \Fraction\FractionBuilder get(string|\UnitEnum $action)
12 |  * @method static array all()
13 |  * @method static void boot()
14 |  *
15 |  * @see \Fraction\FractionManager
16 |  */
17 | class Fraction extends Facade
18 | {
19 |     public static function getFacadeAccessor(): string
20 |     {
21 |         return 'fraction';
22 |     }
23 | }
24 | 


--------------------------------------------------------------------------------
/src/Concerns/UsingDefer.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | 
 3 | declare(strict_types=1);
 4 | 
 5 | namespace Fraction\Concerns;
 6 | 
 7 | use Fraction\Configurable\DeferUsing;
 8 | 
 9 | trait UsingDefer
10 | {
11 |     /**
12 |      * Configuration for deferring the action.
13 |      */
14 |     private ?DeferUsing $deferred = null;
15 | 
16 |     /**
17 |      * Enable the action to be deferred.
18 |      *
19 |      * @return $this
20 |      */
21 |     public function deferred(
22 |         bool $always = false,
23 |         ?string $name = null,
24 |     ): self {
25 |         $this->deferred = new DeferUsing($name, $always);
26 | 
27 |         return $this;
28 |     }
29 | }
30 | 


--------------------------------------------------------------------------------
/src/helpers.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | 
 3 | declare(strict_types=1);
 4 | 
 5 | use Fraction\Facades\Fraction;
 6 | use Fraction\FractionBuilder;
 7 | 
 8 | if (! function_exists('execute')) {
 9 |     /**
10 |      * Register a new action.
11 |      */
12 |     function execute(string|UnitEnum $action, Closure $closure): FractionBuilder
13 |     {
14 |         return Fraction::register($action, $closure);
15 |     }
16 | }
17 | 
18 | if (! function_exists('run')) {
19 |     /**
20 |      * Execute an action.
21 |      */
22 |     function run(string|UnitEnum $action, ...$args): mixed
23 |     {
24 |         $builder = Fraction::get($action);
25 | 
26 |         return $builder(...$args);
27 |     }
28 | }
29 | 


--------------------------------------------------------------------------------
/src/Configurable/LoggedUsing.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | 
 3 | declare(strict_types=1);
 4 | 
 5 | namespace Fraction\Configurable;
 6 | 
 7 | use Illuminate\Contracts\Support\Arrayable;
 8 | 
 9 | final class LoggedUsing implements Arrayable
10 | {
11 |     public function __construct(
12 |         public ?string $channel = null,
13 |         public ?string $message = null,
14 |     ) {
15 |         $this->message = $message ?? __('[:name] Action: [:action] executed.');
16 |     }
17 | 
18 |     /** {@inheritDoc} */
19 |     public function toArray(): array
20 |     {
21 |         return [
22 |             'channel' => $this->channel,
23 |             'message' => $this->message,
24 |         ];
25 |     }
26 | }
27 | 


--------------------------------------------------------------------------------
/src/Concerns/UsingQueue.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | 
 3 | declare(strict_types=1);
 4 | 
 5 | namespace Fraction\Concerns;
 6 | 
 7 | use Fraction\Configurable\QueueUsing;
 8 | 
 9 | trait UsingQueue
10 | {
11 |     /**
12 |      * Configuration for queueing the action.
13 |      */
14 |     private ?QueueUsing $queued = null;
15 | 
16 |     /**
17 |      * Enable the action to be queued.
18 |      *
19 |      * @return $this
20 |      */
21 |     public function queued(
22 |         mixed $delay = null,
23 |         ?string $queue = null,
24 |         ?string $connection = null,
25 |     ): self {
26 |         $this->queued = new QueueUsing($delay, $queue, $connection);
27 | 
28 |         return $this;
29 |     }
30 | }
31 | 


--------------------------------------------------------------------------------
/src/Concerns/UsingLogged.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | 
 3 | declare(strict_types=1);
 4 | 
 5 | namespace Fraction\Concerns;
 6 | 
 7 | use Fraction\Configurable\LoggedUsing;
 8 | 
 9 | trait UsingLogged
10 | {
11 |     /**
12 |      * Configuration for logging the action.
13 |      */
14 |     private ?LoggedUsing $logged = null;
15 | 
16 |     /**
17 |      * Enable the action to be deferred.
18 |      *
19 |      * @param  string|null  $channel  - `null` to use the default logging channel.
20 |      * @return $this
21 |      */
22 |     public function logged(?string $channel = null): self
23 |     {
24 |         $this->logged = new LoggedUsing($channel ?? config('logging.default'));
25 | 
26 |         return $this;
27 |     }
28 | }
29 | 


--------------------------------------------------------------------------------
/src/Configurable/QueueUsing.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | 
 3 | declare(strict_types=1);
 4 | 
 5 | namespace Fraction\Configurable;
 6 | 
 7 | use Illuminate\Contracts\Support\Arrayable;
 8 | 
 9 | final readonly class QueueUsing implements Arrayable
10 | {
11 |     public function __construct(
12 |         public mixed $delay = null,
13 |         public ?string $queue = null,
14 |         public ?string $connection = null,
15 |     ) {
16 |         //
17 |     }
18 | 
19 |     /** {@inheritDoc} */
20 |     public function toArray(): array
21 |     {
22 |         return [
23 |             'delay'      => $this->delay,
24 |             'queue'      => $this->queue,
25 |             'connection' => $this->connection,
26 |         ];
27 |     }
28 | }
29 | 


--------------------------------------------------------------------------------
/src/Support/FractionName.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | 
 3 | declare(strict_types=1);
 4 | 
 5 | namespace Fraction\Support;
 6 | 
 7 | use Illuminate\Support\Str;
 8 | use InvalidArgumentException;
 9 | use UnitEnum;
10 | 
11 | /** @internal */
12 | final class FractionName
13 | {
14 |     /**
15 |      * Format the action name to an internal action name.
16 |      */
17 |     public static function format(string|UnitEnum $action): string
18 |     {
19 |         $action = $action instanceof UnitEnum
20 |             ? $action->name
21 |             : $action;
22 | 
23 |         if (mb_strlen($action) > 50) {
24 |             throw new InvalidArgumentException('Fraction name cannot be longer than 50 characters.');
25 |         }
26 | 
27 |         return '__fraction.'.Str::of($action)
28 |             ->lower()
29 |             ->trim()
30 |             ->snake()
31 |             ->value();
32 |     }
33 | }
34 | 


--------------------------------------------------------------------------------
/src/Support/Bootable.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | 
 3 | declare(strict_types=1);
 4 | 
 5 | namespace Fraction\Support;
 6 | 
 7 | /**
 8 |  * @internal
 9 |  *
10 |  * @codeCoverageIgnore
11 |  */
12 | final readonly class Bootable
13 | {
14 |     public function __construct()
15 |     {
16 |         //
17 |     }
18 | 
19 |     /**
20 |      * Boot the fraction.
21 |      */
22 |     public static function fire(): void
23 |     {
24 |         $class = new self();
25 | 
26 |         $files = $class->files();
27 | 
28 |         if ($files === [] || $files === false) {
29 |             return;
30 |         }
31 | 
32 |         foreach ($files as $file) {
33 |             require $file;
34 |         }
35 |     }
36 | 
37 |     /**
38 |      * Get the files to be booted.
39 |      */
40 |     private function files(): array|false
41 |     {
42 |         return glob(config('fraction.path').'/*.php');
43 |     }
44 | }
45 | 


--------------------------------------------------------------------------------
/src/FractionServiceProvider.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | 
 3 | declare(strict_types=1);
 4 | 
 5 | namespace Fraction;
 6 | 
 7 | use Fraction\Facades\Fraction;
 8 | use Illuminate\Foundation\Application;
 9 | use Illuminate\Support\ServiceProvider;
10 | 
11 | class FractionServiceProvider extends ServiceProvider
12 | {
13 |     public function register(): void
14 |     {
15 |         $this->app->singleton('fraction', fn (Application $app) => new FractionManager($app));
16 | 
17 |         $this->mergeConfigFrom(__DIR__.'/config.php', 'fraction');
18 | 
19 |         if ($this->app->runningInConsole()) {
20 |             $this->commands([
21 |                 Console\MakeActionCommand::class,
22 |                 Console\UnregisteredActionsCommand::class,
23 |             ]);
24 |         }
25 |     }
26 | 
27 |     public function boot(): void
28 |     {
29 |         $this->publishes([
30 |             __DIR__.'/config.php' => config_path('fraction.php'),
31 |         ], 'fraction-config');
32 | 
33 |         Fraction::boot();
34 |     }
35 | }
36 | 


--------------------------------------------------------------------------------
/src/Handlers/AsDefer.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | 
 3 | declare(strict_types=1);
 4 | 
 5 | namespace Fraction\Handlers;
 6 | 
 7 | use Fraction\Configurable\DeferUsing;
 8 | use Fraction\Contracts\Configurable;
 9 | use Fraction\Contracts\ShouldInterpreter;
10 | use Fraction\Handlers\Concerns\ShareableInterpreter;
11 | use Illuminate\Container\Container;
12 | 
13 | final class AsDefer implements Configurable, ShouldInterpreter
14 | {
15 |     use ShareableInterpreter;
16 | 
17 |     public DeferUsing $defer;
18 | 
19 |     public function handle(Container $container): true
20 |     {
21 |         $dependencies = $this->dependencies($container);
22 | 
23 |         \Illuminate\Support\defer(
24 |             fn () => $dependencies->resolve($this->closure, $this->arguments),
25 |             $this->defer->name,
26 |             $this->defer->always,
27 |         );
28 | 
29 |         $this->hooks();
30 | 
31 |         return true;
32 |     }
33 | 
34 |     public function configure(array $data): void
35 |     {
36 |         $this->defer = new DeferUsing(...$data);
37 |     }
38 | }
39 | 


--------------------------------------------------------------------------------
/src/Handlers/AsQueue.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | 
 3 | declare(strict_types=1);
 4 | 
 5 | namespace Fraction\Handlers;
 6 | 
 7 | use Fraction\Configurable\QueueUsing;
 8 | use Fraction\Contracts\Configurable;
 9 | use Fraction\Contracts\ShouldInterpreter;
10 | use Fraction\Handlers\Concerns\ShareableInterpreter;
11 | use Fraction\Jobs\FractionJob;
12 | use Illuminate\Container\Container;
13 | use Illuminate\Foundation\Bus\PendingDispatch;
14 | 
15 | final class AsQueue implements Configurable, ShouldInterpreter
16 | {
17 |     use ShareableInterpreter;
18 | 
19 |     public QueueUsing $queue;
20 | 
21 |     public function handle(Container $container): PendingDispatch
22 |     {
23 |         return FractionJob::dispatch(
24 |             $this->action,
25 |             $this->arguments,
26 |             $this->closure,
27 |             $this->then
28 |         )
29 |             ->delay($this->queue->delay)
30 |             ->onQueue($this->queue->queue)
31 |             ->onConnection($this->queue->connection);
32 |     }
33 | 
34 |     public function configure(array $data): void
35 |     {
36 |         $this->queue = new QueueUsing(...$data);
37 |     }
38 | }
39 | 


--------------------------------------------------------------------------------
/LICENSE:
--------------------------------------------------------------------------------
 1 | MIT License
 2 | 
 3 | Copyright (c) 2025 AJ Meireles
 4 | 
 5 | Permission is hereby granted, free of charge, to any person obtaining a copy
 6 | of this software and associated documentation files (the "Software"), to deal
 7 | in the Software without restriction, including without limitation the rights
 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 9 | copies of the Software, and to permit persons to whom the Software is
10 | furnished to do so, subject to the following conditions:
11 | 
12 | The above copyright notice and this permission notice shall be included in all
13 | copies or substantial portions of the Software.
14 | 
15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21 | SOFTWARE.
22 | 


--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
 1 | # Welcome to _Fraction_ 🎯
 2 | 
 3 | There's no denying that the "Action Pattern" in the Laravel ecosystem is extremely useful and widely used. However, action classes require "too much content" to do basic things. Let's review a basic action class:
 4 | 
 5 | ```php
 6 | namespace App\Actions;
 7 | 
 8 | use App\Models\User;
 9 | 
10 | class CreateUser
11 | {
12 |     public function handle(array $data): User
13 |     {
14 |         return User::create($data);
15 |     }
16 | }
17 | ```
18 | 
19 | We have a namespace, class, method... **All of this to create a user?** It's overkill for such a simple task, isn't it?
20 | 
21 | For this reason, the _Fraction_ solution is revolutionary in the context of Actions. _Fraction_ allows you to write actions in a _simpler and more direct way_, without the need for all this structure, **similar to what _PestPHP_ proposes.**
22 | 
23 | ---
24 | 
25 | ## Documentation
26 | 
27 | Now that I've made you curious about what _Fraction_ does 😉 [check out the official website by clicking here](https://fractionforlaravel.com/). There you'll find a complete explanation of the package, as well as understanding what it really offers along with its many benefits.
28 | 


--------------------------------------------------------------------------------
/src/Handlers/AsSync.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | 
 3 | declare(strict_types=1);
 4 | 
 5 | namespace Fraction\Handlers;
 6 | 
 7 | use Fraction\Configurable\RescuedUsing;
 8 | use Fraction\Contracts\Configurable;
 9 | use Fraction\Contracts\ShouldInterpreter;
10 | use Fraction\Handlers\Concerns\ShareableInterpreter;
11 | use Illuminate\Container\Container;
12 | 
13 | final class AsSync implements Configurable, ShouldInterpreter
14 | {
15 |     use ShareableInterpreter;
16 | 
17 |     /**
18 |      * Execute the action rescued.
19 |      */
20 |     public ?RescuedUsing $rescued = null;
21 | 
22 |     public function handle(Container $container): mixed
23 |     {
24 |         $resolve = $this->dependencies($container)->resolve(...);
25 | 
26 |         $result = match (true) {
27 |             $this->rescued !== null => rescue(fn () => $resolve($this->closure, $this->arguments), $this->rescued->default),
28 |             default                 => $resolve($this->closure, $this->arguments),
29 |         };
30 | 
31 |         $this->hooks();
32 | 
33 |         return $result;
34 |     }
35 | 
36 |     public function configure(array $data): void
37 |     {
38 |         $this->rescued = new RescuedUsing(...$data);
39 |     }
40 | }
41 | 


--------------------------------------------------------------------------------
/src/Jobs/FractionJob.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | 
 3 | declare(strict_types=1);
 4 | 
 5 | namespace Fraction\Jobs;
 6 | 
 7 | use Fraction\Exceptions\DependencyUnresolvable;
 8 | use Fraction\Support\DependencyResolver;
 9 | use Fraction\ValueObjects\Then;
10 | use Illuminate\Container\Container;
11 | use Illuminate\Contracts\Container\BindingResolutionException;
12 | use Illuminate\Contracts\Queue\ShouldQueue;
13 | use Illuminate\Foundation\Queue\Queueable;
14 | use Laravel\SerializableClosure\SerializableClosure;
15 | use ReflectionException;
16 | 
17 | final class FractionJob implements ShouldQueue
18 | {
19 |     use Queueable;
20 | 
21 |     public function __construct(
22 |         protected string $action,
23 |         protected array $arguments,
24 |         protected SerializableClosure $closure,
25 |         public array $then = [],
26 |     ) {
27 |         // ...
28 |     }
29 | 
30 |     /**
31 |      * Handle the job.
32 |      *
33 |      * @throws ReflectionException|BindingResolutionException|DependencyUnresolvable
34 |      */
35 |     public function handle(Container $application): void
36 |     {
37 |         $application->make(DependencyResolver::class, [
38 |             'action' => $this->action,
39 |         ])->resolve($this->closure, $this->arguments);
40 | 
41 |         if ($this->then === []) {
42 |             return;
43 |         }
44 | 
45 |         /** @var Then $hook */
46 |         foreach ($this->then as $hook) {
47 |             run($hook->then, ...$this->arguments);
48 |         }
49 |     }
50 | }
51 | 


--------------------------------------------------------------------------------
/src/Handlers/Concerns/ShareableInterpreter.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | 
 3 | declare(strict_types=1);
 4 | 
 5 | namespace Fraction\Handlers\Concerns;
 6 | 
 7 | use Fraction\Support\DependencyResolver;
 8 | use Fraction\ValueObjects\Then;
 9 | use Illuminate\Container\Container;
10 | use Laravel\SerializableClosure\SerializableClosure;
11 | 
12 | trait ShareableInterpreter
13 | {
14 |     /**
15 |      * The array of "then" hooks.
16 |      */
17 |     public array $then = [];
18 | 
19 |     public function __construct(
20 |         public string $action,
21 |         public array $arguments,
22 |         public SerializableClosure $closure,
23 |     ) {
24 |         // ...
25 |     }
26 | 
27 |     /**
28 |      * Resolve the dependencies for the action.
29 |      */
30 |     final public function dependencies(Container $container): DependencyResolver
31 |     {
32 |         return $container->make(DependencyResolver::class, [
33 |             'action'      => $this->action,
34 |             'application' => $container,
35 |         ]);
36 |     }
37 | 
38 |     /** {@inheritDoc} */
39 |     final public function then(array $then): self
40 |     {
41 |         $this->then = $then;
42 | 
43 |         return $this;
44 |     }
45 | 
46 |     /**
47 |      * Run the hooks after the action is handled.
48 |      */
49 |     final public function hooks(): void
50 |     {
51 |         if ($this->then === []) {
52 |             return;
53 |         }
54 | 
55 |         /** @var Then $hook */
56 |         foreach ($this->then as $hook) {
57 |             run($hook->then, ...$this->arguments);
58 |         }
59 |     }
60 | }
61 | 


--------------------------------------------------------------------------------
/src/FractionManager.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | 
 3 | declare(strict_types=1);
 4 | 
 5 | namespace Fraction;
 6 | 
 7 | use Closure;
 8 | use Fraction\Exceptions\ActionNotRegistered;
 9 | use Fraction\Exceptions\UnallowedActionDuplication;
10 | use Fraction\Support\Bootable;
11 | use Fraction\Support\FractionName;
12 | use Illuminate\Foundation\Application;
13 | use UnitEnum;
14 | 
15 | final class FractionManager
16 | {
17 |     /**
18 |      * The array of registered fractions.
19 |      *
20 |      * @var array<string, FractionBuilder>
21 |      */
22 |     private array $fractions = [];
23 | 
24 |     public function __construct(public Application $application)
25 |     {
26 |         //
27 |     }
28 | 
29 |     /**
30 |      * Register a new action.
31 |      *
32 |      * @throws UnallowedActionDuplication
33 |      */
34 |     public function register(string|UnitEnum $action, Closure $closure): FractionBuilder
35 |     {
36 |         $original = $action;
37 | 
38 |         $action = FractionName::format($action);
39 | 
40 |         if (isset($this->fractions[$action])) {
41 |             throw new UnallowedActionDuplication($original);
42 |         }
43 | 
44 |         $builder = new FractionBuilder($this->application, $original, $closure);
45 | 
46 |         $this->fractions[$action] = $builder;
47 | 
48 |         return $builder;
49 |     }
50 | 
51 |     /**
52 |      * Get the action by its name.
53 |      *
54 |      * @throws ActionNotRegistered
55 |      */
56 |     public function get(string|UnitEnum $action): FractionBuilder
57 |     {
58 |         $original = $action;
59 | 
60 |         $action = FractionName::format($action);
61 | 
62 |         return $this->fractions[$action] ?? throw new ActionNotRegistered($original);
63 |     }
64 | 
65 |     /**
66 |      * Get all registered actions.
67 |      */
68 |     public function all(): array
69 |     {
70 |         return $this->fractions;
71 |     }
72 | 
73 |     /**
74 |      * Bootstrap the actions.
75 |      */
76 |     public function boot(): void
77 |     {
78 |         Bootable::fire();
79 |     }
80 | }
81 | 


--------------------------------------------------------------------------------
/composer.json:
--------------------------------------------------------------------------------
 1 | {
 2 |     "name": "fraction/fraction",
 3 |     "description": "New way to interact with the Laravel Action pattern.",
 4 |     "type": "library",
 5 |     "license": "MIT",
 6 |     "autoload": {
 7 |         "psr-4": {
 8 |             "Fraction\\": "src/"
 9 |         },
10 |         "files": [
11 |             "src/helpers.php"
12 |         ]
13 |     },
14 |     "autoload-dev": {
15 |         "psr-4": {
16 |             "Tests\\": "tests/"
17 |         }
18 |     },
19 |     "authors": [
20 |         {
21 |             "name": "AJ Meireles",
22 |             "email": "alvaro.meireles@live.com"
23 |         }
24 |     ],
25 |     "require": {
26 |         "php": "^8.2",
27 |         "laravel/framework": "^11.0|^12.0"
28 |     },
29 |     "require-dev": {
30 |         "pestphp/pest": "^3.0",
31 |         "pestphp/pest-plugin-type-coverage": "^3.0",
32 |         "larastan/larastan": "^3.0",
33 |         "laravel/pint": "^1.0",
34 |         "orchestra/testbench": "^9.0",
35 |         "rector/rector": "^2.0",
36 |         "timacdonald/log-fake": "^2.4"
37 |     },
38 |     "extra": {
39 |         "laravel": {
40 |             "providers": [
41 |                 "Fraction\\FractionServiceProvider"
42 |             ],
43 |             "aliases": {
44 |                 "Fraction": "Fraction\\Facades\\Fraction"
45 |             }
46 |         }
47 |     },
48 |     "scripts": {
49 |         "coverage": [
50 |             "rm -fr coverage/",
51 |             "./vendor/bin/pest --parallel --coverage --coverage-html=coverage"
52 |         ],
53 |         "test": [
54 |             "./vendor/bin/pest --parallel"
55 |         ],
56 |         "format": [
57 |             "./vendor/bin/pint"
58 |         ],
59 |         "analyse": [
60 |             "./vendor/bin/phpstan analyse --memory-limit=2G"
61 |         ],
62 |         "rector": [
63 |             "vendor/bin/rector process --dry-run"
64 |         ],
65 |         "ci": [
66 |             "./vendor/bin/pint --test",
67 |             "./vendor/bin/phpstan analyse --memory-limit=2G",
68 |             "./vendor/bin/pest --parallel --coverage --min=85"
69 |         ]
70 |     },
71 |     "minimum-stability": "dev",
72 |     "prefer-stable": true,
73 |     "config": {
74 |         "allow-plugins": {
75 |             "pestphp/pest-plugin": true
76 |         }
77 |     }
78 | }
79 | 


--------------------------------------------------------------------------------
/src/Console/MakeActionCommand.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | 
 3 | declare(strict_types=1);
 4 | 
 5 | namespace Fraction\Console;
 6 | 
 7 | use Illuminate\Console\GeneratorCommand;
 8 | use Illuminate\Support\Str;
 9 | use Symfony\Component\Console\Attribute\AsCommand;
10 | use Symfony\Component\Console\Input\InputArgument;
11 | 
12 | /** @codeCoverageIgnore */
13 | #[AsCommand(name: 'make:action')]
14 | class MakeActionCommand extends GeneratorCommand
15 | {
16 |     /**
17 |      * The name and signature of the console command.
18 |      *
19 |      * @var string
20 |      */
21 |     protected $name = 'make:action';
22 | 
23 |     /**
24 |      * The console command description.
25 |      *
26 |      * @var string
27 |      */
28 |     protected $description = 'Create a new action file.';
29 | 
30 |     /**
31 |      * The type of class being generated.
32 |      *
33 |      * @var string
34 |      */
35 |     protected $type = 'Action';
36 | 
37 |     protected function getStub(): string
38 |     {
39 |         return __DIR__.'/../stubs/action.stub';
40 |     }
41 | 
42 |     // The reason why publishing this method is to ensure the
43 |     // action will be created in the correct path fraction.path
44 |     protected function getPath($name): string // @pest-ignore-type
45 |     {
46 |         $path = config('fraction.path');
47 | 
48 |         if (empty($path)) {
49 |             $path = $this->laravel['path'].'/Actions';
50 |         }
51 | 
52 |         $this->files->ensureDirectoryExists($path);
53 | 
54 |         $name = Str::of($name)
55 |             ->afterLast('App\\')
56 |             ->value();
57 | 
58 |         return $path.'/'.str_replace('\\', '/', $name).'.php';
59 |     }
60 | 
61 |     // The reason why publishing this method is to ensure override the {{ name }}
62 |     // placeholder in the stub file with the formatted name of the action
63 |     protected function buildClass($name): string // @pest-ignore-type
64 |     {
65 |         $stub = $this->files->get($this->getStub());
66 | 
67 |         $formatted = Str::of($this->getNameInput())
68 |             ->afterLast('\\')
69 |             ->headline()
70 |             ->lower()
71 |             ->snake(' ')
72 |             ->value();
73 | 
74 |         return str_replace('{{ name }}', $formatted, $stub);
75 |     }
76 | 
77 |     protected function promptForMissingArgumentsUsing(): array
78 |     {
79 |         return [
80 |             'name' => [
81 |                 'What should the action be named?',
82 |                 'E.g. CreateUserAction',
83 |             ],
84 |         ];
85 |     }
86 | 
87 |     protected function getArguments(): array
88 |     {
89 |         return [
90 |             ['name', InputArgument::REQUIRED, 'The name of the action'],
91 |         ];
92 |     }
93 | }
94 | 


--------------------------------------------------------------------------------
/src/Support/DependencyResolver.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | 
 3 | declare(strict_types=1);
 4 | 
 5 | namespace Fraction\Support;
 6 | 
 7 | use Closure;
 8 | use Fraction\Exceptions\DependencyUnresolvable;
 9 | use Illuminate\Contracts\Container\BindingResolutionException;
10 | use Illuminate\Foundation\Application;
11 | use Laravel\SerializableClosure\SerializableClosure;
12 | use ReflectionException;
13 | use ReflectionFunction;
14 | use ReflectionNamedType;
15 | use ReflectionParameter;
16 | 
17 | /** @internal */
18 | final readonly class DependencyResolver
19 | {
20 |     public function __construct(
21 |         private string $action,
22 |         private Application $application,
23 |     ) {
24 |         //
25 |     }
26 | 
27 |     /**
28 |      * Resolve the dependencies of a closure or serializable closure.
29 |      *
30 |      * @throws ReflectionException|BindingResolutionException|DependencyUnresolvable
31 |      */
32 |     public function resolve(Closure|SerializableClosure $closure, array $arguments = []): mixed
33 |     {
34 |         $closure = $closure instanceof SerializableClosure
35 |             ? $closure->getClosure()
36 |             : $closure;
37 | 
38 |         $reflection = new ReflectionFunction($closure);
39 | 
40 |         $parameters = $reflection->getParameters();
41 |         $resolved   = [];
42 | 
43 |         foreach ($parameters as $index => $parameter) {
44 |             if (array_key_exists($index, $arguments)) {
45 |                 $resolved[] = $arguments[$index];
46 | 
47 |                 continue;
48 |             }
49 | 
50 |             foreach ($parameter->getAttributes() as $attribute) {
51 |                 if (! str_contains($attribute->getName(), 'Illuminate\Container\Attributes')) {
52 |                     continue;
53 |                 }
54 | 
55 |                 $instance = $attribute->newInstance();
56 | 
57 |                 if (! method_exists($instance, 'resolve')) {
58 |                     continue;
59 |                 }
60 | 
61 |                 $resolved[] = $instance->resolve($instance, $this->application);
62 |             }
63 | 
64 |             /** @var ReflectionParameter|ReflectionNamedType $type */
65 |             $type = $parameter->getType();
66 | 
67 |             if ($type && (method_exists($type, 'isBuiltin') && ! $type->isBuiltin())) {
68 |                 $resolved[] = $this->application->make($type->getName());
69 |             } elseif ($parameter->isDefaultValueAvailable()) {
70 |                 $resolved[] = $parameter->getDefaultValue();
71 |             } else {
72 |                 throw new DependencyUnresolvable($parameter->getName(), $this->action);
73 |             }
74 |         }
75 | 
76 |         return call_user_func_array($closure, $resolved);
77 |     }
78 | }
79 | 


--------------------------------------------------------------------------------
/src/Console/UnregisteredActionsCommand.php:
--------------------------------------------------------------------------------
  1 | <?php
  2 | 
  3 | declare(strict_types=1);
  4 | 
  5 | namespace Fraction\Console;
  6 | 
  7 | use Exception;
  8 | use Fraction\Facades\Fraction;
  9 | use Illuminate\Console\Command;
 10 | use Symfony\Component\Process\Exception\ProcessFailedException;
 11 | use Symfony\Component\Process\Process;
 12 | 
 13 | use function Laravel\Prompts\table;
 14 | 
 15 | /** @codeCoverageIgnore */
 16 | class UnregisteredActionsCommand extends Command
 17 | {
 18 |     /**
 19 |      * The name and signature of the console command.
 20 |      *
 21 |      * @var string
 22 |      */
 23 |     protected $name = 'actions:unregistered';
 24 | 
 25 |     /**
 26 |      * The console command description.
 27 |      *
 28 |      * @var string
 29 |      */
 30 |     protected $description = 'List of actions used without being registered.';
 31 | 
 32 |     /**
 33 |      * Execute the console command.
 34 |      */
 35 |     public function handle(): int
 36 |     {
 37 |         $find = 'run(';
 38 | 
 39 |         $windows = windows_os();
 40 | 
 41 |         $command = $windows
 42 |             ? ['findstr', '/S', '/N', '/I', $find, base_path('app').'\*.php']
 43 |             : ['grep', '-rn', $find, base_path('app'), '--include=*.php'];
 44 | 
 45 |         $process = new Process($command);
 46 | 
 47 |         try {
 48 |             $process->mustRun();
 49 | 
 50 |             return $this->output($process->getOutput());
 51 |         } catch (ProcessFailedException) {
 52 |             $this->components->error('No unregistered actions found in the codebase.');
 53 | 
 54 |             return self::SUCCESS;
 55 |         } catch (Exception $exception) {
 56 |             $this->components->error('Unexpected Error: '.$exception->getMessage());
 57 | 
 58 |             return self::FAILURE;
 59 |         }
 60 |     }
 61 | 
 62 |     /**
 63 |      * Output the results of the search.
 64 |      */
 65 |     private function output(string $output): int
 66 |     {
 67 |         if (blank($output)) {
 68 |             return self::SUCCESS;
 69 |         }
 70 | 
 71 |         $rows = [];
 72 | 
 73 |         $lines = collect(explode(PHP_EOL, $output))->filter();
 74 | 
 75 |         if ($lines->count() === 0) {
 76 |             $this->components->info('No unregistered actions found.');
 77 | 
 78 |             return self::SUCCESS;
 79 |         }
 80 | 
 81 |         $actions = collect(Fraction::all())->groupBy('action')->keys()->flip();
 82 | 
 83 |         $lines->lazy()->each(function (string $line) use (&$rows, $actions): bool {
 84 |             preg_match("/^(\/[^\s:]+):\d+:\s*.*?run\(\s*'([^']+)'\s*\)/", $line, $matches);
 85 | 
 86 |             if (blank($line) || count($matches) < 3 || $actions->has($matches[2])) {
 87 |                 return false;
 88 |             }
 89 | 
 90 |             $path = str($matches[0])
 91 |                 ->afterLast(base_path())
 92 |                 ->beforeLast(':')
 93 |                 ->replaceFirst('/', '')
 94 |                 ->value();
 95 | 
 96 |             $rows[] = [$path, $matches[2]];
 97 | 
 98 |             return true;
 99 |         });
100 | 
101 |         if ($rows === []) {
102 |             $this->components->info('No unregistered actions found.');
103 | 
104 |             return self::SUCCESS;
105 |         } else {
106 |             $this->components->warn('Unregistered actions found:');
107 |         }
108 | 
109 |         table(['File', 'Unregistered Action'], $rows);
110 | 
111 |         return self::FAILURE;
112 |     }
113 | }
114 | 


--------------------------------------------------------------------------------
/src/FractionBuilder.php:
--------------------------------------------------------------------------------
  1 | <?php
  2 | 
  3 | declare(strict_types=1);
  4 | 
  5 | namespace Fraction;
  6 | 
  7 | use Closure;
  8 | use Fraction\Configurable\DeferUsing;
  9 | use Fraction\Configurable\QueueUsing;
 10 | use Fraction\Contracts\Configurable;
 11 | use Fraction\Contracts\ShouldInterpreter;
 12 | use Fraction\Exceptions\PreventDeferQueueSameTime;
 13 | use Fraction\Handlers\AsDefer;
 14 | use Fraction\Handlers\AsQueue;
 15 | use Fraction\Handlers\AsSync;
 16 | use Illuminate\Contracts\Container\BindingResolutionException;
 17 | use Illuminate\Contracts\Support\Arrayable;
 18 | use Illuminate\Foundation\Application;
 19 | use InvalidArgumentException;
 20 | use Laravel\SerializableClosure\SerializableClosure;
 21 | use UnitEnum;
 22 | 
 23 | final class FractionBuilder implements Arrayable
 24 | {
 25 |     use Concerns\UsingDefer;
 26 |     use Concerns\UsingLogged;
 27 |     use Concerns\UsingQueue;
 28 |     use Concerns\UsingRescue;
 29 |     use Concerns\UsingThen;
 30 | 
 31 |     public function __construct(
 32 |         public Application $application,
 33 |         public string|UnitEnum $action,
 34 |         public Closure $closure
 35 |     ) {
 36 |         $this->action = $this->action instanceof UnitEnum
 37 |             ? $this->action->name
 38 |             : $this->action;
 39 |     }
 40 | 
 41 |     /**
 42 |      * Run the action.
 43 |      *
 44 |      * @throws BindingResolutionException|InvalidArgumentException|PreventDeferQueueSameTime
 45 |      */
 46 |     public function __invoke(...$arguments): mixed
 47 |     {
 48 |         $arguments = $this->ignores($arguments);
 49 | 
 50 |         if ($this->queued !== null && $this->deferred !== null) {
 51 |             throw new PreventDeferQueueSameTime($this->action);
 52 |         }
 53 | 
 54 |         $interpret = match (true) {
 55 |             $this->queued instanceof QueueUsing   => AsQueue::class,
 56 |             $this->deferred instanceof DeferUsing => AsDefer::class,
 57 |             default                               => AsSync::class,
 58 |         };
 59 | 
 60 |         /** @var ShouldInterpreter|Configurable $interpreter */
 61 |         $interpreter = $this->application->make($interpret, [
 62 |             'action'    => $this->action,
 63 |             'arguments' => $arguments,
 64 |             'closure'   => new SerializableClosure($this->closure),
 65 |         ]);
 66 | 
 67 |         if ([$has, $configuration] = $this->configuration()) {
 68 |             if ($has) {
 69 |                 $interpreter->configure($configuration);
 70 |             }
 71 |         }
 72 | 
 73 |         $result = $interpreter->then($this->then ?? [])->handle($this->application);
 74 | 
 75 |         if ($this->logged !== null) {
 76 |             $this->application->make('log')
 77 |                 ->channel($this->logged->channel)
 78 |                 ->info(__($this->logged->message, [
 79 |                     'name'   => config('app.name'),
 80 |                     'action' => $this->action,
 81 |                 ]));
 82 |         }
 83 | 
 84 |         return $result;
 85 |     }
 86 | 
 87 |     /** {@inheritDoc} */
 88 |     public function toArray(): array
 89 |     {
 90 |         return [
 91 |             'action'   => $this->action,
 92 |             'closure'  => $this->closure,
 93 |             'then'     => $this->then,
 94 |             'queued'   => $this->queued,
 95 |             'deferred' => $this->deferred,
 96 |             'rescued'  => $this->rescued,
 97 |         ];
 98 |     }
 99 | 
100 |     /**
101 |      * Determines which configurable should be applied.
102 |      */
103 |     private function configuration(): array
104 |     {
105 |         foreach ([
106 |             $this->queued,
107 |             $this->deferred,
108 |             $this->rescued,
109 |         ] as $instance) {
110 |             if ($instance !== null) {
111 |                 return [true, $instance->toArray()];
112 |             }
113 |         }
114 | 
115 |         return [false, []];
116 |     }
117 | 
118 |     /**
119 |      * Determines if helpers usage should be ignored.
120 |      */
121 |     private function ignores(array $arguments = []): array
122 |     {
123 |         if ($arguments === []) {
124 |             return $arguments;
125 |         }
126 | 
127 |         $helpers = ['queued', 'deferred', 'rescued', 'logged', 'then'];
128 |         $unset   = array_intersect($helpers, array_keys($arguments));
129 | 
130 |         foreach ($unset as $helper) {
131 |             if ($arguments[$helper] === false) {
132 |                 $this->{$helper} = null;
133 |             }
134 | 
135 |             unset($arguments[$helper]);
136 |         }
137 | 
138 |         return $arguments;
139 |     }
140 | }
141 | 


--------------------------------------------------------------------------------