#Hooks

Hooks allow you to intercept and modify the behavior of Veloquent actions at key points in their lifecycle. They use Laravel's Pipeline system to provide a clean, extensible way to add custom logic without modifying the core framework.

#Registration

Hooks are typically registered in the hooks/hooks.php. This file is automatically loaded by the Veloquent Service Provider.

use Veloquent\Core\Domain\Hooks\Facades\Hooks;
use Veloquent\Core\Domain\Hooks\ValueObjects\HookPayload;

Hooks::before('record.create', function (HookPayload $payload, Closure $next) {
    // Modify data before it hits the database
    $payload->data['status'] = 'pending';
    
    // IMPORTANT: You must return the result of $next($payload)
    return $next($payload);
});

Every hook pipe MUST return the result of $next($payload). Failure to do so will stop the pipeline and may result in the core action receiving an empty or incomplete payload. If you want to abort an operation explicitly use the HookAbortException exception.

#The Hook Payload

Every hook closure or class-based pipe receives a Veloquent\Core\Domain\Hooks\ValueObjects\HookPayload object as its first argument. This payload encapsulates all relevant context about the event and the request, providing a unified, secure, and clean interface to inspect or mutate execution state.

#Payload Structure

The HookPayload object has the following properties:

#Property Availability by Event

The properties populated within HookPayload differ depending on the lifecycle stage. The following table defines what to expect inside each hook:

#Practical Payload Usage Examples

#1. Mutating Input Data in "Before" Hooks

In before hooks (like 'record.creating' or 'record.updating'), modifying the $payload->data array directly mutates what is saved to the database. You can do this in-place:

use Veloquent\Core\Domain\Hooks\Facades\Hooks;
use Veloquent\Core\Domain\Hooks\ValueObjects\HookPayload;
use Illuminate\Support\Str;

Hooks::before('record.create', function (HookPayload $payload, Closure $next) {
    // 1. Set default status in-place
    if (!isset($payload->data['status'])) {
        $payload->data['status'] = 'draft';
    }

    // 2. Automatically generate a unique slug
    if (isset($payload->data['title'])) {
        $payload->data['slug'] = Str::slug($payload->data['title']);
    }

    return $next($payload);
});

Alternatively, you can return a completely new immutable copy using the $payload->withData(array $data) helper method:

Hooks::before('record.create', function (HookPayload $payload, Closure $next) {
    $mergedData = array_merge($payload->data, [
        'is_approved' => false,
        'approved_at' => null,
    ]);

    // Return next with a cloned, modified payload
    return $next($payload->withData($mergedData));
});

#2. Auditing and Ownership via the actor Property

Use the actor property to restrict actions or perform ownership checks based on the currently authenticated user:

use Veloquent\Core\Domain\Hooks\Exceptions\HookAbortException;

Hooks::before('record.update', function (HookPayload $payload, Closure $next) {
    $actor = $payload->actor;

    // Check if record has a creator and actor is NOT the creator or superuser
    if ($actor && !$actor->isSuperuser()) {
        $ownerId = $payload->record->created_by;
        if ($ownerId && $ownerId !== $actor->id) {
            throw new HookAbortException("Unauthorized: You do not own this record.");
        }
    }

    return $next($payload);
});

#3. Accessing Request Headers, IPs, or User-Agents

Use the request property to query environmental parameters, request metadata, or geo/browser details during action lifecycle events:

Hooks::after('auth.login', function (HookPayload $payload, Closure $next) {
    $user = $payload->record;
    $request = $payload->request;

    if ($request) {
        // Log the successful login audit trail
        activity()
            ->performedOn($user)
            ->withProperties([
                'ip' => $request->ip(),
                'user_agent' => $request->userAgent(),
            ])
            ->log('User logged in successfully');
    }

    return $next($payload);
});

#Before vs After Hooks

#Before Hooks

• Run inside the database transaction.
• Can modify the $payload->data before the operation executes.
• If a "before" hook throws an exception, the entire operation (including any DB changes made by previous hooks) is rolled back.
• Used for validation, sanitization, and complex authorization.

#After Hooks

• Run outside the database transaction.
• Run after the primary operation has succeeded.
• Exceptions in "after" hooks are silenced and logged by default to prevent side-effects from failing the main request.
• Used for notifications, external API syncs, or logging.

#Class-based Hooks

For complex logic, you can use classes that implement the HookPipe contract:

namespace App\Hooks;

use Veloquent\Core\Domain\Hooks\Contracts\HookPipe;
use Veloquent\Core\Domain\Hooks\ValueObjects\HookPayload;
use Closure;

class SanitizePost implements HookPipe
{
    public function handle(HookPayload $payload, Closure $next): mixed
    {
        $payload->data['title'] = strip_tags($payload->data['title']);
        
        return $next($payload);
    }
}

Register the class in hooks.php:

Hooks::before('record.create', \App\Hooks\SanitizePost::class);

#Aborting Operations

To halt an operation from a "before" hook, throw the HookAbortException:

use Veloquent\Core\Domain\Hooks\Exceptions\HookAbortException;

Hooks::before('record.delete', function ($payload, $next) {
    if ($payload->record->is_protected) {
        throw new HookAbortException("This record cannot be deleted.");
    }
    return $next($payload);
});

#Supported Events