Download the PHP package phpmystic/kai without Composer

Kai - Fluent PHP HTTP Client

A fluent, exception-less PHP HTTP client library that uses a callback-based approach for handling responses. Built on cURL.

Features

• Fluent Interface - Chain methods for readable, expressive code
• Callback-Based - Handle different response scenarios with callbacks
• Exception-Less - No try-catch blocks needed, handle errors gracefully with callbacks
• Type-Safe - Full type hints for better IDE support
• Lightweight - Minimal dependencies, just PHP and cURL
• Testable - Built-in support for mocking HTTP requests

Requirements

• PHP >= 7.4
• ext-curl
• ext-json

Installation

Quick Start

Basic Usage

Creating a Client

Making Requests

GET Request

POST Request

PUT Request

PATCH Request

DELETE Request

Advanced Features

Query Parameters

Custom Headers

Fluent Chaining

Chain multiple operations together:

Response Handlers

Status-Specific Handlers

Handle specific HTTP status codes:

Generic Status Code Handler

Range Handlers

Handle ranges of status codes:

Error Handling

Handle cURL-level errors (connection failures, timeouts, etc.):

Always Handler

Execute a callback regardless of the response status:

Response Object

All callbacks receive a Response object with the following properties and methods:

Properties

Methods

Example Usage

Working with Different Response Types

Real-World Examples

RESTful API Client

GitHub API Integration

Weather API Client

Multi-Endpoint Workflow

Error Handling Pattern

Testing

Using Mocks in Tests

The library supports dependency injection for easy testing:

For more details on testing, see tests/README.md.

Running Tests

Design Philosophy

Why Callbacks Instead of Exceptions?

Traditional HTTP clients throw exceptions for error responses:

Kai uses a callback-based approach:

Benefits:

1. More Explicit - Each status code is handled explicitly
2. No Try-Catch Blocks - Cleaner code flow
3. Fluent Interface - Chain handlers naturally
4. Selective Handling - Only handle the statuses you care about
5. Better for Multiple Outcomes - HTTP responses aren't really "exceptions"

API Reference

Client Methods

Constructor

Request Configuration

• query(array $params): self - Set query parameters
• withHeaders(array $headers): self - Set request headers

HTTP Methods

• get(string $url): self - Send GET request
• post(string $url, array $data = []): self - Send POST request
• put(string $url, array $data = []): self - Send PUT request
• patch(string $url, array $data = []): self - Send PATCH request
• delete(string $url): self - Send DELETE request

Response Handlers

• on(int $statusCode, callable $callback): self - Handle specific status code
• onSuccess(callable $callback): self - Handle 2xx responses
• onClientError(callable $callback): self - Handle 4xx responses
• onServerError(callable $callback): self - Handle 5xx responses
• onError(callable $callback): self - Handle cURL errors
• always(callable $callback): self - Always execute callback

Status Code Aliases

• ok(callable $callback): self - Handle 200
• created(callable $callback): self - Handle 201
• accepted(callable $callback): self - Handle 202
• noContent(callable $callback): self - Handle 204
• badRequest(callable $callback): self - Handle 400
• unauthorized(callable $callback): self - Handle 401
• forbidden(callable $callback): self - Handle 403
• notFound(callable $callback): self - Handle 404
• unprocessable(callable $callback): self - Handle 422
• serverError(callable $callback): self - Handle 500

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This library is licensed under the MIT License. See the LICENSE file for details.

Author

Elmehdi el faithi - [email protected]

Links

• GitHub Repository
• Issue Tracker
• Packagist