Release 0.8.0

[GuilhermeBarile]

Summary

This is the 0.8.0 modernization of objectiveweb/db. It replaces the legacy PDO-oriented internals with Doctrine DBAL, strengthens query construction and mutation safety, adds model mapping and table inheritance, and expands the project from primarily MySQL-oriented behavior to a tested SQLite/MySQL/PostgreSQL abstraction.

The documented public API is intentionally small around DB, Table, Query, Collection, Model, and Expr. This is still a pre-1.0 release and contains breaking behavioral and runtime changes from 0.7.

Database layer

• Replace direct PDO internals with Doctrine DBAL (^4.0).
• Require PHP 8.2 or newer.
• Support DSN strings and parsed connection configuration.
• Add DB::ensureConnection() and DB::reconnect() for recovering lost connections.
• Add transaction helpers with typed TransactionException failures.
• Add dedicated COUNT(*) queries for pagination totals instead of SQL_CALC_FOUND_ROWS.
• Add Expr support for explicit SQL expressions.
• Preserve table-prefix support.

Query construction and safety

• Rework SELECT/INSERT/UPDATE/DELETE generation around DBAL connections and parameter binding.
• Validate table/field identifiers before generating SQL.
• Reject raw string WHERE clauses.
• Reject unsafe UPDATE/DELETE operations without a WHERE clause.
• Add structured JOIN definitions while retaining the legacy join map.
• Support INNER, LEFT, RIGHT, FULL OUTER, and CROSS joins where supported by the database.
• Add grouped queries and aggregate/function fields.
• Add row locking with FOR UPDATE and FOR SHARE.
• Add filter handling for equality, negation, LIKE, IN, and NULL checks.
• Add database-aware identifier quoting and SQL behavior.

Table API

• Expand Table CRUD behavior and filtering.
• Add per-call joins merged with table-level joins.
• Add findBy().
• Support table subclasses through DB::table().
• Define the Table::insert() return contract as the primary-key map, e.g. ['id' => '1'], or null when the ID cannot be determined. Custom primary-key names are used as the return key.
• Remove the old CrudTrait implementation.

Models

Add optional Model mapping to tables:

• hydrate selected rows into model objects;
• accept arrays or model instances for inserts/updates;
• whitelist valid fields;
• define separate creation/update rules;
• support required/nullable fields;
• PHP filters and custom validators;
• type, enum, pattern, min, and max validation;
• throw ModelValidationException for invalid payloads.

Model mapping remains optional; tables without a model continue returning arrays.

Table inheritance

Add support for representing one logical entity across a base and child table using extends configuration.

• Split insert/update payloads between base and child fields.
• Execute multi-table writes transactionally.
• Automatically join the base table for reads.
• Resolve filters against the correct base/child table.
• Support updates/deletes using base, child, or mixed filters.
• Support custom base-table link keys.
• Keep both tables on the same logical primary key.

Exceptions

Add typed exceptions for database-level failures:

• DBException
• InvalidQueryException
• ModelValidationException
• NotFoundException
• TransactionException

Collection and Query

• Modernize Query for Doctrine DBAL result handling.
• Define Query::exec() as returning DBAL Result::rowCount() for result-set queries and DBAL affected-row counts for statement queries; result-set row-count semantics remain driver-dependent.
• Update Collection behavior and typing.
• Keep pagination metadata through total() and contentRange().
• Define Collection::render() to return the collection data array directly, with no HTTP side effects.

Testing and CI

The test suite was substantially expanded to cover CRUD, query generation, SQL behavior, models, inheritance, transactions, safety checks, joins, locks, and database-specific behavior.

GitHub Actions now runs:

• SQLite on PHP 8.2, 8.3, and 8.4;
• MySQL 8.4 on PHP 8.2, 8.3, and 8.4;
• PostgreSQL 16 on PHP 8.2, 8.3, and 8.4;
• SQLite on PHP 8.2 with the lowest compatible dependency versions, including Doctrine DBAL 4.0.0.

MySQL and PostgreSQL run as real service containers in CI. Pull requests run the suite once through the pull_request event; pushes run CI only on master to avoid duplicate PR checks.

Local multi-database testing is also available through Docker Compose and ./scripts/test-docker.sh.

The obsolete Travis CI configuration has been removed.

Compatibility

• PHP 8.2, 8.3, and 8.4 are supported and tested.
• Doctrine DBAL 4.x is supported and is part of the 0.8.x compatibility target.
• SQLite, MySQL 8.4, and PostgreSQL 16 are tested database backends.
• DB::insert() returns a scalar generated ID (string|null), while Table::insert() returns a primary-key map such as ['id' => '1'] or null.

Validation

The branch is synchronized with master and the expanded SQLite, MySQL, and PostgreSQL GitHub Actions suites are passing.

[objectivebot]

Reviewed for the v0.8.0 release. The full CI matrix is green, including lowest-compatible dependencies with Doctrine DBAL 4.0.0, Composer metadata validation, SQLite/MySQL/PostgreSQL coverage, and PHP 8.2–8.4.