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

+286
View File
@@ -0,0 +1,286 @@
<?php
declare(strict_types=1);
namespace Camelia\Orm\Metadata;
use Camelia\Orm\Attribute\AutoIncrement;
use Camelia\Orm\Attribute\BelongsTo;
use Camelia\Orm\Attribute\BelongsToMany;
use Camelia\Orm\Attribute\Column;
use Camelia\Orm\Attribute\Enum;
use Camelia\Orm\Attribute\Guarded;
use Camelia\Orm\Attribute\HasMany;
use Camelia\Orm\Attribute\HasOne;
use Camelia\Orm\Attribute\Ignore;
use Camelia\Orm\Attribute\Index;
use Camelia\Orm\Attribute\MaxLength;
use Camelia\Orm\Attribute\Nullable;
use Camelia\Orm\Attribute\PrimaryKey;
use Camelia\Orm\Attribute\Required;
use Camelia\Orm\Attribute\TableName;
use Camelia\Orm\Exception\MetadataException;
use Camelia\Orm\Model;
use Camelia\Orm\Support\NameConverter;
use ReflectionClass;
use ReflectionNamedType;
use ReflectionProperty;
/**
* Builds ClassMetadata from a model class through reflection.
*
* @internal
*/
final class MetadataFactory
{
/**
* @param class-string<\Camelia\Orm\Model> $class
*/
public function forClass(string $class): ClassMetadata
{
if (!class_exists($class) || !is_subclass_of($class, Model::class)) {
throw MetadataException::notAModel($class);
}
$reflection = new ReflectionClass($class);
$tableName = $reflection->getAttributes(TableName::class)[0] ?? null;
if ($tableName === null) {
throw MetadataException::missingTableName($class);
}
/** @var TableName $table */
$table = $tableName->newInstance();
if (trim($table->name) === '') {
throw MetadataException::missingTableName($class);
}
$properties = [];
$primaryKeys = [];
$columnOwners = [];
foreach ($reflection->getProperties(ReflectionProperty::IS_PUBLIC) as $property) {
if ($property->isStatic()) {
continue;
}
$declaring = $property->getDeclaringClass()->getName();
if ($declaring !== $class && $declaring === Model::class) {
continue;
}
$metadata = $this->buildProperty($class, $reflection, $property);
if (isset($columnOwners[$metadata->column])) {
throw MetadataException::duplicateColumn(
$class,
$metadata->column,
$columnOwners[$metadata->column],
$metadata->name,
);
}
$columnOwners[$metadata->column] = $metadata->name;
$properties[$metadata->name] = $metadata;
if ($metadata->primaryKey) {
$primaryKeys[] = $metadata->name;
}
}
if (count($primaryKeys) !== 1) {
throw MetadataException::primaryKeyCount($class, count($primaryKeys));
}
$primaryKey = $primaryKeys[0];
$primaryKeyProperty = $properties[$primaryKey] ?? null;
if ($primaryKeyProperty === null) {
throw MetadataException::unknownProperty($class, $primaryKey);
}
return new ClassMetadata(
$class,
$table->name,
$primaryKey,
$primaryKeyProperty->column,
$properties,
);
}
/**
* @param class-string<\Camelia\Orm\Model> $class
* @param ReflectionClass<object> $reflection
*/
private function buildProperty(
string $class,
ReflectionClass $reflection,
ReflectionProperty $property,
): PropertyMetadata {
$name = $property->getName();
$type = $property->getType();
if (!$type instanceof ReflectionNamedType) {
throw MetadataException::missingType($class, $name);
}
$relation = $this->buildRelation($class, $reflection, $property);
$columnAttribute = $property->getAttributes(Column::class)[0] ?? null;
$column = $columnAttribute !== null
? $columnAttribute->newInstance()->name
: NameConverter::camelToSnake($name);
if (preg_match('/[^\x20-\x7E]/', $column) === 1) {
throw MetadataException::nonAsciiColumn($class, $name, $column);
}
$enumAttribute = $property->getAttributes(Enum::class)[0] ?? null;
$enumClass = $enumAttribute !== null ? $enumAttribute->newInstance()->class : null;
if ($relation !== null) {
$this->assertRelationShape($class, $property, $relation);
}
$maxLength = $property->getAttributes(MaxLength::class)[0] ?? null;
return new PropertyMetadata(
name: $name,
column: $column,
type: $enumClass ?? $type->getName(),
enumClass: $enumClass,
relation: $relation,
declaringClass: $class,
constraint: new Constraint(
nullable: $type->allowsNull() || $property->getAttributes(Nullable::class) !== [],
ignored: $property->getAttributes(Ignore::class) !== [] || $relation !== null,
guarded: $property->getAttributes(Guarded::class) !== [],
primaryKey: $property->getAttributes(PrimaryKey::class) !== [],
autoIncrement: $property->getAttributes(AutoIncrement::class) !== [],
required: $property->getAttributes(Required::class) !== [],
indexed: $property->getAttributes(Index::class) !== [],
maxLength: $maxLength !== null ? $maxLength->newInstance()->value : null,
),
);
}
/**
* @param class-string<\Camelia\Orm\Model> $class
* @param ReflectionClass<object> $reflection
*/
private function buildRelation(
string $class,
ReflectionClass $reflection,
ReflectionProperty $property,
): ?RelationMetadata {
$name = $property->getName();
$belongsTo = $property->getAttributes(BelongsTo::class)[0] ?? null;
if ($belongsTo !== null) {
/** @var BelongsTo $attribute */
$attribute = $belongsTo->newInstance();
return new RelationMetadata(
RelationMetadata::KIND_BELONGS_TO,
$this->resolveRelatedClass($class, $reflection, $attribute->related, $name),
$attribute->foreignKey,
);
}
$hasOne = $property->getAttributes(HasOne::class)[0] ?? null;
if ($hasOne !== null) {
/** @var HasOne $attribute */
$attribute = $hasOne->newInstance();
return new RelationMetadata(
RelationMetadata::KIND_HAS_ONE,
$this->resolveRelatedClass($class, $reflection, $attribute->related, $name),
$attribute->foreignKey,
);
}
$hasMany = $property->getAttributes(HasMany::class)[0] ?? null;
if ($hasMany !== null) {
/** @var HasMany $attribute */
$attribute = $hasMany->newInstance();
return new RelationMetadata(
RelationMetadata::KIND_HAS_MANY,
$this->resolveRelatedClass($class, $reflection, $attribute->related, $name),
$attribute->foreignKey,
);
}
$belongsToMany = $property->getAttributes(BelongsToMany::class)[0] ?? null;
if ($belongsToMany !== null) {
/** @var BelongsToMany $attribute */
$attribute = $belongsToMany->newInstance();
return new RelationMetadata(
RelationMetadata::KIND_BELONGS_TO_MANY,
$this->resolveRelatedClass($class, $reflection, $attribute->related, $name),
'',
$attribute->through,
$attribute->foreignPivotKey,
$attribute->relatedPivotKey,
);
}
return null;
}
/**
* @param class-string<\Camelia\Orm\Model> $class
* @param ReflectionClass<object> $reflection
* @return class-string<\Camelia\Orm\Model>
*/
private function resolveRelatedClass(
string $class,
ReflectionClass $reflection,
string $related,
string $property,
): string {
if (class_exists($related) && is_subclass_of($related, Model::class)) {
return $related;
}
$namespace = $reflection->getNamespaceName();
$candidate = $namespace === '' ? $related : $namespace . '\\' . $related;
if (class_exists($candidate) && is_subclass_of($candidate, Model::class)) {
return $candidate;
}
throw MetadataException::unknownRelatedClass($class, $property, $related);
}
private function assertRelationShape(
string $class,
ReflectionProperty $property,
RelationMetadata $relation,
): void {
$name = $property->getName();
$type = $property->getType();
if (!$type instanceof ReflectionNamedType) {
throw MetadataException::invalidRelationProperty($class, $name);
}
$isArray = $type->getName() === 'array';
if ($relation->isToMany() && !$isArray) {
throw MetadataException::invalidRelationProperty($class, $name);
}
if (!$relation->isToMany() && (!$type->allowsNull() || $isArray)) {
throw MetadataException::invalidRelationProperty($class, $name);
}
}
}