DBLayer Documentation

DBLayer is a high-performance PHP database layer for PHP ^8.4 focused on predictable SQL behavior, safe defaults, and practical performance features.

This manual is written for backend engineers who want a lightweight library that still provides:

• A fluent query builder

• Repository-level conveniences

• Multi-driver support (MySQL, PostgreSQL, SQLite)

• Read/write splitting with replica strategies

• Transaction and retry controls

• Security checks, telemetry, and profiling

How To Read This Documentation

If you are new to the project, follow this order:

1. installation for environment setup.

2. quickstart for a working end-to-end flow.

3. choosing-api to choose DB vs QueryBuilder vs Repository.

4. configuration and connections to move from local to production use.

5. table-repository for repository-oriented class workflows without ORM.

6. examples-cookbook for ready-to-use snippets across all layers.

7. query-builder and repository for day-to-day application code.

8. security and observability before deploying.

The API reference sections are intentionally method-oriented and are best used as lookup pages after reading the guides.

Getting Started

• Installation
  • Requirements
  • Driver Notes
  • Install
  • Quick Verification
  • Development Dependencies
• Quick Start
  • 1. Configure a Connection
  • 2. Create Schema and Seed Data
  • 3. Read with Query Builder
  • 4. Write with Transaction Safety
  • 5. Read with Repository API
  • 6. Pick the Right API for New Work
  • What To Do Next
  • Copy-Paste Single-File Examples
• Architecture
  • Core Components
  • Responsibility Boundaries
  • Data Flow
  • Layer Lifecycles
  • Driver Stack
  • Runtime Modules
  • Design Intent

Guides

• Configuration
  • Introduction
  • Connection Setup
  • Default Behavior
  • Important Keys
  • Read/Write Config Shape
  • Replica + Cache + Comment Defaults
  • Security Block
  • Config-Driven Hardening
  • Production Guidance
  • Recommended Production Baseline
• Connections, Replicas, and Pooling
  • Introduction
  • Connection Access
  • Connection Runtime Methods
  • Read/Write Split
  • Read Strategies
  • Strategy Behavior Summary
  • Using Multiple Database Connections
  • Pooling
  • Operational Notes
  • Pool Limitations and Fit
• Choosing DB, QueryBuilder, and Repository
  • Introduction
  • Entry Path (How Most Apps Work)
  • Quick Decision Matrix
  • Mental Model
  • Practical Scenarios
  • Repository-Style App Service Pattern
  • Laravel-Like Static Repository Facade (Still Repo Style)
  • TableRepository Scenarios
  • Common Pitfalls
  • Related Guides
• TableRepository Guide
  • Introduction
  • When to Use TableRepository
  • Minimal Setup
  • Dispatch Rules
  • Connection Control
  • Scope Boundaries
  • Practical Use Cases
  • Non-ORM Boundary
  • See Also
• Examples Cookbook
  • Introduction
  • Bootstrap Once
  • Schema + Seed
  • DB Facade Recipes
  • QueryBuilder Recipes
  • Repository Recipes
  • TableRepository Recipes
  • Observability Recipes
  • Caching Recipe
  • Connection + Replica Recipe
  • Security Recipe
  • Choosing the Right Recipe
  • Related Pages
• Query Builder
  • Introduction
  • When to Use QueryBuilder
  • Basic Select
  • Writes
  • Running SQL Queries
  • Dynamic Filtering Pattern
  • Advanced SQL
  • Reporting Scenario
  • Pagination and Streaming
  • Branching Queries Safely
  • Locks
  • See Also
• Repository
  • Introduction
  • DB vs Repository: Why and What Differs
  • Entry Flow from DB
  • When Repository Is the Better Default
  • Core Methods
  • Repository-Style App Class (Composition)
  • Laravel-Like Repository Surface (Without ORM)
  • Feature Scopes
  • Repository + QueryBuilder Together
  • Common Scenarios
  • Mapping
• Transactions
  • Introduction
  • Closure Transaction
  • Manual Transaction
  • Retry Attempts
  • Read-Only Transactions
  • Execution Budgets
  • Introspection
• Caching
  • Basic Cache
  • File Cache Adapter
  • Remember Pattern
  • Tags
  • Operational Metrics
• Security
  • Introduction
  • Security Mode
  • Mode Semantics
  • Policy Guardrails
  • Validation Coverage
  • Per-Connection Security Config
  • Transport / TLS Policy
  • Raw SQL Fragment Policy
  • Facade-Level Defaults
  • Rate Limiting and Confirmation
  • Error and Log Hygiene
• Known Limitations
  • Scope Boundaries
  • Connection and Consistency Notes
  • Performance Notes
• Observability
  • Introduction
  • Logger
  • Profiler
  • Facade Listener
  • Telemetry
  • Telemetry Exports
  • Long Query Threshold Hook
• Events and Helpers
  • Events
  • Database Event Payloads
  • Helpers
  • Helper Philosophy
• Benchmarks
  • Purpose
  • Commands
  • Report Interpretation
  • Do Not Assume Feature Speedups
  • Chart Output

API Reference

• API: DB Facade
  • Role in the 3-Layer API
  • Connection Methods
  • Raw SQL Methods
  • Builder and Repository
  • Transactions
  • Execution Controls
  • Observability and Utility
  • Long-Running Worker Note
• API: TableRepository
  • Required/Optional Static Properties
  • Core Methods
  • Customization Hooks
  • Scope Pattern
  • Connection Pattern
  • DB Interface Access
  • Example
  • Non-ORM Scope
• API: QueryBuilder
  • Select/Read
  • Filters
  • Join and Set Operations
  • CTE
  • Writes
  • Pagination/Streaming
  • Other
• API: Repository
  • Read APIs
  • Pagination/Streaming
  • Write APIs
  • Scopes and Features
  • Hooks and Mapping
• API: ConnectionConfig
  • Factory and Access
  • Read/Write Split
  • Statement Cache + Query Comment
  • Security
  • Core
• API: Driver Capabilities
  • Fields
  • Built-in Driver Matrix

Source

• GitHub: infocyph/DBLayer

• Package: https://packagist.org/packages/infocyph/dblayer