README

A modular, testable, and maintainable package for encapsulating outbound HTTP calls in Laravel. Raid Caller enforces a clean separation of concerns for HTTP requests, making your codebase more robust and easier to extend.

Features

• Separation of concerns: Caller (intent), Service (execution), Receiver (parsing), DTO (domain model)
• Immutable DTOs: Safe, readonly data transfer objects
• Extensible: Easy to add new endpoints and customize behavior
• Testable: Works seamlessly with Laravel HTTP fakes

Installation

composer require raid/caller

• Compatible with Laravel 9+
• The service provider Raid\\Caller\\Providers\\CallerServiceProvider is auto-discovered. If not, register it manually.
• To publish the config (if available):

php artisan vendor:publish --tag=caller

Quick Start

Here's a minimal example for making a GET request:

readonly class GetUsersCaller extends \Raid\Caller\Callers\GetCaller {
    public function getUrl(): string { return 'https://api.example.com/users'; }
    public function getReceiver(): string { return GetUsersReceiver::class; }
}

readonly class GetUsersReceiver extends \Raid\Caller\Receivers\ResponseReceiver {
    public function __construct(protected int $status, protected array $users) {}
    public static function fromResponse(\Illuminate\Http\Client\Response $r): static {
        return new static(status: $r->status(), users: array_map(fn(array $u) => UserDto::fromArray($u), $r->json()));
    }
    public function toSuccessResponse(): array { return ['message' => 'Users fetched', 'data' => array_map(fn(UserDto $u) => $u->toArray(), $this->users)]; }
    public function toErrorResponse(): array { return ['message' => 'Failed to fetch users']; }
}

Concepts

• Callers: Define HTTP method, URL, options, and receiver. (Docs)
• Receivers: Parse responses and shape output. (Docs)
• DTOs: Immutable data models. (Docs)
• Service: Orchestrates execution and extension points. (Docs)
• Traits & Provider: Utilities and configuration. (Docs, Docs)

See the Overview for a high-level map.

Lifecycle

See Lifecycle for a summary and sequence diagram.

Advanced Usage

• Customize options, headers, and caching in Callers
• Extend Receivers for custom response handling
• Add new DTOs for your domain models

Testing

Use Laravel HTTP fakes to test Callers and Receivers in isolation. See Testing.

Observability & Conventions

• Logging, correlation, and metrics are supported. See Observability.
• Coding norms and best practices: Conventions.

Contributing

Contributions are welcome! Please open issues or submit pull requests.

License

This package is open-sourced software licensed under the MIT license.

Roadmap

See Roadmap for planned features and improvements.

Changelog

See CHANGELOG.md for release history.