---
name: actions-3a2c9f677b05
description: >-
  Implementa lógica de negócio em Laravel usando Actions (lorisleiva/laravel-actions), Events, Listeners, Jobs e Observers. Use quando precisar criar actions, despachar eventos, jobs em background, ou implementar padrões event-driven em projetos Laravel.
compatibility: PHP 8.2+, Laravel 11+, laravel-actions
metadata:
  author: aronpc
  version: 5.0.0
  category: laravel
allowed-tools:
  - Read
  - Write
  - Edit
  - Bash
---

# actions

## Resumo
Implementa lógica de negócio usando Actions, Events, Jobs e Observers.

## Skills Relacionadas

| Skill | Quando usar junto |
|-------|-------------------|
| `architecture` | Para usar Actions na arquitetura limpa |
| `realtime` | Para broadcasting de events |
| `testing` | Para testar Actions e Events |
| `exceptions` | Para tratamento de erros em Actions |
| `coder` | Para implementar Actions |

## Quando usar

Use esta skill sempre que:
- Criar lógica de negócio para Laravel
- Separar side-effects da lógica principal
- Criar background jobs
- Configurar model observers
- Implementar event-driven architecture

## Princípios Fundamentais

1. **Actions over Services** - Sempre use `lorisleiva/laravel-actions`
2. **Event-Driven** - Use Events + Listeners para side effects
3. **Observers** - Use para model lifecycle hooks
4. **Jobs** - Queue via Actions implementando `ShouldQueue`

## Criando Actions

```bash
php artisan make:action CreateBusiness
```

## Estrutura de Action

```php
<?php

declare(strict_types=1);

namespace App\Actions\Business;

use App\DataObjects\Business\CreateBusinessData;
use App\Models\Business;
use App\Models\Tenant;
use Lorisleiva\Actions\Concerns\AsAction;

final class CreateBusinessAction
{
    use AsAction;

    /**
     * Execute action.
     */
    public function handle(Tenant $tenant, CreateBusinessData $data): Business
    {
        // Check limits
        if (!$tenant->isWithinLimit('businesses')) {
            throw new \Exception('Business limit exceeded');
        }

        // Create business
        $business = $tenant->businesses()->create($data->toArray());

        // Increment usage
        $tenant->incrementUsage('businesses');

        // Dispatch event
        event(new BusinessCreated($business));

        return $business;
    }

    /**
     * Use as controller (optional).
     */
    public function asController(StoreBusinessRequest $request): Business
    {
        $data = CreateBusinessData::fromRequest($request->validated());
        return $this->handle(auth()->user()->tenant, $data);
    }

    /**
     * Run as queued job (optional).
     */
    public function asJob(Tenant $tenant, CreateBusinessData $data): void
    {
        $this->handle($tenant, $data);
    }
}
```

## Uso de Actions

```php
// Run sincronamente
CreateBusinessAction::run($tenant, $data);

// Run em background (queued)
CreateBusinessAction::dispatch($tenant, $data);

// Run com delay
CreateBusinessAction::dispatch($tenant, $data)->delay(now()->addMinutes(5));

// Run em fila específica
CreateBusinessAction::dispatch($tenant, $data)->onQueue('high');
```

## Value Objects (DTOs)

**CRÍTICO:** Actions DEVEM usar Value Objects - NUNCA passe arrays crusos.

### Por Que Usar Value Objects?

✅ Type Safety - Detecta erros em tempo de compilação \
✅ Suporte IDE - Autocompletion \
✅ Validação Centralizada - Em um lugar \
✅ Imutabilidade - Previne mutações \
✅ Self-Documenting - Contrato claro \
✅ Reusabilidade - Use across Actions/Jobs/Events

❌ Single primitive values \
❌ Eloquent models \
❌ Collections

### Criando Value Objects

