clearsoft / easysql-sdk

1.5.0 2026-09-04 13:36 UTC

Requires

• php: >=8.2
• ext-json: *
• guzzlehttp/guzzle: ^7.0

Requires (Dev)

• illuminate/contracts: ^11.0
• illuminate/support: ^11.0
• orchestra/testbench: ^9.0
• phpunit/phpunit: ^11.0

Suggests

• illuminate/support: Required to use the Laravel Service Provider and Facade (^11.0)

MIT

• Clearsoft

• database
• php
• sql
• api
• sdk
• laravel
• ai
• llm
• easysql
• clearsoft

Published on Packagist.org on 2026-09-04 13:52 UTC

README

EasySQL PHP & Laravel SDK

Official PHP & Laravel SDK for the EasySQL API · A Clearsoft Product

Ask questions in natural language to your MySQL, MariaDB, or PostgreSQL databases directly from your PHP applications and Laravel projects.

Requirements

• PHP >= 8.2
• ext-json
• guzzlehttp/guzzle ^7.0
• (Optional) Laravel ^11.0 (for Service Provider and Facade)

Installation

composer require clearsoft/easysql-sdk

Laravel Integration

The SDK provides first-class support for Laravel with automatic package discovery, configuration publishing, and a dedicated EasySQL facade.

1. Publish Configuration (Optional)

Publish the easysql.php configuration file:

php artisan vendor:publish --tag=easysql-config

This creates config/easysql.php in your Laravel application.

2. Configure Environment Variables

Add your credentials to your .env file:

EASYSQL_BASE_URL=https://api.easysql.net
EASYSQL_ACCESS_TOKEN=your-access-token
EASYSQL_TIMEOUT=30

3. Using the Facade

use Clearsoft\EasySql\Laravel\Facades\EasySQL;

// Ask questions in natural language
$result = EasySQL::createQuery([
    'connector_id' => 'conn_abc123',
    'question'     => 'How many users registered this month?',
]);

// Generated SQL and query results
$sql  = $result['sql'];
$rows = $result['result'];

// List recent queries
$queries = EasySQL::listQueries(['page' => 1, 'per_page' => 10]);

// Manage database connectors
$connectors = EasySQL::listConnectors();
$connector  = EasySQL::getConnector('conn_abc123');

// Access specific named connections defined in config/easysql.php
$analyticsClient = EasySQL::connection('analytics');
$stats = $analyticsClient->dashboardStats();

Standalone PHP Usage

Typed API Client (Recommended)

Use the generated Client with typed methods for all endpoints:

<?php

require 'vendor/autoload.php';

use Clearsoft\EasySQL\SDK\Client;

$client = new Client([
    'base_url'     => 'https://api.easysql.net',
    'access_token' => 'your-access-token',
]);

// Authentication
$tokens = $client->login([
    'email'    => '[e-mail]',
    'password' => 'secret',
]);
$user = $client->me();

// Managing Database Connectors
$client->createConnector([
    'name'   => 'Production MySQL',
    'type'   => 'mysql',
    'config' => [
        'host'     => 'db.example.com',
        'port'     => 3306,
        'database' => 'myapp',
        'user'     => 'readonly',
        'password' => 'secret',
    ],
]);

$connectors = $client->listConnectors();

// Running Natural Language Queries
$query = $client->createQuery([
    'connector_id' => 'conn_abc123',
    'question'     => 'What were the top 5 selling products last week?',
]);

print_r($query['sql']);
print_r($query['result']);

Automatic Token Refresh (EasySQLClient)

For automatic token refresh on 401 Unauthorized responses and persistent token storage:

use Clearsoft\EasySQL\SDK\EasySQLClient;
use Clearsoft\EasySQL\SDK\TokenStoreInterface;

$client = new EasySQLClient([
    'base_url'      => 'https://api.easysql.net',
    'access_token'  => $accessToken,
    'refresh_token' => $refreshToken,
]);

// Implement TokenStoreInterface to persist tokens in Redis, Session, or Database
class SessionTokenStore implements TokenStoreInterface
{
    public function load(): ?array
    {
        return $_SESSION['easysql_tokens'] ?? null;
    }

    public function save(string $accessToken, string $refreshToken): void
    {
        $_SESSION['easysql_tokens'] = [
            'access_token'  => $accessToken,
            'refresh_token' => $refreshToken,
        ];
    }

    public function clear(): void
    {
        unset($_SESSION['easysql_tokens']);
    }
}

$client->setTokenStore(new SessionTokenStore());

API Overview

Module	Available Methods
Auth	register, login, refresh, me, deleteMe, updateMe, changePassword
Queries	createQuery, listQueries, getQuery
Connectors	listConnectors, createConnector, testConnector, getConnector, updateConnector, deleteConnector, syncConnector
Billing	getPlan, checkout, portal
Dashboard	dashboardStats
Health	health, healthHealth

See docs/API.md for full endpoint reference and parameters.

Development & Contributing

Contributions are welcome! Please read our Contributing Guidelines for details on the development workflow and pull request process.

make install                          # install composer dependencies
make lint                             # check PHP syntax
make test                             # run PHPUnit test suite
make generate                         # regenerate Client & Models from OpenAPI spec
make build                            # full build (generate + lint + test)

License

This project is open source and licensed under the MIT License.

Maintained by Clearsoft.