Introduction

Introduction

Unlock the full potential of Domain-Driven Design in your Laravel projects with the laravel-cycle-orm-adapter — the adapter package that seamlessly integrates the capabilities of CycleORM DataMapper ORM into Laravel Framework.

This adapter bridges the gap between Laravel's rapid development capabilities and CycleORM's Data Mapper features, enabling you to craft complex, domain-centric applications, with separation of concerns, and a clear distinction between the domain model and the persistence layer.

🧐 Understanding the Limitations of Eloquent

Eloquent, Laravel's default ORM, is a powerful and convenient tool for many projects, thanks to its simplicity and ActiveRecord implementation that streamlines database interactions. However, in applications that aim to implement Domain-Driven Design (DDD) principles, Eloquent's ActiveRecord pattern can pose some challenges, as your application grows in complexity

DDD emphasizes a clear separation between the domain logic (data model) and the infrastructure code (persistence), allowing the domain model to operate independently of the persistence layer. This separation is crucial for maintaining testability, maintainability, and scalability, especially in complex applications or those developed by large teams with varying levels of expertise.

Eloquent's ActiveRecord approach tends to blend the domain models and the database layer, leading to tightly coupled code. This coupling can make it difficult to enforce clean architecture principles, as the business logic and persistence concerns become intertwined. As a result, the codebase becomes harder to maintain, test, and evolve, particularly in large-scale or complex applications. Moreover, this approach can lead to bloated models, where business logic and database operations are mixed together, complicating the adherence to coding standards and the application's ability to adapt to change.

🤔 Why CycleORM in Laravel?

Several notable attempts have been made to bring DDD to Laravel, such as:

these often involve workarounds to adapt Eloquent rather than a fundamental shift in approach, by selecting a more suitable ORM for DDD.

The laravel-cycle-orm-adapter bridges this gap, by introducing DataMapper pattern capabilities implemented by CycleORM, to Laravel, empowering you to unlock the full potential of DDD within your projects.

Here's why this combination shines:

  • Domain-Driven Design: This stack is designed to work with complex domain models, making it a perfect fit for DDD.
  • Separation of Concerns: The Data Mapper pattern enforced by CycleORM creates a clear boundary between your business logic (domain model) and data persistence mechanisms. This leads to a cleaner, more testable, and adaptable codebase.
  • Tackling Complexity: As your project's business rules and data relationships become more intricate, CycleORM's features provide the flexibility to model and manage them effectively.
  • Long-Term Maintainability: By decoupling your domain model from persistence details, your application becomes less brittle and easier to maintain as requirements evolve.

🌟 Key Features

  • Seamless Integration: The adapter is designed to work seamlessly with Laravel
  • Entity-Driven Database Migrations: Unlike Eloquent ActiveRecord approach, where migrations stands as the source of truth, CycleORM allows you to use your domain entities as the source of truth for your database schema, making it easier to keep your database schema in sync with your domain model.
  • Real Repositories: Avoid breaking the Repository Design Pattern in Laravel, maintaining a clear separation between your domain logic and the persistence layer.
  • DataMapper Pattern: Enforces a clear boundary between business logic and persistence, leading to a cleaner, more testable, and adaptable codebase, by defining your domain models and their relationships in a way that is more natural and expressive.
  • Designed for Complex Domains: Provides the flexibility to model and manage intricate business rules and data relationships effectively.
  • Long-Term Maintainability: By decoupling the domain model from persistence details, your application becomes less brittle and easier to maintain as requirements evolve.
  • Compatibility with Laravel Octane: CycleORM is designed to work in daemonized PHP applications like RoadRunner, making it a good fit for Laravel Octane users.
  • Database Factories: Use Laravel database seeders together with wayofdev/laravel-cycle-orm-factories to write Eloquent-Like factories for your CycleORM entities.
  • Powerful Query Builder: CycleORM provides a powerful query builder that allows you to write complex queries in a way that is easy to read and understand.
  • Schema Management: CycleORM provides powerful schema management capabilities, allowing you to define your database schema using PHP code.
  • Laravel Collections Support: The adapter provides support for Laravel Collections, allowing you to use them with your domain entities and repositories.
  • Flexible Entity Definition: Use Plain Old PHP objects, ActiveRecord, Custom objects, or the same entity type for multiple repositories.
  • Embedded Entities: Work with embedded entities and lazy/eager loaded embedded partials.
  • Additional Features: Supports global query scopes, UUIDs as primary keys, soft deletes, and auto timestamps.
  • Custom Column Types: Allows the use of custom column types and foreign keys to non-primary columns.
  • Annotation Support: Compatible with PHP8 attributes.

🛠️ Want to see it in action?

Explore the Laravel CycleORM Starter Kit project: laravel-cycle-orm-starter-kit, based on Laravel 10.x. It showcases the practical use of the adapter in a real-world application, demonstrating how to leverage CycleORM's strengths within a Laravel project.

Getting Started