README

The official PHP client for ZTeraDB—a unified database abstraction platform. This library enables you to connect to your existing data infrastructure and execute queries seamlessly using ZTeraDB Query Language (ZQL).

Technical Overview

This package implements a performance-optimized, ZQL-first PHP client utilizing a raw TCP socket transport layer.

To ensure low-overhead binary framing, the client communicates with the ZTeraDB server using 4-byte big-endian length-prefixed payloads containing structured JSON data. This underlying transport architecture eliminates HTTP overhead, offering high-throughput query execution directly from your PHP runtime.

🧠 Architecture Overview

You never connect to your backend databases directly. ZTeraDB handles all connections, cryptographic signing, proxy routing, and query execution securely behind the scenes.

Your App ➔ ZTeraDB PHP Client ➔ ZTeraDB Server ➔ Your Databases

Key Features

• Unified Access: Query multiple existing databases through a single interface.
• Type-Safe & Standardized: Receive predictable, structured payloads regardless of the underlying data source.
• Lightweight: Built with minimal overhead, supporting modern PHP environments (7.2+).

Table of Contents

1. Key Features
2. Prerequisites & Requirements
3. Installation
4. Usage
5. Documentation Sections
6. Licence

⭐ Key Features

• 🚀 Unified Query Language (ZQL): Write once, run on any database (PostgreSQL, MySQL, MSSQL, etc.).
• 🔌 Easy Integration: Seamlessly plugs into any PHP application or framework (Laravel, Symfony, CodeIgniter).
• ⚙️ Auto-Managed Connections: Handles connection pooling and automatic retries behind the scenes.
• 🔐 Secure Authentication: Protected via client, access, and secret keys with cryptographic signing.
• 🎯 Clean Query Builder: Fluent interface for standard CRUD operations (insert, select, update, delete).
• 🔍 Advanced Filtering: Built-in support for complex logical and mathematical filters.
• 🧵 Streamed Results: Efficiently memory-manages large datasets using PHP generators.
• 📦 Type-Safe & Standardized: Receive predictable, structured payloads regardless of the underlying data source.

🛠 Prerequisites & Requirements

Installation

Option 1: Via Composer (Recommended)

Run the following command in your terminal to install the ZTeraDB client:

# Using composer
composer require zteradb/zteradb-php

Option 2: From GitHub Repository

Alternatively, you can pull the package directly from GitHub. Add the repository to your composer.json file:

{
  "repositories": [
    {
      "type": "vcs",
      "url": "[https://github.com/zteradb/zteradb-php](https://github.com/zteradb/zteradb-php)"
    }
  ],
  "require": {
    "zteradb/zteradb-php": "v1.0"
  }
}

Then, run the installation command:

composer require zteradb/zteradb-php:v2.0.0

🚀 60-Second Quick Start

<?php
require_once "vendor/autoload.php";

use ZTeraDB\Config\ZTeraDBConfig;
use ZTeraDB\Connection\ZTeraDBConnection;
use ZTeraDB\Query\ZTeraDBQuery;
use ZTeraDB\Config\ResponseDataTypes;
use ZTeraDB\Config\ENVS;

// 1. Setup Configuration
$config = new ZTeraDBConfig([
    'client_key'         => getenv('ZTERADB_CLIENT_KEY'),
    'access_key'         => getenv('ZTERADB_ACCESS_KEY'),
    'secret_key'         => getenv('ZTERADB_SECRET_KEY'),
    'database_id'        => getenv('ZTERADB_DATABASE_ID'),
    'env'                => ENVS::dev,
    'response_data_type' => ResponseDataTypes::json,
]);

// 2. Initialize Connection
$db = new ZTeraDBConnection(
    getenv("ZTERADB_HOST"),
    getenv("ZTERADB_PORT"),
    $config
);

// 3. Build ZQL Query
$query = (new ZTeraDBQuery("user"))->select();

// 4. Execute and Stream Results
foreach ($db->run($query) as $row) {
    print_r($row);
}

// 5. Close Connection
$db->close();
?>

🗂 Documentation Sections

Explore the rest of our guides to unlock the full potential of ZTeraDB:

• Configuration - Learn all available configuration options.
• Connection - Deep dive into socket connections and lifecycle management.
• Query Builder - Master building fluent ZQL queries.
• Filter Conditions - Apply advanced math and logical filters to your data.
• Examples — Copy-pasteable snippets for common use cases.
• Troubleshooting Guide — How to resolve common connection or runtime errors.
• Quickstart Guide — A streamlined, 5-minute setup guide.
• Licence — Open-source licence terms.

Licence

This project is licenced under the ZTeraDB Licence - see LICENCE file for details.