Introduction

Hector ORM is a lightweight, framework-agnostic PHP ORM — designed to be modular, fast, and expressive. It draws inspiration from existing ORM concepts, while promoting freedom of structure and strong typing.

Requirements

• PHP 8.0+
• PDO extension
• Database driver (e.g., pdo_mysql, pdo_sqlite)

What is an ORM?

Object-relational mapping (ORM, O/RM, and O/R mapping tool!) in computer science is a programming technique for converting data between incompatible type systems using object-oriented programming languages. This creates, in effect, a “virtual object database” that can be used from within the programming language.

— Wikipedia

Choose your style

You can manage entities in multiple ways:

• Classic entities: define PHP properties explicitly and Hector ORM handles mapping.
• Magic entities: rely on Hector ORM dynamic behavior using PHP’s magic methods.
• Roll your own 🧪: create a custom Mapper if you want total control over mapping logic.

Why Hector ORM?

DBMS compatibility

Quick start

1. Installation

Install with Composer:

composer require hectororm/hectororm

2. Create a database connection

use Hector\Connection\Connection;

$connection = new Connection(
    dsn: 'mysql:host=localhost;dbname=my_database',
    username: 'user',
    password: 'pass',
);

3. Boot the ORM

use Hector\Orm\OrmFactory;

$orm = OrmFactory::orm(
    options: [
        'schemas' => ['my_database'], // Your database name(s)
    ],
    connection: $connection,
);

The schemas option tells Hector ORM which database(s) to introspect at boot time. It will read the table structure and cache the metadata for entity mapping.

4. Define entities

Entity classes map to database tables. By default, the class name is converted to snake_case to find the table:

use Hector\Orm\Attributes as Orm;
use Hector\Orm\Entity\MagicEntity;

// Maps to table "foo"
#[Orm\HasOne(Bar::class, 'bar')]
class Foo extends MagicEntity {}

// Maps to table "bar"
#[Orm\BelongsTo(Foo::class, 'foo')]
class Bar extends MagicEntity {}

5. Use the ORM

$foo = Foo::findOrFail(1); // Find a Foo entity by primary key
$bar = $foo->bar;          // Access the related Bar entity (lazy loaded)

echo $bar->field;          // Access a field from the related Bar

Explore the ecosystem

You’re now ready to build with Hector ORM. Here is a guide to the documentation:

ORM

• Entities — Define your data models as PHP classes (Magic or Classic)
• Relationships — HasOne, HasMany, BelongsTo, ManyToMany
• Builder — Query, filter and paginate entities
• Events — Hook into the entity lifecycle (save, delete)
• Advanced configuration — Table mapping, column types, hidden fields
• Cache — Schema caching for production

Standalone components

Each component can be used independently of the ORM:

• Collection — Typed and lazy collections for data manipulation
• Connection — PDO wrapper with read/write separation and logging
• Data Types — Type casting between database and PHP (DateTime, Enum, JSON, UUID…)
• Query Builder — Fluent SQL query building
• Schema — Database introspection (tables, columns, indexes, foreign keys)
• Plan — DDL operations builder (CREATE/ALTER/DROP TABLE)
• Migration — Database migration runner with providers and trackers
• Pagination — Offset, cursor and range pagination with PSR-7

Going further

• Architecture — Package overview, dependency graph, and design philosophy
• Berlioz Framework — First-class integration with Berlioz Framework
• Framework integration — How to integrate Hector ORM into your own framework