README

Single-purpose action classes that can be used as controllers, jobs, commands, and listeners

The Actions package provides traits for creating versatile action classes that can be executed in multiple contexts (HTTP, CLI, Queue, Events) without code duplication.

Overview
Installation
Features
Quick Start
Core Concepts
Usage
API Reference
Best Practices
Testing
Examples

Overview

The Actions package is built on top of lorisleiva/laravel-actions and provides a set of traits that allow you to create single-purpose action classes that can be executed in different contexts.

Key Benefits

✅ Single Responsibility: One class, one purpose
✅ Reusable: Use the same logic across HTTP, CLI, Queue, and Events
✅ Type Safe: Full IDE support and type hints
✅ Testable: Easy to test in isolation
✅ Clean Code: No code duplication

Installation

The Actions package is part of the Framework meta-package:

composer require pixielity/laravel-framework

Features

🎯 Multiple Execution Contexts

Execute the same action as a controller, job, command, or event listener.

🔄 Code Reusability

Write business logic once, use it everywhere.

🧪 Easy Testing

Test actions in isolation without HTTP or queue infrastructure.

📝 Type Safety

Full type hints and IDE autocompletion support.

Quick Start

Create an Action

use Pixielity\Actions\Concerns\AsAction;

class CreateUser
{
    use AsAction;

    public function handle(array $data): User
    {
        return User::create([
            'name' => $data['name'],
            'email' => $data['email'],
            'password' => Hash::make($data['password']),
        ]);
    }
}

Use as Controller

Route::post('/users', CreateUser::class);

Use as Job

CreateUser::dispatch($userData);

Use as Command

php artisan app:create-user

Use as Object

$user = CreateUser::run($userData);

Core Concepts

Action Classes

Actions are single-purpose classes that encapsulate a specific piece of business logic. They follow the Single Responsibility Principle and can be executed in multiple contexts.

Execution Contexts

Controller: Handle HTTP requests
Job: Run asynchronously in queue
Command: Execute from CLI
Listener: Respond to events
Object: Call directly as a method

Usage

As Controller

Use actions as HTTP controllers:

use Pixielity\Actions\Concerns\AsController;

class CreateUser
{
    use AsController;

    public function handle(array $data): User
    {
        return User::create($data);
    }

    public function asController(CreateUserRequest $request): JsonResponse
    {
        $user = $this->handle($request->validated());

        return response()->json($user, 201);
    }
}

// Route
Route::post('/users', CreateUser::class);

As Job

Dispatch actions to the queue:

use Pixielity\Actions\Concerns\AsJob;

class SendWelcomeEmail
{
    use AsJob;

    public function handle(User $user): void
    {
        Mail::to($user)->send(new WelcomeEmail($user));
    }
}

// Dispatch
SendWelcomeEmail::dispatch($user);

// Dispatch with delay
SendWelcomeEmail::dispatch($user)->delay(now()->addMinutes(5));

// Dispatch to specific queue
SendWelcomeEmail::dispatch($user)->onQueue('emails');

As Command

Execute actions from the command line:

use Pixielity\Actions\Concerns\AsCommand;

class GenerateReport
{
    use AsCommand;

    public string $commandSignature = 'report:generate {type}';
    public string $commandDescription = 'Generate a report';

    public function handle(string $type): void
    {
        $this->info("Generating {$type} report...");

        // Generate report logic

        $this->info('Report generated successfully!');
    }
}

// Execute
php artisan report:generate sales

As Listener

Use actions as event listeners:

use Pixielity\Actions\Concerns\AsListener;

class SendOrderConfirmation
{
    use AsListener;

    public function handle(OrderPlaced $event): void
    {
        Mail::to($event->order->customer)
            ->send(new OrderConfirmationEmail($event->order));
    }
}

// Register in EventServiceProvider
protected $listen = [
    OrderPlaced::class => [
        SendOrderConfirmation::class,
    ],
];

As Object

Call actions directly as methods:

use Pixielity\Actions\Concerns\AsObject;

class CalculateTotal
{
    use AsObject;

    public function handle(array $items): float
    {
        return collect($items)->sum('price');
    }
}

// Use
$total = CalculateTotal::run($items);

Combined Usage

Use multiple traits for maximum flexibility:

use Pixielity\Actions\Concerns\AsAction;

class ProcessPayment
{
    use AsAction;

    public string $commandSignature = 'payment:process {orderId}';

    public function handle(Order $order): PaymentResult
    {
        // Process payment logic
        return new PaymentResult($order);
    }

    // As Controller
    public function asController(ProcessPaymentRequest $request): JsonResponse
    {
        $order = Order::findOrFail($request->order_id);
        $result = $this->handle($order);

        return response()->json($result);
    }

    // As Job
    public function asJob(Order $order): void
    {
        $this->handle($order);
    }

    // As Command
    public function asCommand(int $orderId): void
    {
        $order = Order::findOrFail($orderId);
        $result = $this->handle($order);

        $this->info("Payment processed: {$result->status}");
    }
}

