README

A lightweight and expressive response helper designed to provide a consistent structure when returning action results in PHP applications.

This package includes:

• A Response class with a fluent API
• A ResponseStatus enum (success, error, snooze)
• Convenience constructors (success(), error(), snooze())
• Helpers for attaching messages, errors, data, and retrieving nested data via dot notation

📦 Installation

Install via Composer:

composer require manhhuyvo/action-response

🚀 Basic Usage

Create a success response

use ManhHuyVo\ActionResponse\Response;

$response = Response::success()
    ->message('Action completed successfully.')
    ->data(['foo' => 'bar']);

return $response;

Create an error response

$response = Response::error()
    ->message('Unable to process request.')
    ->errors(['Invalid input', 'Another error']);

return $response;

Create a snooze response

Useful when the action should be skipped or is not applicable.

$response = Response::snooze()
    ->message('Skipping this action for now.');

return $response;

🧱 Response Structure

A Response object contains:

Example structure:

[
    'status' => 'success',
    'message' => 'Action completed successfully.',
    'errors' => [],
    'data' => [
        'foo' => 'bar'
    ],
]

🔍 Status Checking

$response->isSuccessful(); // true / false
$response->isError();      // true / false
$response->isSnooze();     // true / false

🎯 Setting Values Manually

$response = (new Response())
    ->status('success')
    ->message('Done')
    ->data(['x' => 1])
    ->errors([]);

return $response;

📥 Accessing Nested Data (Dot Notation)

If your data is nested:

$response = Response::success()->data([
    'user' => [
        'profile' => [
            'email' => 'john@example.com'
        ],
    ],
]);

You can fetch nested values:

$response->getData('user.profile.email');

// "john@example.com"

🧩 ResponseStatus Enum

enum ResponseStatus: string
{
    case Success = 'success';
    case Error   = 'error';
    case Snooze  = 'snooze';
}

🧪 Running Tests

If you are developing locally, run PHPUnit:

vendor/bin/phpunit --testdox

📚 Example Usage in a Real Action

use ManhHuyVo\ActionResponse\Response;

function processOrder(array $order): Response
{
    if (empty($order)) {
        return Response::error()
            ->message('Order cannot be empty.')
            ->errors(['order_empty']);
    }

    if ($order['status'] === 'skipped') {
        return Response::snooze()
            ->message('Order skipped.');
    }

    return Response::success()
        ->message('Order processed.')
        ->data(['id' => 123]);
}

📝 License

MIT License.