Download the PHP package ascetic-soft/rowcast without Composer

Rowcast

Lightweight DataMapper over PDO for PHP 8.4+.

Rowcast maps database rows to DTOs and back using reflection, supports explicit/auto mapping, type conversion, and includes a fluent query builder with dialect-aware UPSERT.

Documentation: English | Русский | LLM/Context7

Requirements

• PHP >= 8.4
• ext-pdo

Installation

Quick Start

Core Concepts

Rowcast supports two mapping styles:

• Auto mapping — pass class-string for reads and table name for writes. Names are converted via NameConverterInterface (default: SnakeCaseToCamelCase).
• Explicit mapping — pass Mapping to control table name, column/property pairs, and ignored properties.

Auto Mapping

Table name is derived from DTO class name for reads:

Column/property conversion (default):

Explicit Mapping

Use Mapping::explicit(...) when only declared columns must be used:

Notes:

• Mapping is currently mutable and configured in place.
• Prefer building it once during setup and then reusing it as configuration.
• Avoid mutating the same Mapping instance after it is already shared across multiple operations or services.

Connection

Connection wraps PDO and provides query helpers, transaction API, nested transaction support (savepoints), and query-builder factory.

Create Connection

Raw Queries

Query Events

Register lightweight listeners to observe SQL execution.

Transactions

Nested mode creates savepoints for inner transactions.

DataMapper API

Main methods:

• insert(string|Mapping $target, object $dto): void
• batchInsert(string|Mapping $target, array $dtos, ?int $maxBindParameters = null): void
• update(string|Mapping $target, object $dto, array $where): int
• batchUpdate(string|Mapping $target, array $dtos, array $identityProperties, ?int $maxBindParameters = null): void
• delete(string|Mapping $target, array $where): int
• findAll(string|Mapping $target, array $where = [], array $orderBy = [], ?int $limit = null, ?int $offset = null): array
• iterateAll(string|Mapping $target, array $where = [], array $orderBy = [], ?int $limit = null, ?int $offset = null): iterable
• findOne(string|Mapping $target, array $where = []): ?object
• save(string|Mapping $target, object $dto, string ...$identityProperties): void
• upsert(string|Mapping $target, object $dto, string ...$conflictProperties): int
• batchUpsert(string|Mapping $target, array $dtos, array $conflictProperties, ?int $maxBindParameters = null): void
• hydrate(...), hydrateAll(...), extract(...)

CRUD Example

save(...) Example

save(...) checks row existence by identity columns, then performs insert or update.

Notes:

• save(...) is a convenience API and does a read-before-write flow.
• It does not require a database conflict constraint to exist.
• It may use two SQL statements for one logical save operation.
• Prefer upsert(...) when your database and schema support conflict handling and write-path efficiency matters.

upsert(...) Example

Batch operations

batchInsert and batchUpsert automatically split large input into chunks based on DB parameter limits (for example, SQLite: 999 bind params), while executing all chunks inside one transaction.

Advanced where in DataMapper

DataMapper passes where arrays to the same QueryBuilder condition engine, so advanced operators are available there as well:

Type Conversion

Rowcast converts DB values to declared PHP property types on hydrate, and PHP values to DB-safe values on extract/write.

Built-in converters:

• ScalarConverter (int, float, string)
• BoolConverter (bool <-> 0/1)
• DateTimeConverter (DateTimeInterface <-> formatted UTC string)
• JsonConverter (array <-> JSON)
• EnumConverter (BackedEnum <-> backing value)

Custom Type Converter

Implement TypeConverterInterface and pass a custom registry to DataMapper:

Custom Name Converter

Implement NameConverterInterface and pass it to DataMapper:

Query Builder

Connection::createQueryBuilder() provides a fluent SQL builder.

SELECT

For pagination, use:

• setOffset(int $offset) — start row
• setLimit(int $limit) — max rows

You can also pass associative arrays to where(), andWhere(), and orWhere():

array predicates are converted to field = :param expressions joined by AND:

• where(['a' => 1, 'b' => 2]) -> a = :w_a AND b = :w_b
• andWhere(['a' => 1]) appends another AND block
• orWhere(['a' => 1]) wraps previous predicate: (prev OR a = :w_a)

Parameter names are generated automatically and made unique (:w_id, :w_id_1, ...).

Supported array operators:

Operator reference:

Notes:

• Empty IN array compiles to 1 = 0 (always false).
• Empty NOT IN array compiles to 1 = 1 (always true).
• ILIKE and NOT ILIKE are PostgreSQL-specific.
• BackedEnum values are normalized to backing scalar values in WHERE parameters (including IN / NOT IN arrays).

Dialect-specific operator support:

Base set for all dialects: >, >=, <, <=, LIKE, NOT LIKE.

OR Conditions

You can compose OR logic in two ways.

Method-based OR groups:

Combine with existing filters:

Nested-key style in one array:

OR composition reference:

INSERT / UPDATE / DELETE

UPSERT

Upsert is compiled via SQL dialects:

• MysqlDialect
• PostgresDialect
• SqliteDialect
• GenericDialect (throws for unsupported UPSERT)

WHERE array operator support is also dialect-aware (for example, ILIKE/NOT ILIKE only for PostgreSQL).

Architecture

Development

License

MIT