Merge pull request #4 from kirschbaum-development/rework

Pretty big rework

Author: brandonferens

README.md

@@ -21,7 +21,7 @@ The special sauce here is that you get to tell the Action which events you want
 
 ## Requirements
 
-This package requires Laravel 6.0 or higher.
+This package requires Laravel 6.0 or higher and PHP 7.2.5 or higher.
 
 ## Installation
 
@@ -106,9 +106,9 @@ The package also has a facade. Here's the syntax:
 ```php
 use Kirschbaum\Actions\Facades\Action;
 
-Action::act(new ChuckNorris($data));
-Action::actWhen($isChuckNorrisMighty, new ChuckNorris($data));
-Action::actUnless($isChuckNorrisPuny, new ChuckNorris($data));
+Action::act(ChuckNorris::class, $data);
+Action::actWhen($isChuckNorrisMighty, ChuckNorris::class, $data);
+Action::actUnless($isChuckNorrisPuny, ChuckNorris::class, $data);
 ```
 
 The usage is nearly identical to calling the methods directly on the Action as mentioned in the section above. The benefit here is that you can easily test actions using `Action::shouldReceive('act')`, `Action::shouldReceive('actWhen')` or `Action::shouldReceive('actUnless')`.
@@ -118,23 +118,23 @@ The usage is nearly identical to calling the methods directly on the Action as m
 The package also has a few handy helpers to get Chuck in action. Here's the syntax:
 
 ```php
-act(new ChuckNorris($data));
-act_when($isChuckNorrisMighty, new ChuckNorris($data));
-act_unless($isChuckNorrisPuny, new ChuckNorris($data));
+act(ChuckNorris::class, $data);
+act_when($isChuckNorrisMighty, ChuckNorris::class, $data);
+act_unless($isChuckNorrisPuny, ChuckNorris::class, $data);
 ```
 
 ### Dependency Injection
 
 You can even inject Actions as a dependencies inside your application!
 
 ```php
-use Kirschbaum\Actions\Contracts\Actionable;
+use Kirschbaum\Actions\Action;
 
-public function index (Actionable $action)
+public function index (Action $action)
 {
-    $action->act(new ChuckNorris($data));
-    $action->actWhen($isChuckNorrisMighty, new ChuckNorris($data));
-    $action->actUnless($isChuckNorrisPuny, new ChuckNorris($data));
+    $action->act(ChuckNorris::class, $data);
+    $action->actWhen($isChuckNorrisMighty, ChuckNorris::class, $data);
+    $action->actUnless($isChuckNorrisPuny, ChuckNorris::class, $data);
 }
 ```
 
@@ -171,6 +171,22 @@ Another option for handling failures is to tell the Action to throw its own exce
 public $exception = SeagalFailedException::class;
 ```
 
+## Auto-Discovery and Configuration
+
+Out of the box, actions are automatically discovered and bound to Laravel's container, which allows for easier testing of your actions. If you need to add a custom path if you are placing your actions somewhere other than `app/Actions`, make sure to publish the configs.
+
+```bash
+php artisan vendor:publish --tag laravel-actions
+```
+
+If you want to disable auto-discovery, publish the config and return an empty array from the `paths` key.
+
+```php
+return [
+    'paths' => [],
+];
+```
+
 ## Testing
 
 Have no fear. Testing all of this is very straightforward. There are two approaches to testing built in.
@@ -189,12 +205,24 @@ Action::shouldReceive('act')
 
 ### Mocking
 
-If you are using helpers, the `CanAct` trait, or dependency injection, you can easily mock the `Actionable` interface with Laravel's mocking tools.
+If you are using helpers, the `CanAct` trait, or dependency injection, you can easily mock the `Action` class with Laravel's mocking tools.
+
+```php
+use Kirschbaum\Actions\Action;
+
+$this->mock(Action::class, function ($mock) {
+    $mock->shouldReceive('act')
+        ->once()
+        ->andReturnTrue();
+});
+```
+
+Because actions are bound into Laravel's container by default, you can test specific actions as well.
 
 ```php
