Download the PHP package mathsgod/light-db without Composer

Light-DB

Light-DB is a lightweight PHP ORM/database access layer built on top of Laminas DB, designed for modern PHP 8.2+ applications. It provides an Eloquent-like Active Record experience with support for auto-mapping, dynamic queries, relationship queries, JSON field operations, and pagination — with first-class compatibility for both MySQL 8.0 and MariaDB 10.11 / 11.4.

✨ Features

• 🚀 Modern PHP: Built on PHP 8.2+ features with type declarations and modern PHP syntax
• 🔗 Multi-Database Support: Based on Laminas DB — supports MySQL 8.0, MariaDB 10.11/11.4, PostgreSQL, SQLite, SQL Server
• 🧩 MariaDB-Aware: Detects MariaDB at runtime and adjusts column metadata (JSON detection, default-value parsing) automatically
• 📦 Eloquent-Style: Familiar Active Record pattern with an Eloquent-like API powered by illuminate/collections
• 🎯 Smart Queries: Complex conditional queries, sorting, grouping, and aggregation functions
• 📄 Pagination Support: Built-in Laminas Paginator integration
• 🔄 JSON Fields: Native JSON field operations with automatic serialization/deserialization
• 🔗 Relationship Queries: Inter-model relationship queries and dynamic property access
• ✅ CI-Tested: Automated test matrix on GitHub Actions across PHP 8.2 / 8.3 / 8.4 / 8.5 × MySQL 8.0 / MariaDB 10.11 / MariaDB 11.4

📋 Requirements

• PHP 8.2 or higher
• PDO extension
• A supported database (tested against):
  • MySQL 8.0
  • MariaDB 10.11 / 11.4

🚀 Installation

Install via Composer:

⚙️ Configuration

Create a .env file in your project root:

🎯 Basic Usage

Defining Models

CRUD Operations

Creating Records

Querying Records

Updating Records

Deleting Records

🔍 Advanced Queries

Query Conditions

Sorting and Limiting

OR / AND Logic with filters()

Use the _or and _and magic keys inside filters() to build boolean logic.

Mixing outer where() with inner _or / _and:

Nested _or and _and for deeper boolean trees:

Alternatively, the underlying Laminas\Db\Sql\Select::where() accepts a combination operator:

Tip: filters(['_or' => ...]) is generally easier to read and supports arbitrary nesting. Use the direct where(..., OP_OR) form when you need fine-grained control over a single predicate.

Aggregate Functions

📄 Pagination

🔄 JSON Field Operations

Note: MariaDB stores JSON columns as LONGTEXT with a JSON_VALID() CHECK constraint. Light-DB detects this at runtime and treats them as json data type for transparent encoding/decoding.

🔗 Relationship Queries

🛠️ Advanced Features

Declarative Filters & Sorts (Model::boot())

A model's relation-based or computed filters and sorts can be declared on the model itself instead of being registered ad-hoc from controllers. Light-DB auto-invokes the model's boot() lifecycle method the first time Model::Query() is called for the class, so registrations are guaranteed to be in place before any filter is resolved.

Override filterDefinitions() and / or orderDefinitions() to return an [name => callable] map:

After this, any caller of Schedule::Query()->filters(['Letter' => $v]) — including sub-queries from unrelated code paths — gets the right SQL, without the controller having to call RegisterFilter() first. Boot is idempotent per process per class, so multiple Query::Query() invocations don't double-register.

Inheritance via parent:::

Borrow a filter from another class:

The legacy Model::RegisterFilter() / Model::RegisterOrder() APIs are still supported and remain the right choice when the registration depends on request-scoped state (current user, request params, etc.) that the static filterDefinitions() hook cannot see. Both styles can coexist on the same model.

Collection Operations

Custom Sorting

Prefer orderDefinitions() on the model itself for new code — see Declarative Filters & Sorts.

Binding Input Parameters to Prepared Statements

Both cursor() and execute() accept an optional array $input_parameters = [] argument. These parameters are bound to the underlying Laminas\Db\Adapter\ParameterContainer and matched against the ? placeholders that Light-DB/Laminas auto-generates for where conditions. Both methods iterate the same way and return hydrated model instances.

input_parameters is a thin pass-through to the prepared statement. Use it when you want to be explicit about what gets bound:

Note: If you pass keys that don't match any ? token in the query, the database driver will reject the statement with HY093 (PDO: "number of bound variables does not match number of tokens"). The placeholder count is determined by your where/filter/join expressions — Light-DB does not invent extra ? tokens for unused parameters.

🗄️ Database Compatibility

Light-DB automatically detects MariaDB at connection time by inspecting SELECT VERSION(). Internally, this enables:

• JSON column detection — MariaDB reports json columns as longtext in INFORMATION_SCHEMA; Light-DB queries CHECK_CONSTRAINTS for json_valid() clauses to recover the real type
• Default-value parsing — MariaDB quotes string defaults (e.g. 'foo') while MySQL 8.0 does not; Light-DB normalizes both formats
• Connection setup — utf8mb4_0900_ai_ci collation is only set on MySQL 8.x

🧪 Running Tests

A .env file with valid database credentials is required (see Configuration).

✅ Continuous Integration

Tests run automatically on every push and pull request via GitHub Actions. The CI matrix covers:

• PHP: 8.2, 8.3, 8.4, 8.5
• Database: MySQL 8.0, MariaDB 10.11, MariaDB 11.4

That gives 12 parallel jobs ensuring compatibility across the supported matrix.

📊 Test Coverage

• 96 test cases
• 380 assertions
• Covers all core functionality
• Includes unit and integration tests
• Supports error handling and edge case testing

📦 Dependencies

📝 License

This project is licensed under the MIT License.

👨‍💻 Author

Raymond Chong

• Email: [email protected]
• GitHub: @mathsgod

🤝 Contributing

Issues and Pull Requests are welcome!

1. Fork the project
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📚 More Examples

Check the test files in the tests/ directory for more usage examples and best practices.