Database/
├── ORM/
│   ├── Persistence/        # EntityManager, UnitOfWork, EntityPersister, ObjectHydrator, ProxyFactory, EntityRepository
│   ├── Mapping/            # ClassMetaData, MetadataFactory
│   │   └── Attribute/      # Entity, Table, Column, Id, GeneratedValue, relations, JoinColumn, JoinTable
│   ├── Query/              # QueryBuilder
│   ├── Collection/         # Collection, LazyCollection
│   ├── Platform/           # AbstractPlatform, MySQLPlatform
│   ├── Schema/             # SchemaTool
│   └── Type/               # Type, TypeRegistry
├── Migration/
│   ├── Runner/             # MigrationRunner
│   ├── Generator/          # MigrationGenerator
│   ├── Interface/          # MigrationInterface
│   ├── SchemaDiffer.php
│   └── MigrationSchemaSnapshot.php
├── Form/
│   ├── Field/              # FieldType, FormField
│   ├── Form.php
│   ├── FormBuilder.php
│   ├── FormFactory.php
│   ├── FormRenderer.php
│   └── PropertyAccessor.php
├── Access/
│   ├── Connection/         # DatabaseConnection
│   └── Introspector/       # DatabaseIntrospector
│       └── Metadata/       # ColumnMetadata, ForeignKeyMetadata, IndexMetadata
├── Pagination/
│   ├── Paginator.php
│   └── Extension/          # PaginationViewExtension (paginator_links Twig function)
├── Commands/               # CLI commands
└── DatabaseManager.php

// Injection into a controller or service
use Neo\Core\Database\ORM\Persistence\EntityManager;

$em = $container->get(EntityManager::class);

// Create and persist an entity
$user = new User();
$user->setName('Alice')->setEmail('alice@example.com');

$em->persist($user);
$em->flush(); // INSERT INTO users ...

// Retrieve an entity by its ID
$user = $em->find(User::class, 1);

// Modify and save
$user->setName('Alice Updated');
$em->flush(); // UPDATE users SET name = ? WHERE id = ?

// Delete
$em->remove($user);
$em->flush(); // DELETE FROM users WHERE id = ?

// Explicit transaction
$result = $em->wrapInTransaction(function (EntityManager $em) {
    $order = new Order();
    $em->persist($order);
    return $order;
});

// Access the UoW through the EntityManager
$uow = $em->getUnitOfWork();

// Check whether an entity is managed
$uow->isManaged($entity); // bool

// Force-register an entity as managed
$uow->registerManaged($entity, $id, $originalData);

$repo = $em->getRepository(User::class);

// Find by ID
$user = $repo->find(1);

// Find all
$users = $repo->findAll();

// Find by criteria
$users = $repo->findBy(
    criteria: ['role' => 'admin'],
    orderBy: ['name' => 'ASC'],
    limit: 10,
    offset: 0
);

// Find a single one
$user = $repo->findOneBy(['email' => 'alice@example.com']);

// Count
$count = $repo->count(['active' => true]);

// Pagination
$paginator = $repo->paginate(page: 1, perPage: 20, criteria: ['role' => 'admin'], orderBy: ['name' => 'ASC']);

// src/MyProject/Database/Repository/UserRepository.php
namespace Neo\Src\MyProject\Database\Repository;

use Neo\Core\Database\ORM\Persistence\EntityRepository;
use Neo\Src\MyProject\Database\Entity\User;

/**
 * @extends EntityRepository<User>
 */
final class UserRepository extends EntityRepository
{
    public function findAdmins(): array
    {
        return $this->findBy(['role' => 'admin'], ['name' => 'ASC']);
    }

    public function findByEmailDomain(string $domain): array
    {
        // Access to the persister for custom queries
        return $this->persister()->loadAll(['email_domain' => $domain]);
    }
}

// A proxy is a "ghost" object: its data is loaded
// only on the first access to a non-ID property.
$proxy = $em->getReference(User::class, 42);
// No SQL query here

echo $proxy->getName(); // Triggers lazy loading
// SELECT * FROM users WHERE id = 42

use Neo\Core\Database\Query\QueryBuilder;

$qb = QueryBuilder::for($db, 'users');

// SELECT with join and pagination
$rows = $qb
    ->select('u.id', 'u.name', 'p.title')
    ->join('posts p', 'p.user_id', '=', 'u.id')
    ->where('u.active', '=', true)
    ->orWhere('u.role', '=', 'admin')
    ->whereIn('u.id', [1, 2, 3])
    ->orderBy('u.name', 'ASC')
    ->limit(20)
    ->offset(0)
    ->get();

