README

A modern PHP SDK foundation package for building API clients with ease.

Based on hanson/foundation-sdk, redesigned with PSR standards and improved architecture.

Features

Feature	Description
PSR-3 Logging	Standard logger interface, Monolog optional, auto HTTP logging
PSR-16 Cache	Built-in file cache with security hardening, or bring your own
HTTP Client	Guzzle wrapper with GET/POST/PUT/PATCH/DELETE/Upload, 20s default timeout
Auto Logging	LogMiddleware records all requests/responses, supports database storage
Middleware	Promise-based pipeline with auth, retry & logging built-in
Response Wrapper	Auto JSON/XML decode with XXE protection, status helpers
Token Management	Auto-cached access token with refresh
Dot-notation Config	Access nested config with `log.file` syntax

Requirements

PHP >= 7.4
ext-curl
ext-json

Installation

composer require royfee/basesdk

For file-based logging, install Monolog:

composer require monolog/monolog

Quick Start

use Royfee\BaseSdk\Application;
use Royfee\BaseSdk\Api\AbstractApi;
use Royfee\BaseSdk\Http\Middleware\AuthMiddleware;
use Royfee\BaseSdk\Http\Middleware\RetryMiddleware;

// 1. Create the application
$app = new Application([
    'app_id' => 'your-app-id',
    'secret' => 'your-secret',
    'debug'  => true,
    'log'    => [
        'file'  => __DIR__ . '/logs/sdk.log',
        'level' => 'debug',
    ],
]);

// 2. Define your API class
class MyApi extends AbstractApi
{
    public function registerMiddlewares(): void
    {
        $this->addMiddleware(new AuthMiddleware($this->app['access_token']));
        $this->addMiddleware(new RetryMiddleware(3, 500));
    }

    public function getUsers(): array
    {
        return $this->get('/users')->toArray();
    }

    public function createUser(array $data): array
    {
        return $this->postJson('/users', $data)->toArray();
    }
}

// 3. Use it
$api = new MyApi($app);
$users = $api->getUsers();

Documentation

See the doc/ directory for detailed documentation:

Installation — Environment requirements and Composer setup
Quick Start — Get started in 5 minutes
Configuration — All config options and service providers
HTTP Client — Request methods, timeout, default options
Response — JSON/XML parsing, magic access, status helpers
Middleware — Built-in middleware, custom middleware guide, Promise pattern
Access Token — Auto-cached tokens, custom field mapping
API Base Class — Building your API layer
Cache — PSR-16 file cache, custom implementations
Logging — PSR-3 logging, auto HTTP logging, database logging
Exceptions — Exception hierarchy and best practices

Examples

Example	Description
17Track API Client	Full example of integrating with the 17track shipping API
JsonPlaceholder	Standard RESTful JSON API (GET/POST/PUT/PATCH/DELETE)
XmlApi	XML response parsing with `toArray()` and `toXml()`
Middleware	Custom middleware patterns (header injection, HMAC signing, Promise-based validation)
DatabaseLog	HTTP request logging to SQLite/MySQL database

Testing

composer test

Static Analysis

composer analyse

License

MIT License. See LICENSE for details.

royfee / basesdk

Package info

Security

Statistics