Macroable, pint and github action updates

Author: brandonferens

.github/workflows/ci.yml

@@ -0,0 +1,119 @@
+on: push
+name: CI
+
+jobs:
+  phpunit:
+    runs-on: ubuntu-24.04
+    timeout-minutes: 5
+
+    strategy:
+      fail-fast: true
+      matrix:
+        php: [ 8.1, 8.2, 8.3, 8.4 ]
+        laravel: [ 10.*, 11.*, 12.* ]
+        include:
+          - php: 8.1
+            laravel: 10.*
+            pest: 2.*
+            testbench: 8.*
+          - php: 8.2
+            laravel: 10.*
+            pest: 2.*
+            testbench: 8.*
+          - php: 8.3
+            laravel: 10.*
+            pest: 2.*
+            testbench: 8.*
+          - php: 8.4
+            laravel: 10.*
+            pest: 2.*
+            testbench: 8.*
+          - php: 8.2
+            laravel: 11.*
+            pest: 3.*
+            testbench: 9.*
+          - php: 8.3
+            laravel: 11.*
+            pest: 3.*
+            testbench: 9.*
+          - php: 8.4
+            laravel: 11.*
+            pest: 3.*
+            testbench: 9.*
+          - php: 8.2
+            laravel: 12.*
+            pest: 3.*
+            testbench: 10.*
+          - php: 8.3
+            laravel: 12.*
+            pest: 3.*
+            testbench: 10.*
+          - php: 8.4
+            laravel: 12.*
+            pest: 3.*
+            testbench: 10.*
+        exclude:
+          - php: 8.1
+            laravel: 11.*
+          - php: 8.1
+            laravel: 12.*
+
+    name: Laravel Actions Tests - PHP ${{ matrix.php }} - Laravel ${{ matrix.laravel }}
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Cache dependencies
+        uses: actions/cache@v4
+        with:
+          path: ~/.composer/cache/files
+          key: dependencies-${{ matrix.laravel }}-php-${{ matrix.php }}-composer-${{ hashFiles('composer.json') }}
+
+      - name: Setup PHP
+        uses: shivammathur/setup-php@v2
+        with:
+          php-version: ${{ matrix.php }}
+          extensions: curl, mbstring, zip, pcntl, iconv
+          coverage: none
+          tools: composer:v2
+
+      - name: Install dependencies
+        run: |
+          composer require "laravel/framework:${{ matrix.laravel }}" --no-interaction --no-update
+          composer require "orchestra/testbench:${{ matrix.testbench }}" --no-interaction --no-update
+          composer require "pestphp/pest:${{ matrix.pest }}" "pestphp/pest-plugin-laravel:${{ matrix.pest }}" "pestphp/pest-plugin-type-coverage:${{ matrix.pest }}" --no-interaction --no-update
+          composer update --prefer-dist --no-interaction
+          composer dump
+
+      - name: Execute tests
+        run: vendor/bin/phpunit tests/
+
+  pint:
+    runs-on: ubuntu-24.04
+    timeout-minutes: 5
+
+    name: Pint Style Check
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Cache dependencies
+        uses: actions/cache@v4
+        with:
+          path: ~/.composer/cache/files
+          key: dependencies-composer-${{ hashFiles('composer.json') }}
+
+      - name: Setup PHP
+        uses: shivammathur/setup-php@v2
+        with:
+          php-version: 8.3
+          tools: composer:v2
+
+      - name: Install dependencies
+        run: |
+          composer install --no-interaction
+          composer dump
+
+      - name: Execute Pint
+        run: composer pint-check

.github/workflows/code-style.yml