// Count
$count = QueryBuilder::for($db, 'users')
    ->where('role', '=', 'admin')
    ->count();

// Insert and retrieve the ID
$id = QueryBuilder::for($db, 'users')
    ->insertGetId(['name' => 'Bob', 'email' => 'bob@example.com']);

// Update
QueryBuilder::for($db, 'users')
    ->where('id', '=', 5)
    ->update(['name' => 'Robert']);

// Delete
QueryBuilder::for($db, 'users')
    ->where('active', '=', false)
    ->delete();

// Inspect the generated SQL
echo $qb->toSql();

$paginator = QueryBuilder::for($db, 'posts')
    ->where('published', '=', true)
    ->orderBy('created_at', 'DESC')
    ->paginate(page: 2, perPage: 10);

$paginator = $repo->paginate(page: 1, perPage: 20, criteria: ['role' => 'admin'], orderBy: ['name' => 'ASC']);

{# Basic navigation, default symbols (« / » / …) #}
{{ paginator_links(paginator) }}

{# Explicit base URL (otherwise the current request path is used) #}
{{ paginator_links(paginator, '/posts') }}

{# Custom / translated labels via the i18n module #}
{{ paginator_links(
    paginator,
    prevLabel: translate('pagination.prev'),
    nextLabel: translate('pagination.next'),
    gapLabel: translate('pagination.gap')
) }}

// Inside an entity, after hydration
$user = $em->find(User::class, 1);
$posts = $user->getPosts(); // Uninitialized LazyCollection

foreach ($posts as $post) {
    // First access: SELECT * FROM posts WHERE user_id = 1
    echo $post->getTitle();
}

use Neo\Core\Database\ORM\Mapping\Attribute\Entity;

#[Entity(repositoryClass: UserRepository::class, readOnly: false)]
final class User { }

use Neo\Core\Database\ORM\Mapping\Attribute\Table;

#[Table(name: 'app_users')]
final class User { }

use Neo\Core\Database\ORM\Mapping\Attribute\Column;

#[Column(type: 'string', name: 'full_name', length: 100, nullable: false, unique: true)]
private string $name;

use Neo\Core\Database\ORM\Mapping\Attribute\Id;
use Neo\Core\Database\ORM\Mapping\Attribute\GeneratedValue;

#[Id]
#[GeneratedValue]  // strategy: 'AUTO' by default
#[Column(type: 'integer', unsigned: true)]
private ?int $id = null;

use Neo\Core\Database\ORM\Mapping\Attribute\ManyToOne;
use Neo\Core\Database\ORM\Mapping\Attribute\JoinColumn;

#[ManyToOne(targetEntity: Category::class, inversedBy: 'products', cascade: ['persist'])]
#[JoinColumn(name: 'category_id', nullable: false, onDelete: 'CASCADE')]
private ?Category $category = null;

use Neo\Core\Database\ORM\Mapping\Attribute\OneToMany;
use Neo\Core\Database\ORM\Collection\Collection;

/** @var Collection<Post> */
#[OneToMany(targetEntity: Post::class, mappedBy: 'author', cascade: ['persist'], orphanRemoval: true)]
private Collection $posts;

// Owning side (holds the FK)
#[OneToOne(targetEntity: Profile::class, inversedBy: 'user')]
#[JoinColumn(name: 'profile_id', unique: true, nullable: true)]
private ?Profile $profile = null;

// Inverse side
#[OneToOne(targetEntity: User::class, mappedBy: 'profile')]
private ?User $user = null;

use Neo\Core\Database\ORM\Mapping\Attribute\ManyToMany;
use Neo\Core\Database\ORM\Mapping\Attribute\JoinTable;
use Neo\Core\Database\ORM\Mapping\Attribute\JoinColumn;

// Owning side
/** @var Collection<Tag> */
#[ManyToMany(targetEntity: Tag::class, inversedBy: 'articles')]
#[JoinTable(
    name: 'article_tag',
    joinColumns: [new JoinColumn(name: 'article_id')],
    inverseJoinColumns: [new JoinColumn(name: 'tag_id')]
)]
private Collection $tags;

// Inverse side
/** @var Collection<Article> */
#[ManyToMany(targetEntity: Article::class, mappedBy: 'tags')]
private Collection $articles;

<?php
declare(strict_types=1);

namespace Neo\Src\Blog\Database\Entity;

use Neo\Core\Database\ORM\Collection\Collection;
use Neo\Core\Database\ORM\Mapping\Attribute\Column;
use Neo\Core\Database\ORM\Mapping\Attribute\Entity;
use Neo\Core\Database\ORM\Mapping\Attribute\GeneratedValue;
use Neo\Core\Database\ORM\Mapping\Attribute\Id;
use Neo\Core\Database\ORM\Mapping\Attribute\ManyToOne;
use Neo\Core\Database\ORM\Mapping\Attribute\OneToMany;
use Neo\Core\Database\ORM\Mapping\Attribute\Table;
use Neo\Src\Blog\Database\Repository\PostRepository;

#[Entity(repositoryClass: PostRepository::class)]
#[Table(name: 'posts')]
final class Post
{
    #[Id]
    #[GeneratedValue]
    #[Column(type: 'integer', unsigned: true)]
    private ?int $id = null;

    #[Column(type: 'string', length: 255)]
    private string $title;

    #[Column(type: 'text', nullable: true)]
    private ?string $content = null;

    #[Column(type: 'datetime')]
    private \DateTime $createdAt;

    #[ManyToOne(targetEntity: User::class, inversedBy: 'posts')]
    private ?User $author = null;

    /** @var Collection<Comment> */
    #[OneToMany(targetEntity: Comment::class, mappedBy: 'post', orphanRemoval: true)]
    private Collection $comments;

    public function __construct()
    {
        $this->createdAt = new \DateTime();
        $this->comments  = new Collection();
    }

    public function getId(): ?int { return $this->id; }
    public function getTitle(): string { return $this->title; }
    public function setTitle(string $title): static { $this->title = $title; return $this; }
    // ...
}

use Neo\Core\Database\ORM\Type\TypeRegistry;

TypeRegistry::register(new MyCustomType());

$platform = $em->getPlatform();
$platform->quoteIdentifier('my_table'); // `my_table`
$platform->getName();                   // 'mysql'

$introspector = new DatabaseIntrospector($container);
// Or on a specific connection:
$introspector = DatabaseIntrospector::on($container, 'secondary');

foreach ($introspector->getColumns('users') as $column) {
    echo $column->getName() . ' : ' . $column->getType();
    if ($column->isNullable()) {
        echo ' (nullable)';
    }
}

foreach ($introspector->getForeignKeys('posts') as $fk) {
    echo $fk->getColumn() . ' → ' . $fk->getReferencedTable() . '.' . $fk->getReferencedColumn();
}

foreach ($introspector->getIndexes('posts') as $index) {
    echo $index->getName() . ' : ' . implode(', ', $index->getColumns());
    echo $index->isUnique() ? ' (unique)' : '';
}

$runner = new MigrationRunner($db, 'default');

// List pending migrations
$pending = $runner->getPending('/path/to/migrations');

// Run every pending migration
$runner->run('/path/to/migrations');

// Dry run (list without running)
$runner->run('/path/to/migrations', dryRun: true);

// Rollback the last batch
$runner->rollback('/path/to/migrations');

<?php
declare(strict_types=1);

/**
 * Migration: add_posts_table
 * Generated: 2026-07-28 10:00:00
 */
final class MigrationVersion_20260728_100000
{
    public function up(\Neo\Core\Database\DatabaseManager $db): void
    {
        if (!$this->tableExists($db, 'posts')) {
            $db->execute('CREATE TABLE IF NOT EXISTS `posts` (
                `id` int NOT NULL AUTO_INCREMENT,
                `title` varchar(255) NOT NULL,
                `content` text,
                `created_at` datetime NOT NULL,
                `author_id` int,
                PRIMARY KEY (`id`)
            ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci');
        }
    }

    public function down(\Neo\Core\Database\DatabaseManager $db): void
    {
        if ($this->tableExists($db, 'posts')) {
            $db->execute('DROP TABLE IF EXISTS `posts`');
        }
    }

    private function tableExists(\Neo\Core\Database\DatabaseManager $db, string $table): bool
    {
        $row = $db->fetch(
            'SELECT 1 FROM information_schema.TABLES WHERE TABLE_SCHEMA = DATABASE() AND TABLE_NAME = :table',
            ['table' => $table]
        );
        return $row !== null;
    }

    private function columnExists(\Neo\Core\Database\DatabaseManager $db, string $table, string $column): bool
    {
        $row = $db->fetch(
            'SELECT 1 FROM information_schema.COLUMNS WHERE TABLE_SCHEMA = DATABASE() AND TABLE_NAME = :table AND COLUMN_NAME = :column',
            ['table' => $table, 'column' => $column]
        );
        return $row !== null;
    }
}

$differ = new SchemaDiffer();
$diff = $differ->diff($previousSchema, $currentSchema);

// $diff contains:
// - tablesToCreate: new tables
// - tablesToDrop:   removed tables
// - tableChanges:   changes per table (added, removed, modified)

// Detect whether the diff is empty
$differ->isEmpty($diff); // bool

// Table rename candidates (by column signature)
$candidates = $differ->findTableRenameCandidates($tablesToCreate, $tablesToDrop);

// Column rename candidates
$candidates = $differ->findColumnRenameCandidates($removed, $added);

// Risky NOT NULL changes
$risks = $differ->findRiskyNotNullChanges($tablesToCreate, $tableChanges);

$schemaTool = new SchemaTool($em);

// Get the desired schema from entities
$schema = $schemaTool->getSchema([User::class, Post::class, Comment::class]);

// Get foreign keys
$fks = $schemaTool->getForeignKeys([User::class, Post::class]);

// Get indexes
$indexes = $schemaTool->getIndexes([User::class]);

$factory = $container->get(FormFactory::class);

// Simple form
$builder = $factory->create('register');
$builder
    ->add('username', 'text', ['required' => true, 'maxLength' => 50])
    ->add('email', 'email', ['required' => true])
    ->add('password', 'password', ['required' => true, 'minLength' => 8])
    ->add('role', 'select', ['choices' => ['user' => 'User', 'admin' => 'Administrator']])
    ->add('newsletter', 'checkbox', ['label' => 'Subscribe to the newsletter']);

$form = $builder->getForm();

// Form bound to an entity
$user = $em->find(User::class, 1);
$builder = $factory->createFor($user, 'edit_user');
$builder->add('name', 'text', ['required' => true]);

$form = $builder->getForm(); // Values are pre-filled from $user

// Handle a submission
$form->handleRequest($_POST);

if ($form->isSubmitted() && $form->isValid()) {
    // Data is automatically mapped onto the bound entity
    $user = $form->getEntity();
    $em->persist($user);
    $em->flush();
} else {
    // Access errors
    $errors = $form->getErrors();
    // ['email' => ['This field is required.'], ...]
}

// Access raw data
$data = $form->getData();
// ['username' => 'Alice', 'email' => 'alice@example.com', ...]

$renderer = new FormRenderer();

// Full form rendering
$html = $renderer->render($form, action: '/register', method: 'POST', attributes: ['class' => 'form-card']);

// Partial rendering
$html  = $renderer->start($form, '/register');
$html .= $renderer->field($form->getField('email'));
$html .= $renderer->field($form->getField('password'));
$html .= $renderer->end();

<form action="/register" method="POST">
   <input type="hidden" name="_csrf_token" value="abc123">

   <div class="form-group">
      <label for="email">Email</label>
      <input type="email" id="email" name="email" value="" required="required">
      <ul class="form-errors">
         <li>This field is required.</li>
      </ul>
   </div>
</form>

$db = $container->get(DatabaseManager::class);

// Query returning a single row
$row = $db->fetch('SELECT * FROM users WHERE id = :id', ['id' => 1]);

// Query returning multiple rows
$rows = $db->fetchAll('SELECT * FROM users WHERE role = ?', ['admin']);

// Execute with no result (INSERT, UPDATE, DELETE)
$db->execute('UPDATE users SET active = 1 WHERE id = ?', [42]);

// Query returning a PDOStatement object
$stmt = $db->query('SELECT COUNT(*) FROM users');

// Last inserted ID
$id = $db->lastInsertId();

// Specific connection (multi-connection)
$dbSecondary = DatabaseManager::on('secondary');

// Default connection (managed automatically by the framework)
$pdo = DatabaseConnection::getPdo();

// Named connection
$pdo = DatabaseConnection::connectTo('reporting');

// Check connection status
DatabaseConnection::isConnected();          // default connection
DatabaseConnection::isConnected('reporting'); // named connection

// Names of active connections
$names = DatabaseConnection::getConnectionNames();

return [
    'enabled' => true,
    'use' => 'default',
    'connections' => [
        'default' => [
            'driver'  => 'mysql',
            'host'    => 'localhost',
            'port'    => 3306,
            'dbname'  => 'myapp',
            'user'    => 'root',
            'pass'    => 'secret',
            'charset' => 'utf8mb4',
        ],
        'secondary' => [
            'driver'  => 'mysql',
            'host'    => 'replica.example.com',
            'port'    => 3306,
            'dbname'  => 'myapp_ro',
            'user'    => 'reader',
            'pass'    => 'secret',
            'charset' => 'utf8mb4',
        ],
    ],
];

'connections' => [
    'default' => [
        // ...
        'persistent' => true,
    ],
],

Database/Seeder/
├── SeedManager.php                         # Discovery, filtering and execution of seeders
├── Interface/
│   └── SeedInterface.php                  # Contract for a seeder
├── Attribute/
│   └── Seeder.php                         # Configuration attribute
└── Commands/
    ├── DatabaseMakeSeedCommand.php         # Seeder generator
    └── DatabaseRunSeedCommand.php          # Running seeders

namespace Neo\Core\Database\Seeder\Interface;

use Neo\Core\Database\ORM\Persistence\EntityManager;

interface SeedInterface
{
    public function run(EntityManager $entityManager): void;
}

use Neo\Core\Database\Seeder\Attribute\Seeder;

#[Seeder(order: 10, group: 'reference')]
final class CountrySeeder implements SeedInterface { ... }

$manager = new SeedManager($container);

$seeders = $manager->discover(
    '/var/www/app/src/Blog/Database/Seeder',
    'Neo\Src\Blog\Database\Seeder'
);
// [['class' => 'Neo\Src\Blog\Database\Seeder\CountrySeeder', 'order' => 10, 'group' => 'reference'], ...]

php bin/neo database:make:seed CountrySeeder --project=Blog
php bin/neo database:make:seed CountrySeeder --project=Blog --order=10 --group=reference
php bin/neo database:make:seed DemoPostSeeder --project=Blog --order=50 --group=demo
php bin/neo database:make:seed CountrySeeder --project=Blog --force   # Overwrites if it exists

# Run only the 'reference' seeders (default behavior)
php bin/neo database:run:seed --project=Blog

# Include development seeders (all groups)
php bin/neo database:run:seed --project=Blog --dev

# Run only a specific group
php bin/neo database:run:seed --project=Blog --group=demo

# Preview without running
php bin/neo database:run:seed --project=Blog --dry-run

<?php
declare(strict_types=1);

namespace Neo\Src\Blog\Database\Seeder;

use Neo\Core\Database\ORM\Persistence\EntityManager;
use Neo\Core\Database\Seeder\Attribute\Seeder;
use Neo\Core\Database\Seeder\Interface\SeedInterface;
use Neo\Src\Blog\Database\Entity\Country;

#[Seeder(order: 10, group: 'reference')]
final class CountrySeeder implements SeedInterface
{
    public function run(EntityManager $entityManager): void
    {
        $countries = [
            ['code' => 'FR', 'name' => 'France'],
            ['code' => 'DE', 'name' => 'Germany'],
            ['code' => 'ES', 'name' => 'Spain'],
        ];

        foreach ($countries as $data) {
            $country = new Country();
            $country->setCode($data['code']);
            $country->setName($data['name']);
            $entityManager->persist($country);
        }

        $entityManager->flush();
    }
}

# Generate a seeder
php bin/neo database:make:seed CountrySeeder --project=Blog --order=10

# Preview
php bin/neo database:run:seed --project=Blog --dry-run

# Run
php bin/neo database:run:seed --project=Blog

# Demo data only
php bin/neo database:run:seed --project=Blog --group=demo

php neo make:entity --project=Blog
# The tool asks interactive questions:
# - Entity name
# - Fields (type, nullable, length)
# - Relations (ManyToOne, OneToMany, ManyToMany, OneToOne)
# - Generates the entity and its repository

php neo database:create --project=Blog
# Reads database.config.php and creates the database

# Compare entities against the database and generate a migration
php neo database:orm:diff --project=Blog --name=add_posts_table

# Dry run (preview without writing)
php neo database:orm:diff --project=Blog --name=test --dry-run

# Use a specific connection
php neo database:orm:diff --project=Blog --name=secondary_update --connection=secondary

# Run pending migrations
php neo database:migration:migrate --project=Blog

# List without running
php neo database:migration:migrate --project=Blog --dry-run

php neo database:migration:rollback --project=Blog

php neo database:migration:status --project=Blog

$post = $em->find(Post::class, 1);
$author = $post->getAuthor(); // Proxy, no SQL yet
echo $author->getId();        // Access to the ID without triggering the load
echo $author->getName();      // SQL triggered here: SELECT * FROM users WHERE id = ?

$user = $em->find(User::class, 1);
$user->setName('New Alice'); // Change detected on the next flush()
$em->flush();                // UPDATE users SET name = ? WHERE id = 1