documentation

PDOdb Documentation

Complete documentation for the PDOdb library - a lightweight, framework-agnostic PHP database library providing a unified API across MySQL, PostgreSQL, and SQLite.

📖 Table of Contents

Getting Started

• Installation - Install via Composer
• Configuration - Database configuration
• First Connection - Your first connection
• Hello World - Simple example

Core Concepts

• Connection Management - Single and pooled connections
• Query Builder Basics - Fluent API overview
• Parameter Binding - Prepared statements and security
• Dialect Support - Database differences

Query Builder

• SELECT Operations - SELECT, FROM, WHERE, JOIN
• Data Manipulation - INSERT, UPDATE, DELETE, REPLACE
• Filtering Conditions - WHERE, HAVING, complex conditions
• Joins - JOIN types and usage
• Aggregations - GROUP BY, HAVING, aggregates
• Ordering & Pagination - ORDER BY, LIMIT, OFFSET
• Subqueries - Subqueries and EXISTS
• Raw Queries - Raw SQL with binding

JSON Operations

• JSON Basics - Creating and storing JSON
• JSON Querying - Querying JSON data
• JSON Filtering - JSON path filtering
• JSON Modification - Updating JSON values
• JSON Aggregations - JSON functions and operations

Advanced Features

• Transactions - Transaction management
• Table Locking - Lock tables
• Batch Processing - batch(), each(), cursor()
• Bulk Operations - insertMulti, bulk updates
• Upsert Operations - onDuplicate/INSERT...ON CONFLICT
• File Loading - CSV/XML loaders
• Connection Retry - Retry mechanism
• Query Analysis - EXPLAIN, EXPLAIN ANALYZE

Error Handling

• Exception Hierarchy - Exception types
• Error Codes - DbError constants
• Retry Logic - Building retry logic
• Logging - Query and error logging
• Monitoring - Error tracking and alerting

Helper Functions

• Core Helpers - raw(), escape(), config()
• String Helpers - concat(), upper(), lower()
• Numeric Helpers - inc(), dec(), abs()
• Date Helpers - now(), curDate()
• NULL Helpers - isNull(), ifNull()
• Comparison Helpers - like(), between(), in()
• JSON Helpers - jsonObject(), jsonArray()
• Aggregate Helpers - count(), sum(), avg()
• Export Helpers - toJson(), toCsv(), toXml()

Best Practices

• Security - SQL injection prevention
• Performance - Optimizing queries
• Memory Management - Handling large datasets
• Code Organization - Structuring your code
• Common Pitfalls - Mistakes to avoid

Reference

• API Reference - Complete API documentation
• Query Builder Methods - All QueryBuilder methods
• PdoDb Methods - All PdoDb methods
• Helper Functions Reference - All helper functions
• Dialect Differences - Database-specific differences

Cookbook

• Common Patterns - Reusable code patterns
• Real-World Examples - Complete app examples
• Migration Guide - Migrating from other libraries
• Troubleshooting - Common issues and solutions

🚀 Quick Start

composer require tommyknocker/pdo-database-class

use tommyknocker\pdodb\PdoDb;
use tommyknocker\pdodb\helpers\Db;

$db = new PdoDb('mysql', [
    'host' => 'localhost',
    'username' => 'user',
    'password' => 'pass',
    'dbname' => 'mydb'
]);

$users = $db->find()
    ->from('users')
    ->where('age', 18, '>')
    ->andWhere(Db::jsonContains('tags', 'php'))
    ->orderBy('created_at', 'DESC')
    ->limit(10)
    ->get();

📚 Key Features

• Fluent Query Builder - Intuitive chainable API
• Cross-Database Support - Works with MySQL, PostgreSQL, SQLite
• JSON Operations - Unified JSON API across all databases
• Prepared Statements - Automatic parameter binding for security
• Transactions - Full transaction support
• Batch Processing - Handle large datasets efficiently
• Connection Pooling - Manage multiple connections
• Comprehensive Error Handling - Detailed exception hierarchy
• Zero Dependencies - Lightweight and fast
• Well Tested - Comprehensive test coverage
• Type Safe - PHPStan level 8 compliant

💡 Navigation Tips

• New to PDOdb? Start with Installation
• Building queries? See SELECT Operations
• Working with JSON? See JSON Basics
• Performance issues? See Performance
• Need a quick reference? See API Reference
• Troubleshooting? See Troubleshooting

📖 Version

This documentation corresponds to PDOdb version 2.x.

🤝 Contributing

Found an issue or have a suggestion? Please open an issue on GitHub.

📄 License

This library is open source. See the LICENSE file for details.