@@ -141,6 +141,29 @@ public function index (Action $action)
 }
 ```
 
+## Macros
+
+There are times when you may want to add something extra to your actions. We can leverage macros for this!
+
+Here is an example were we are leveraging Inertia's defer functionality directly on our action. The macro then just calls `act()` on the action class when the deferred prop is requested!
+
+```php
+// In your service provider
+Action::macro('defer', function($action, ...$arguments) {
+    return Inertia::defer(fn () => $action::act(...$arguments));
+});
+
+// In your controller
+return Inertia::render('Users/Index')
+    ->with('users', GetUsers::defer());
+```
+
+Note how the originating class is passed into the macro function as the first parameter. This is very important, otherwise the macro will be unaware of which action you are actually running as macros are technically run on the parent action class. You are also free to do what you want regarding the subsequent $arguments, but it is considered best practice to pack/unpack the arguments with the spread operator to ensure the actions are as flexible as possible.
+
+Also take note the `defer()` is defined on the `Kirschbaum\Actions\Action` class, not on the `GetUsers` action class. Individual actions are not macroable in and of themselves. The macro `defer()` will also be available to every action in your application, not just the `GetUsers` action! 
+
+Before and after events will not be fired when using macros. They will get fired however if you use an action's `act()`, `actWhen()`, or `actUnless()` methods with the macro function.
+
 ## Handling Failures
 
 We all know Chuck Norris isn't going to fail us, but he isn't the only one using this... Handling failures is pretty easy with Actions. Out of the box, any exceptions thrown by your Action classes get handled by Laravel's exception handler. If you'd rather implement your own logic during a failure, add a `failed()` method to your Action. It's that easy! You can return data from your `failed()` method if you choose as well.

.github/workflows/run-tests.yml

@@ -25,13 +25,26 @@
         "yield"
       ]
     },
+    "class_definition": {
+      "multi_line_extends_each_single_line": true,
+      "single_item_single_line": true,
+      "single_line": false
+    },
     "concat_space": {
       "spacing": "one"
     },
     "explicit_string_variable": true,
     "method_chaining_indentation": true,
     "new_with_braces": true,
+    "nullable_type_declaration_for_default_null_value": true,
     "ordered_traits": true,
-    "phpdoc_separation": true
+    "php_unit_method_casing": {
+      "case": "camel_case"
+    },
+    "php_unit_test_annotation": {
+      "style": "prefix"
+    },
+    "phpdoc_separation": true,
+    "single_line_empty_body": true
   }
 }

README.md

@@ -2,23 +2,23 @@
 
 namespace Kirschbaum\Actions;
 
+use Illuminate\Support\Traits\Macroable;
 use Kirschbaum\Actions\Contracts\Actionable;
 use Kirschbaum\Actions\Exceptions\ActionableInterfaceNotFoundException;
 use Throwable;
 
 class Action
 {
+    use Macroable;
+
     /**
      * Arguments to pass into the action's constructor.
-     *
-     * @var array
      */
-    protected $arguments;
+    protected array $arguments;
 
     /**
      * Initiate the given action.
      *
-     * @param  string  $action
      * @param  mixed  ...$arguments
      *
      * @return mixed
@@ -35,8 +35,6 @@ public function act(string $action, ...$arguments)
     /**
      * Initiate the given action if the given condition is true.
      *
-     * @param $condition
-     * @param  string  $action
      * @param  mixed  ...$arguments
      *
      * @return mixed|void
@@ -55,8 +53,6 @@ public function actWhen($condition, string $action, ...$arguments)
     /**
      * Initiate the action if the given condition is false.
      *
-     * @param $condition
-     * @param  string  $action
      * @param  mixed  ...$arguments
      *
      * @return mixed|void
@@ -75,7 +71,6 @@ public function actUnless($condition, string $action, ...$arguments)
     /**
      * Handle the given action.
      *
-     * @param  string  $action
      *
      * @return mixed|void
      *
@@ -101,16 +96,17 @@ protected function handle(string $action)
 
     /**
      * Determine if the action has a `failed()` method defined.
-     *
-     * @param  Actionable  $action
-     *
-     * @return bool
      */
     protected function actionHasFailedMethod(Actionable $action): bool
     {
         return method_exists($action, 'failed');
     }
 
+    /**
+     * Determine if the action has the proper interface.
+     *
+     * @throws Throwable
+     */
     protected function checkActionForInterface($action): void
     {
         throw_unless(
@@ -121,11 +117,6 @@ protected function checkActionForInterface($action): void
 
     /**
      * Dispatch appropriate action event.
-     *
-     * @param  string  $event
-     * @param  Actionable  $action
-     *
-     * @return void
      */
     protected function dispatchEvent(string $event, Actionable $action): void
     {
@@ -139,11 +130,6 @@ protected function dispatchEvent(string $event, Actionable $action): void
 
     /**
      * Check if the given event exists in the action.
-     *
-     * @param  Actionable  $action
-     * @param  string  $event
-     *
-     * @return bool
      */
     protected function eventExists(Actionable $action, string $event): bool
     {
@@ -154,8 +140,6 @@ protected function eventExists(Actionable $action, string $event): bool
     /**
      * Fire failure event and/or call failed action method if they exist.
      *
-     * @param  Actionable  $action
-     * @param  Throwable  $exception
      *
      * @return mixed
      *
@@ -178,10 +162,6 @@ protected function handleFailure(Actionable $action, Throwable $exception)
 
     /**
      * Check if action has a custom exception.
-     *
-     * @param  Actionable  $action
-     *
-     * @return bool
      */
     protected function hasCustomException(Actionable $action): bool
     {
@@ -191,10 +171,6 @@ protected function hasCustomException(Actionable $action): bool
 
     /**
      * Raise the before action event.
-     *
-     * @param  Actionable  $action
-     *
-     * @return void
      */
     protected function raiseBeforeActionEvent(Actionable $action): void
     {
@@ -203,10 +179,6 @@ protected function raiseBeforeActionEvent(Actionable $action): void
 
     /**
      * Raise the after action event.
-     *
-     * @param  Actionable  $action
-     *
-     * @return void
      */
     protected function raiseAfterActionEvent(Actionable $action): void
     {