Download the PHP package shibudb-org/shibudb-client-php without Composer

shibudb-client-php

ShibuDb client library for PHP

ShibuDb PHP Client

A comprehensive PHP client for ShibuDb database that supports authentication, key-value operations, vector similarity search, space management, and connection pooling. Compatible with PHP 5.6+.

Features

• 🔐 Authentication & User Management: Secure login with role-based access control
• 🔑 Key-Value Operations: Traditional key-value storage with PUT, GET, DELETE operations
• 🧮 Vector Similarity Search: Advanced vector operations with multiple index types
• 🗂️ Space Management: Create, delete, and manage different storage spaces
• 🛡️ Error Handling: Comprehensive error handling with custom exceptions
• 📊 Connection Management: Automatic connection handling with destructors
• 🔗 Connection Pooling: High-performance connection pooling for concurrent operations

Installation

Prerequisites

1. ShibuDb Server: Ensure the ShibuDb server is running

2. PHP Requirements:
   • PHP 5.6 or higher
   • No external PHP extensions required (uses built-in stream_socket_client, json_encode, json_decode)

Setup

Composer (Recommended)

Then in your PHP code:

Manual Installation

1. Copy the client file to your project:

2. Include the client:

Quick Start

Basic Connection and Authentication

Convenience Function

Connection Pooling

Key-Value Operations

Vector Operations

API Reference

ShibuDbClient

Constructor

Authentication

Space Management

Key-Value Operations

Vector Operations

User Management (Admin Only)

Data Models

User Array

Exceptions

• ShibuDbException: Base exception for all client errors
• ShibuDbAuthenticationError: Raised when authentication fails
• ShibuDbConnectionError: Raised when connection fails
• ShibuDbQueryError: Raised when query execution fails
• ShibuDbPoolExhaustedError: Raised when connection pool is exhausted

Examples

Complete Example

Error Handling

Advanced Usage

Running Examples

Simple Test

Comprehensive Examples

Connection Pooling Examples

Comprehensive Connection Pooling Tests

Connection Pooling

The ShibuDb client supports connection pooling for high-performance concurrent operations. Connection pooling provides:

• Connection Reuse: Efficiently reuse database connections
• Concurrent Operations: Support for multiple simultaneous operations
• Automatic Health Checks: Health monitoring of connections
• Configurable Pool Size: Adjustable minimum and maximum pool sizes
• Timeout Handling: Configurable connection acquisition timeouts

Pool Configuration

Using Connection Pools

Pool Statistics

Error Handling with Pools

Engine Types

Key-Value Engine

• Traditional key-value storage
• Supports PUT, GET, DELETE operations
• No dimension required

Vector Engine

• Vector similarity search
• Multiple index types:
  • Flat: Exact search (default)
  • HNSW: Hierarchical Navigable Small World
  • IVF: Inverted File Index
  • IVF with PQ: Product Quantization
• Distance metrics:
  • L2: Euclidean distance (default)
  • IP: Inner product
  • COS: Cosine similarity

Security

• Authentication Required: All operations require valid credentials
• Role-Based Access: Admin and user roles with different permissions
• Space-Level Permissions: Read/write permissions per space
• Connection Security: TCP-based communication with timeout handling

PHP 5.6 Compatibility

This client is designed for PHP 5.6+ compatibility:

• No scalar type hints (PHP 7+ feature)
• No return type declarations (PHP 7+ feature)
• No null coalescing operator (??) (PHP 7+ feature)
• Uses array() syntax for clarity
• Compatible with json_decode() strictness in PHP 5.6
• Uses built-in PHP functions only (no external dependencies)

Troubleshooting

Common Issues

1. Connection Failed

   • Ensure ShibuDb server is running: sudo shibudb start 4444
   • Check server port and host settings
   • Verify firewall settings
   • Check PHP error logs for connection errors

2. Authentication Failed

   • Verify username and password
   • Ensure user exists in the system
   • Check user permissions

3. Space Not Found

   • Use listSpaces() to see available spaces
   • Create space before using: createSpace()
   • Use useSpace() to switch to a space

4. Vector Dimension Mismatch

   • Ensure vector dimension matches space dimension
   • Check space creation parameters
   • Verify vector format (array of floats)
5. JSON Parsing Errors
   • Check PHP version compatibility (PHP 5.6+)
   • Verify JSON response format from server
   • Check for special characters in data

Debug Mode

Enable PHP error reporting:

Running Tests

Tests mirror the Python client test structure:

Contributing

1. Fork the repository
2. Create a feature branch
3. Add tests for new functionality
4. Ensure PHP 5.6+ compatibility
5. Submit a pull request

License

This client is provided as-is for use with ShibuDb database.