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.

raid / caller

Maintainers

Details