README

PaperORM is a PHP ORM designed for projects requiring a lightweight yet performant object-relational mapping solution.

📖 Documentation

• English
• Français

English

PaperORM is a PHP ORM designed for projects requiring a lightweight yet performant object-relational mapping solution. Specifically developed for PHP 7.4 and above, it positions itself as a lighter alternative to existing solutions.

At just 5MB compared to Doctrine's 75MB with dependencies, PaperORM offers the essential features of a modern ORM while maintaining a minimal footprint. It includes:

• Database schema management
• Migration system
• Repository pattern

Installation

PaperORM is available via Composer and installs in seconds.

📦 Via Composer (recommended)

composer require michel/paper-orm

🔧 Minimal Configuration

Create a simple configuration file to connect PaperORM to your database:

<?php
require_once 'vendor/autoload.php';

use Michel\PaperORM\EntityManager;
use Michel\PaperORM\PaperConfiguration;

// --- Basic SQLite configuration ---
$configuration = PaperConfiguration::fromArray([
    'driver' => 'sqlite',
    'user' => null,
    'password' => null,
    'memory' => true
], false); // Set to true to enable debug mode (logs queries and ORM operations)

// Basic configuration MySQL/Mariadb
$configuration = PaperConfiguration::fromArray([
            'driver' => 'mariadb',
            'host' => '127.0.0.1',
            'port' => 3306,
            'dbname' => 'paper_orm_test',
            'user' => 'root',
            'password' => 'root',
            'charset' => 'utf8mb4',
], false);  // Set to true to enable debug mode (logs queries and ORM operations)

// --- Optional event listener registration ---
// Called automatically before any entity creation
$configuration->withListener(PreCreateEvent::class, new App\Listener\PreCreateListener());

// --- Optional SQL logger ---
// Use any PSR-3 compatible logger (e.g. Monolog) to log all executed queries
$configuration->withLogger(new Monolog());

$em = EntityManager::createFromConfig($configuration);

✅ PaperORM is now ready to use!

Note: PDO and corresponding database extensions must be enabled (pdo_mysql, pdo_sqlite, etc.).

Basic Usage

Note: The repository attribute/method is optional. If none is defined, a dummy repository will be automatically generated.

Defining an Entity

PHP 7.4 < 8

use Michel\PaperORM\Entity\EntityInterface;
use Michel\PaperORM\Mapping\{PrimaryKeyColumn, StringColumn, BoolColumn, DateTimeColumn, OneToMany, JoinColumn};

class User implements EntityInterface
{
    private ?int $id = null;
    private string $name;
    private string $email;
    private bool $isActive = true;
    private \DateTime $createdAt;
    
    public static function getTableName(): string 
    {
        return 'users';
    }
    
    public static function columnsMapping(): array
    {
        return [
            (new PrimaryKeyColumn())->bindProperty('id'),
            (new StringColumn())->bindProperty('name'),
            (new StringColumn())->bindProperty('email'),
            (new BoolColumn('is_active'))->bindProperty('isActive'), // 'is_active' is the column name
            (new DateTimeColumn('created_at'))->bindProperty('createdAt') // 'created_at' is the column name
        ];
    }
    
    // Getters/Setters...
}

PHP 8+ with attributes

use Michel\PaperORM\Entity\EntityInterface;
use Michel\PaperORM\Mapping\{PrimaryKeyColumn, StringColumn, BoolColumn, DateTimeColumn, OneToMany, JoinColumn};

#[Entity(table : 'user', repository : null)]
class User implements EntityInterface
{
    #[PrimaryKeyColumn]
    private ?int $id = null;
    #[StringColumn]
    private string $name;
    #[StringColumn]
    private string $email;
    #[BoolColumn(name: 'is_active')]
    private bool $isActive = true;
    #[DateTimeColumn(name: 'created_at')]
    private \DateTime $createdAt;
   
    
    // Getters/Setters...
}

CRUD Operations

Fetching Entities:

// Get user by ID
$user = $entityManager->getRepository(User::class)->find(1);

// Filtered query
$users = $entityManager->getRepository(User::class)
    ->findBy()
    ->where('isActive', true)
    ->orderBy('name', 'ASC')
    ->limit(10)
    ->toArray();