-use Kirschbaum\Actions\Contracts\Actionable;
+use App\Actions\ChuckNorris;
 
-$this->mock(Actionable::class, function ($mock) {
+$this->mock(ChuckNorris::class, function ($mock) {
     $mock->shouldReceive('act')
         ->once()
         ->andReturnTrue();

config/laravel-actions.php

@@ -0,0 +1,16 @@
+<?php
+
+return [
+    /*
+    |--------------------------------------------------------------------------
+    | Auto-discovery Action Paths
+    |--------------------------------------------------------------------------
+    |
+    | The paths for auto-discovering actions classes. Each path must be a full path to
+    | a directory within your Laravel application. If you would rather disable this
+    | cool feature and/or bind them yourself, just return an empty array instead.
+    */
+    'paths' => [
+        app_path('Actions'),
+    ],
+];

src/Action.php

@@ -3,68 +3,89 @@
 namespace Kirschbaum\Actions;
 
 use Throwable;
-use Illuminate\Support\Arr;
 use Kirschbaum\Actions\Contracts\Actionable;
+use Kirschbaum\Actions\Exceptions\ActionableInterfaceNotFoundException;
 
 class Action
 {
+    /**
+     * Arguments to pass into the action's constructor.
+     *
+     * @var array
+     */
+    protected $arguments;
+
     /**
      * Initiate the given action.
      *
-     * @param Actionable $action
+     * @param string $action
+     * @param mixed ...$arguments
      *
      * @throws Throwable
      *
-     * @return mixed|void
+     * @return mixed
      */
-    public function act(Actionable $action)
+    public function act(string $action, ...$arguments)
     {
+        $this->arguments = $arguments;
+
         return $this->handle($action);
     }
 
     /**
      * Initiate the given action if the given condition is true.
      *
      * @param $condition
-     * @param Actionable $action
+     * @param string $action
+     * @param mixed ...$arguments
      *
      * @throws Throwable
      *
      * @return mixed|void
      */
-    public function actWhen($condition, Actionable $action)
+    public function actWhen($condition, string $action, ...$arguments)
     {
         if ($condition) {
-            return $this->act($action);
+            $this->arguments = $arguments;
+
+            return $this->handle($action);
         }
     }
 
     /**
      * Initiate the action if the given condition is false.
      *
      * @param $condition
-     * @param Actionable $action
+     * @param string $action
+     * @param mixed ...$arguments
      *
      * @throws Throwable
      *
      * @return mixed|void
      */
-    public function actUnless($condition, Actionable $action)
+    public function actUnless($condition, string $action, ...$arguments)
     {
-        return $this->actWhen(! $condition, $action);
+        if (! $condition) {
+            $this->arguments = array_slice(func_get_args(), 2);
+
+            return $this->handle($action);
+        }
     }
 
     /**
      * Handle the given action.
      *
-     * @param Actionable $action
+     * @param string $action
      *
      * @throws Throwable
      *
      * @return mixed|void
      */
-    protected function handle(Actionable $action)
+    protected function handle(string $action)
     {
+        $action = new $action(...$this->arguments);
+
+        $this->checkActionForInterface($action);
         $this->raiseBeforeActionEvent($action);
 
         try {
@@ -90,20 +111,27 @@ protected function actionHasFailedMethod(Actionable $action): bool
         return method_exists($action, 'failed');
     }
 
+    protected function checkActionForInterface($action): void
+    {
+        throw_unless(
+            $action instanceof Actionable,
+            ActionableInterfaceNotFoundException::class
+        );
+    }
+
     /**
      * Dispatch appropriate action event.
      *
      * @param string $event
      * @param Actionable $action
-     * @param Throwable|null $exception
      *
      * @return void
      */
-    protected function dispatchEvent(string $event, Actionable $action, ?Throwable $exception = null): void
+    protected function dispatchEvent(string $event, Actionable $action): void
     {
         if ($this->eventExists($action, $event)) {
             // Gather method arguments except for the `$event` argument.
-            $arguments = Arr::except(func_get_args(), 0);
+            $arguments = array_slice(func_get_args(), 1);
 
             event(new $action->{$event}(...$arguments));
         }

src/ActionsServiceProvider.php

@@ -2,6 +2,10 @@
 
 namespace Kirschbaum\Actions;
 
+use ReflectionClass;
+use ReflectionException;
+use Illuminate\Support\Str;
+use Symfony\Component\Finder\Finder;
 use Illuminate\Support\ServiceProvider;
 use Kirschbaum\Actions\Contracts\Actionable;
 use Kirschbaum\Actions\Commands\MakeActionCommand;
@@ -15,15 +19,88 @@ class ActionsServiceProvider extends ServiceProvider
      */
     public $bindings = [
         'actions' => Action::class,
-        Actionable::class => Action::class,
+        Action::class => Action::class,
     ];
 
+    /**
+     * Register any application services.
+     *
+     * @return void
+     */
+    public function register(): void
+    {
+        $this->registerMergeConfig();
+    }
+
     /**
      * Bootstrap any package services.
      *
+     * @throws ReflectionException
+     *
      * @return void
      */
-    public function boot()
+    public function boot(): void
+    {
+        $this->bootConsoleCommands();
+
+        $this->bootPublishConfig();
+
+        $this->bootAutoDiscoverActions();
+    }
+
+    /**
+     * Get the services provided by the provider.
+     *
+     * @return array
+     */
+    public function provides(): array
+    {
+        return [Action::class];
+    }
+
+    /**
+     * Auto-discover actions classes.
+     *
+     * @throws ReflectionException
+     *
+     * @return void
+     */
+    protected function bootAutoDiscoverActions(): void
+    {
+        $paths = collect(config('laravel-actions.paths'))
+            ->unique()
+            ->filter(function ($path) {
+                return is_dir($path);
+            });
+
+        if ($paths->isEmpty()) {
+            return;
+        }
+
+        $namespace = $this->app->getNamespace();
+
+        foreach ((new Finder())->in($paths->toArray())->files() as $action) {
+            $action = $namespace . str_replace(
+                ['/', '.php'],
+                ['\\', ''],
+                Str::after($action->getRealPath(), realpath(app_path()) . DIRECTORY_SEPARATOR)
+            );
+
+            if (
+                is_subclass_of($action, Actionable::class)
+                && ! (new ReflectionClass($action))->isAbstract()
+            ) {
+                $this->app->bind($action, Action::class);
+            }
+        }
+    }
+
+    /**
+     * Load console commands for actions.
+     *
+     * @return void
+     */
+    protected function bootConsoleCommands(): void
     {
         if ($this->app->runningInConsole()) {
             $this->commands([
@@ -33,12 +110,27 @@ public function boot()
     }
 
     /**
-     * Get the services provided by the provider.
+     * Publish action configuration file.
      *
-     * @return array
+     * @return void
      */
-    public function provides(): array
+    protected function bootPublishConfig(): void
     {
-        return [Action::class];
+        $this->publishes([
+            __DIR__ . '/../config/laravel-actions.php' => config_path('laravel-actions.php'),
+        ], 'laravel-actions');
+    }
+
+    /**
+     * Register merging of configuration file.
+     *
+     * @return void
+     */
+    protected function registerMergeConfig(): void
+    {
+        $this->mergeConfigFrom(
+            __DIR__ . '/../config/laravel-actions.php',
+            'laravel-actions'
+        );
     }
 }

src/Exceptions/ActionableInterfaceNotFoundException.php

@@ -0,0 +1,9 @@
+<?php
+
+namespace Kirschbaum\Actions\Exceptions;
+
+use Exception;
+
+class ActionableInterfaceNotFoundException extends Exception
+{
+}