feat: initial commit of camelia/orm

Attribute-mapped Active Record ORM for MariaDB/MySQL over PDO.

- Attribute-driven metadata: TableName, PrimaryKey, AutoIncrement, Column,
  Guarded, Ignore, Required, Enum, Nullable, Length, Precision, Unique,
  UniqueGroup, Index, MaxLength.
- Relationship mapping: BelongsTo, HasOne, HasMany, BelongsToMany with
  batched eager loading and a 3-level depth limit.
- Orm entry point with fromArray, fromPdo, fromEnv and nested transactions.
- Immutable Query with Cond operators and GroupCond grouping.
- Repository read and write API, pagination, and typed exception hierarchy.
- Declares PHP >=8.3; Mago and PHPStan pin the parser to 8.3.
- MIT license.
This commit is contained in:
dgarcia committed 2026-11-15 10:14:22 -03:00
commit 66e93e3070
97 files changed
+12188

No files matched your search

+213
View File
@@ -0,0 +1,213 @@
<?php
declare(strict_types=1);
namespace Camelia\Orm\Connection;
use Camelia\Orm\Exception\ConfigurationException;
use Camelia\Orm\Exception\DatabaseException;
use PDO;
use PDOException;
use PDOStatement;
/**
* PDO-backed transport with a bounded LRU statement cache.
*
* Invariant: statements are always executed with execute(array). bindParam is never used,
* because cached statements are shared across calls.
*/
final class PdoConnection implements Connection
{
private const MAX_CACHED_STATEMENTS = 200;
/** @var array<string, PDOStatement> */
private array $statements = [];
/** @var list<string> LRU order, most recent last */
private array $lru = [];
/** @var list<string> savepoint names for nested transactions */
private array $savepoints = [];
public function __construct(
private readonly PDO $pdo,
) {
if ($pdo->getAttribute(PDO::ATTR_ERRMODE) !== PDO::ERRMODE_EXCEPTION) {
throw ConfigurationException::invalidErrorMode();
}
}
public function execute(string $sql, array $params = []): int
{
$statement = $this->prepare($sql);
try {
$statement->execute($params);
} catch (PDOException $exception) {
throw DatabaseException::fromPdoException($exception, 'write', $sql, $params);
}
return $statement->rowCount();
}
public function select(string $sql, array $params = []): array
{
$statement = $this->prepare($sql);
try {
$statement->execute($params);
$rows = $statement->fetchAll();
} catch (PDOException $exception) {
throw DatabaseException::fromPdoException($exception, 'read', $sql, $params);
}
/** @var list<array<string, mixed>> $rows */
return $rows;
}
public function scalar(string $sql, array $params = []): mixed
{
$statement = $this->prepare($sql);
try {
$statement->execute($params);
$value = $statement->fetchColumn();
} catch (PDOException $exception) {
throw DatabaseException::fromPdoException($exception, 'read', $sql, $params);
}
$statement->closeCursor();
return $value === false ? null : $value;
}
public function lastInsertId(): string
{
$id = $this->pdo->lastInsertId();
return $id === false ? '0' : $id;
}
public function begin(): void
{
if ($this->pdo->inTransaction()) {
$name = 'camelia_sp_' . count($this->savepoints);
$this->pdo->exec('SAVEPOINT ' . $name);
$this->savepoints[] = $name;
return;
}
$this->pdo->beginTransaction();
}
public function commit(): void
{
if ($this->savepoints !== []) {
$name = array_pop($this->savepoints);
$this->pdo->exec('RELEASE SAVEPOINT ' . $name);
return;
}
if ($this->pdo->inTransaction()) {
$this->pdo->commit();
}
}
public function rollBack(): void
{
if ($this->savepoints !== []) {
$name = array_pop($this->savepoints);
$this->pdo->exec('ROLLBACK TO SAVEPOINT ' . $name);
return;
}
if ($this->pdo->inTransaction()) {
$this->pdo->rollBack();
}
}
public function inTransaction(): bool
{
return $this->pdo->inTransaction();
}
public function driver(): string
{
return (string) $this->pdo->getAttribute(PDO::ATTR_DRIVER_NAME);
}
/**
* Raw PDO handle for cases the library does not cover.
*/
public function pdo(): PDO
{
return $this->pdo;
}
/**
* Clears the statement cache. Tests only.
*/
public function clearStatementCache(): void
{
$this->statements = [];
$this->lru = [];
}
public function statementCacheSize(): int
{
return count($this->statements);
}
private function prepare(string $sql): PDOStatement
{
$key = md5($sql);
$cached = $this->statements[$key] ?? null;
if ($cached instanceof PDOStatement) {
$this->touch($key);
return $cached;
}
$statement = $this->pdo->prepare($sql);
if (!$statement instanceof PDOStatement) {
throw new DatabaseException(sprintf('Unable to prepare statement: %s', $sql), $sql);
}
$this->statements[$key] = $statement;
$this->lru[] = $key;
$this->evict();
return $statement;
}
private function touch(string $key): void
{
$position = array_search($key, $this->lru, true);
if ($position !== false) {
unset($this->lru[$position]);
$this->lru = array_values($this->lru);
}
$this->lru[] = $key;
}
private function evict(): void
{
while (count($this->statements) > self::MAX_CACHED_STATEMENTS) {
$oldest = array_shift($this->lru);
if ($oldest === null) {
break;
}
unset($this->statements[$oldest]);
}
}
}