```php
<?php

declare(strict_types=1);

namespace App\DataObjects\Business;

final readonly class CreateBusinessData
{
    public function __construct(
        public string $name,
        public string $type,
        public ?string $email = null,
        public ?string $phone = null,
        public ?array $settings = null,
    ) {}

    public static function fromRequest(array $data): self
    {
        return new self(
            name: $data['name'],
            type: $data['type'],
            email: $data['email'] ?? null,
            phone: $data['phone'] ?? null,
            settings: $data['settings'] ?? null,
        );
    }

    public function toArray(): array
    {
        return [
            'name' => $this->name,
            'type' => $this->type,
            'email' => $this->email,
            'phone' => $this->phone,
            'settings' => $this->settings ?? [],
        ];
    }
}
```

### Quando Usar Value Objects

✅ Action parameters (sempre para inputs complexos) \
✅ Service methods \
✅ API responses \
✅ Event payloads \
✅ Jobs data

❌ Single primitive values \
❌ Eloquent models \
❌ Collections

## Events & Listeners

**Event:**

```php
<?php

namespace App\Events;

use App\Models\Business;
use Illuminate\Foundation\Events\Dispatchable;

final class BusinessCreated
{
    use Dispatchable;

    public function __construct(public Business $business) {}
}
```

**Listener (as Action):**

```php
<?php

namespace App\Listeners;

use App\Events\BusinessCreated;
use Lorisleiva\Actions\Concerns\AsAction;

final class SendBusinessWelcomeEmail
{
    use AsAction;

    public function handle(BusinessCreated $event): void
    {
        // Send welcome email
    }
}
```

## Model Observers

```bash
php artisan make:observer BusinessObserver --model=Business
```

```php
<?php

namespace App\Observers;

use App\Models\Business;

final class BusinessObserver
{
    public function creating(Business $business): void
    {
        $business->slug = Str::slug($business->name);
    }

    public function created(Business $business): void
    {
        event(new BusinessCreated($business));
    }

    public function updating(Business $business): void
    {
        if ($business->isDirty('name')) {
            $business->slug = Str::slug($business->name);
        }
    }
}
```

**Registrar em AppServiceProvider:**

```php
public function boot(): void
{
    Business::observe(BusinessObserver::class);
}
```

## Melhores Práticas

### ✅ FAÇA

- Use Actions para toda lógica de negócio
- Use Value Objects para dados complexos
- Use Events para side-effects
- Use Observers para model lifecycle
- Use Jobs para processos longos
- Dispatch Events após mudanças de estado
- Mantenha Actions focadas (single responsibility)

### ❌ NÃO FAÇA

- Não crie Services tradicionais
- Não passe arrays crusos para Actions
- Não coloque lógica de negócio em Models
- Não esqueça de usar Events
- Não use DB facade em Actions
- Não crie Actions sem tipagem

## Referências Cruzadas

- **Estrutura Actions/DTOs**: Veja `architecture` para estrutura completa de Actions e Value Objects
- **Traduções**: Veja `i18n` para traduções de Events e mensagens de sistema
- **Exceções**: Veja `exceptions` para criar exceções customizadas em Actions
- **Testes**: Veja `testing` para testes de Actions, Jobs e Events

## Referências

- `docs/07-actions-events-jobs.md` - Documentação completa
- [Laravel Actions Documentation](https://laravelactions.com/) - Documentação oficial
- [Laravel Events Documentation](https://laravel.com/docs/events) - Documentação Laravel


---
Source attribution: aronpc
Original project: https://github.com/aronpc/ai/blob/85e01f1cbbd8159dd87c408f226435c0b3201c09/skills/actions/SKILL.md
License: MIT
License information: https://opensource.org/license/mit
Original upstream instructions; downloaded from Mega AI Hub.

## Upstream license notice

MIT License

Copyright (c) 2026 AronPC

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.



# Mega AI Hub resource metadata

Creator / publisher: aronpc
Original project: https://github.com/aronpc/ai/blob/85e01f1cbbd8159dd87c408f226435c0b3201c09/skills/actions/SKILL.md
Attribution basis: Source repository record

Fields of work: Development & Engineering, Product Management
Roles: Backend Developer, Full-Stack Developer, Product Manager
Specialties: Backend
Tools: Laravel
Country applicability: Country not specified
Classification basis: Source category, role and specialization labels
Instruction SHA-256: 857de17b136189cbfa6d4d1389135bcc83fb34eae7865f8499cd41438ffbb37e