README

⚡ A lightweight, high-performance ORM wrapper for Doctrine 3

Simplify your repositories. Eliminate boilerplate. Boost performance.

📖 Overview

Mitsuki ORM is a developer-friendly wrapper around Doctrine ORM 3 that removes repetitive repository configuration.

It uses reflection-based entity discovery, filesystem caching, and fluent query helpers to deliver both developer experience and performance.

✨ Features

🔍 Automatic Entity Discovery (zero config)
⚡ Filesystem Cache for Production
🧠 Smart Reflection Mapping
🔗 Relationship Helpers
📄 Pagination Ready (Doctrine Paginator)
🧪 Fully tested with Pest PHP & Mockery
🛠️ CLI integration via mitsuki/commands

📦 Installation

composer require mitsuki/mitsuki-orm

🚀 Quick Start

1. Create a Repository

namespace App\Repository;

use Mitsuki\ORM\Repositories\Repository;
use App\Entity\User;

class UserRepository extends Repository
{
    protected User $userEntity;
}

✅ No configuration needed — Mitsuki automatically detects the entity.

🧱 Basic Usage

// Create
$userRepository->save($user);

// Read
$user = $userRepository->find(1);

// Update (same as save)
$userRepository->save($user);

// Delete
$userRepository->delete($user);

// All
$users = $userRepository->findAll();

🔍 Query Builder Helpers

Simple Query

$userRepository->where([
    'status' => 'active'
]);

AND Conditions

$qb = $userRepository->whereAnd([
    'status' => 'active',
    'role' => 'admin'
]);

$results = $qb->getQuery()->getResult();

OR Conditions

$qb = $userRepository->whereOr([
    'role' => 'admin',
    'role' => 'editor'
]);

📄 Pagination

$paginator = $userRepository->paginate(page: 1, limit: 10);

foreach ($paginator as $user) {
    // ...
}

🔗 Relationship Management

Get Collection

$posts = $userRepository->getCollection($user, 'posts');

Add Related Entity

$userRepository->addRelated($user, 'posts', $post);

Get Single Relation

$profile = $userRepository->getRelated($user, 'profile');

⚡ Performance Optimization

Enable caching in production:

$repo = new UserRepository(
    entityManager: $entityManager,
    cachePath: '/path/to/cache',
    useCache: true
);

Cache Strategy

Step	Description
1	In-memory cache
2	Filesystem cache
3	Reflection fallback
4	Cache warmup

🧹 CLI Commands

php hermite repository:clear

Behavior

✅ Removes cache file
ℹ️ Shows info if no cache exists
❌ Returns error on failure

🧪 Testing

composer test

✔ Covers:

Cache system
CLI commands
Repository logic
Error scenarios

🏗️ Architecture

Repository Pattern
    ↓
Reflection Mapping
    ↓
Filesystem Cache
    ↓
Doctrine QueryBuilder

📁 Project Structure

src/
 ├── ORM/
 │   ├── Repositories/
 │   │   └── Repository.php
 │   ├── Command/
 │   │   └── RepositoryClearCommand.php
tests/

⚠️ Requirements

PHP 8.1+
Doctrine ORM 3+
Symfony Filesystem

📜 License

MIT License — free for personal and commercial use.

👨‍💻 Author

Zgenius Matondo 📧 zgeniuscoders@gmail.com

⭐ Support the Project

If you like this project:

⭐ Star the repository
🐛 Report issues
🤝 Contribute

🔥 Roadmap (Optional but Pro Touch)

Soft delete support
Query caching layer
Event system (hooks)
Multi-tenant support
API Platform integration

💡 Final Thought

Mitsuki ORM is built for developers who love Doctrine — but hate boilerplate.

mitsuki / mitsuki-orm

Maintainers

Package info

Statistics

Security