Insert/Update:

$newUser = new User();
$newUser->setName('Jean Dupont')
        ->setEmail('jean@example.com');

$entityManager->persist($newUser);
$entityManager->flush();

Delete:

$user = $entityManager->getRepository(User::class)->find(1);
$entityManager->remove($user);
$entityManager->flush();

Entity Relationships

// OneToMany relationship
class Article 
{
    // IF PHP >= 8
    #[\Michel\PaperORM\Mapping\OneToMany(Comment::class, 'article')] 
    private \Michel\PaperORM\Collection\ObjectStorage $comments;
    
    public function __construct() {
        $this->comments = new ObjectStorage();
    }
    
    // ...
    public static function columnsMapping(): array
    {
        return [
            new OneToMany('comments', Comment::class, 'article')
        ];
    }
}

// Fetch with join
$articleWithComments = $entityManager->getRepository(Article::class)
    ->find(1)
    ->with('comments')
    ->toObject();

Result Formats

// Associative array
$userArray = $repository->find(1)->toArray();

// Entity object
$userObject = $repository->find(1)->toObject();

// Object collection
$activeUsers = $repository->findBy()
    ->where('isActive', true)
    ->toObject();

PaperORM offers a simple API while covering the essential needs of a modern ORM.

Beta Version - Contribute to Development

PaperORM is currently in beta version and actively evolving. We invite interested developers to:

🐞 Report Bugs

If you encounter issues, open a GitHub issue detailing:

• Context
• Reproduction steps
• Expected vs. actual behavior

💡 Suggest Improvements

Ideas for:

• Performance optimization
• API improvements
• New features

📖 Contribute to Documentation

Complete documentation is being written. You can:

• Fix errors
• Add examples
• Translate sections

Note: This version is stable for development use but requires additional testing for production.

Active development continues - stay tuned for updates!

Français

PaperORM est un ORM PHP conçu pour les projets qui nécessitent une solution de mapping objet-relationnel légère et performante. Développé spécifiquement pour PHP 7.4 et versions ultérieures, il se positionne comme une alternative plus légère aux solutions existantes.

Avec seulement 3Mo contre 75Mo pour Doctrine avec ses dépendances, PaperORM propose les fonctionnalités essentielles d'un ORM moderne tout en conservant une empreinte minimale. Il intègre notamment :

• La gestion des schémas de base de données
• Un système de migrations
• Le pattern Repository

Installation

PaperORM est disponible via Composer et s'installe en quelques secondes.

📦 Via Composer (recommandé)

composer require michel/paper-orm

🔧 Configuration minimale

Créez un fichier de configuration simple pour connecter PaperORM à votre base de données :

<?php
require_once 'vendor/autoload.php';


use Michel\PaperORM\EntityManager;
use Michel\PaperORM\PaperConfiguration;

// --- Basic SQLite configuration ---
$configuration = PaperConfiguration::fromArray([
    'driver' => 'sqlite',
    'user' => null,
    'password' => null,
    'memory' => true
], false); // Mettre à true pour activer le mode debug (journalisation des requêtes et opérations ORM)

// Basic configuration MySQL/Mariadb
$configuration = PaperConfiguration::fromArray([
            'driver' => 'mariadb',
            'host' => '127.0.0.1',
            'port' => 3306,
            'dbname' => 'paper_orm_test',
            'user' => 'root',
            'password' => 'root',
            'charset' => 'utf8mb4',
], false);  // Set to true to enable debug mode (logs queries and ORM operations)

// --- Enregistrement optionnel d’un écouteur d’événement ---
// Appelé automatiquement avant chaque création d’entité
$configuration->withListener(PreCreateEvent::class, new App\Listener\PreCreateListener());

// --- Journalisation SQL optionnelle ---
// Permet de journaliser toutes les requêtes exécutées via un logger compatible PSR-3 (ex. Monolog
$configuration->withLogger(new Monolog());

$em = EntityManager::createFromConfig($configuration);

✅ PaperORM est maintenant prêt à être utilisé !

Remarque : PDO et les extensions correspondantes à votre SGBD doivent être activées (pdo_mysql, pdo_sqlite, etc.).

