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.

Table of Contents

• Overview
• Installation
• Features
• Quick Start
• Core Concepts
• Usage
  • As Controller
  • As Job
  • As Command
  • As Listener
  • As Object
  • Combined 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.