// Use in different contexts
Route::post('/payments', ProcessPayment::class);
ProcessPayment::dispatch($order);
php artisan payment:process 123
$result = ProcessPayment::run($order);

API Reference

Concerns

`AsAction`

Master trait that includes all other traits. Use this for maximum flexibility.

Includes:

AsObject
AsController
AsJob
AsCommand
AsListener

`AsObject`

Allows calling the action as a static method.

Methods:

run(...$parameters): Execute the action
make(): Create a new instance

`AsController`

Enables using the action as an HTTP controller.

Methods:

asController(...): Handle HTTP requests
authorize(): Authorization logic
rules(): Validation rules

`AsJob`

Allows dispatching the action to the queue.

Methods:

asJob(...): Handle queued execution
dispatch(...): Dispatch to queue
dispatchIf(...): Conditional dispatch
dispatchUnless(...): Inverse conditional dispatch

`AsCommand`

Enables executing the action as an Artisan command.

Properties:

$commandSignature: Command signature
$commandDescription: Command description

Methods:

asCommand(...): Handle command execution

`AsListener`

Allows using the action as an event listener.

Methods:

asListener(...): Handle event

Best Practices

1. Single Responsibility

Each action should do one thing:

// ✅ Good - Single purpose
class CreateUser { }
class SendWelcomeEmail { }
class GenerateUserReport { }

// ❌ Bad - Multiple responsibilities
class UserManager { }

2. Type Hints

Always use type hints:

// ✅ Good
public function handle(User $user, array $data): Order
{
    // Implementation
}

// ❌ Bad
public function handle($user, $data)
{
    // Implementation
}

3. Dependency Injection

Inject dependencies in the constructor:

class CreateOrder
{
    use AsAction;

    public function __construct(
        private OrderRepository $orders,
        private PaymentGateway $gateway
    ) {}

    public function handle(array $data): Order
    {
        // Use $this->orders and $this->gateway
    }
}

4. Validation

Validate input in controller context:

class CreateUser
{
    use AsAction;

    public function rules(): array
    {
        return [
            'name' => 'required|string|max:255',
            'email' => 'required|email|unique:users',
        ];
    }

    public function asController(Request $request): JsonResponse
    {
        // Validation happens automatically
        $user = $this->handle($request->validated());

        return response()->json($user, 201);
    }
}

Testing

Testing Actions

use Tests\TestCase;

class CreateUserTest extends TestCase
{
    public function test_creates_user(): void
    {
        $data = [
            'name' => 'John Doe',
            'email' => 'john@example.com',
            'password' => 'password123',
        ];

        $user = CreateUser::run($data);

        $this->assertInstanceOf(User::class, $user);
        $this->assertEquals('John Doe', $user->name);
        $this->assertDatabaseHas('users', [
            'email' => 'john@example.com',
        ]);
    }

    public function test_as_controller(): void
    {
        $response = $this->postJson('/users', [
            'name' => 'John Doe',
            'email' => 'john@example.com',
            'password' => 'password123',
        ]);

        $response->assertStatus(201);
    }

    public function test_as_job(): void
    {
        Queue::fake();

        SendWelcomeEmail::dispatch($user);

        Queue::assertPushed(SendWelcomeEmail::class);
    }
}

Examples

Complete CRUD Action

use Pixielity\Actions\Concerns\AsAction;

class UpdateUser
{
    use AsAction;

    public function __construct(
        private UserRepository $users
    ) {}

    public function handle(User $user, array $data): User
    {
        return $this->users->update($user, $data);
    }

    public function rules(): array
    {
        return [
            'name' => 'sometimes|string|max:255',
            'email' => 'sometimes|email|unique:users,email,' . $this->user->id,
        ];
    }

    public function asController(UpdateUserRequest $request, User $user): JsonResponse
    {
        $updated = $this->handle($user, $request->validated());

        return response()->json($updated);
    }

    public function asCommand(int $userId, string $name): void
    {
        $user = User::findOrFail($userId);
        $this->handle($user, ['name' => $name]);

        $this->info("User {$userId} updated successfully!");
    }
}

Related Packages

lorisleiva/laravel-actions: The underlying package
ServiceProvider: Base service provider for action registration
Support: Utilities used by actions

License

This package is part of the Pixielity Framework and is open-sourced software licensed under the MIT license.

pixielity / laravel-actions

Maintainers

Details

README

Table of Contents

Overview

Key Benefits

Installation

Features

🎯 Multiple Execution Contexts

🔄 Code Reusability

🧪 Easy Testing

📝 Type Safety

Quick Start

Create an Action

Use as Controller

Use as Job

Use as Command

Use as Object

Core Concepts

Action Classes

Execution Contexts

Usage

As Controller

As Job

As Command

As Listener

As Object

Combined Usage

API Reference

Concerns

AsAction

AsObject

AsController

AsJob

AsCommand

AsListener

Best Practices

1. Single Responsibility

2. Type Hints

3. Dependency Injection

4. Validation

Testing

Testing Actions

Examples

Complete CRUD Action

Related Packages

License

`AsAction`

`AsObject`

`AsController`

`AsJob`

`AsCommand`

`AsListener`