Utilisation de base

Note: L’attribut ou la méthode repository est facultatif. Si aucun n’est défini, un repository fictif sera généré automatiquement.

Définition d'une entité

PHP 7.4 < 8

use Michel\PaperORM\Entity\EntityInterface;
use Michel\PaperORM\Mapping\{PrimaryKeyColumn, StringColumn, BoolColumn, DateTimeColumn, OneToMany, JoinColumn};

class User implements EntityInterface
{
    private ?int $id = null;
    private string $name;
    private string $email;
    private bool $isActive = true;
    private \DateTime $createdAt;
    
    public static function getTableName(): string 
    {
        return 'users';
    }
    
    public static function columnsMapping(): array
    {
        return [
            new PrimaryKeyColumn('id'),
            new StringColumn('name'),
            new StringColumn('email'),
            new BoolColumn('isActive'),
            new DateTimeColumn('createdAt')
        ];
    }
    
    // Getters/Setters...
}

PHP 8+ avec attributs

use Michel\PaperORM\Entity\EntityInterface;
use Michel\PaperORM\Mapping\{PrimaryKeyColumn, StringColumn, BoolColumn, DateTimeColumn, OneToMany, JoinColumn};

#[Entity(table : 'user', repository : null)]
class User implements EntityInterface
{
    #[PrimaryKeyColumn]
    private ?int $id = null;
    #[StringColumn]
    private string $name;
    #[StringColumn]
    private string $email;
    #[BoolColumn(name: 'is_active')]
    private bool $isActive = true;
    #[DateTimeColumn(name: 'created_at')]
    private \DateTime $createdAt;
   
    
    // Getters/Setters...
}

Opérations CRUD

Récupération d'entités :

// Récupérer un utilisateur par ID
$user = $entityManager->getRepository(User::class)->find(1);

// Requête avec filtres
$users = $entityManager->getRepository(User::class)
    ->findBy()
    ->where('isActive', true)
    ->orderBy('name', 'ASC')
    ->limit(10)
    ->toArray();

Insertion/Mise à jour :

$newUser = new User();
$newUser->setName('Jean Dupont')
        ->setEmail('jean@example.com');

$entityManager->persist($newUser);
$entityManager->flush();

Suppression :

$user = $entityManager->getRepository(User::class)->find(1);
$entityManager->remove($user);
$entityManager->flush();

Relations entre entités

// Relation OneToMany
class Article 
{
    // IF PHP >= 8
    #[\Michel\PaperORM\Mapping\OneToMany(Comment::class, 'article')] 
    private \Michel\PaperORM\Collection\ObjectStorage $comments;
    
    public function __construct() {
        $this->comments = new ObjectStorage();
    }
    
    // ...
    public static function columnsMapping(): array
    {
        return [
            new OneToMany('comments', Comment::class, 'article')
        ];
    }
}

// Récupération avec jointure
$articleWithComments = $entityManager->getRepository(Article::class)
    ->find(1)
    ->with('comments')
    ->toObject();

Format des résultats

// Tableau associatif
$userArray = $repository->find(1)->toArray();

// Objet entité
$userObject = $repository->find(1)->toObject();

// Collection d'objets
$activeUsers = $repository->findBy()
    ->where('isActive', true)
    ->toCollection();

PaperORM propose une API simple tout en couvrant les besoins essentiels d'un ORM moderne.

Version Bêta - Contribuez au développement

PaperORM est actuellement en version bêta et évolue activement. Nous invitons tous les développeurs intéressés à :

🐞 Signaler des bugs

Si vous rencontrez un problème, ouvrez une issue GitHub en détaillant :

• Le contexte
• Les étapes pour reproduire
• Le comportement attendu vs. observé

💡 Proposer des améliorations

Des idées pour :

• Optimiser les performances
• Améliorer l'API
• Ajouter des fonctionnalités

📖 Contribuer à la documentation

La documentation complète est en cours de rédaction. Vous pouvez :

• Corriger des erreurs
• Ajouter des exemples
• Traduire des sections

Note : Cette version est stable pour un usage en développement, mais nécessite des tests supplémentaires pour la production.

Le développement actif continue - restez à l'écoute pour les mises à jour !