diff --git a/README.md b/README.md index 6c021580..bc09ec54 100644 --- a/README.md +++ b/README.md @@ -85,7 +85,7 @@ Created in **2022** by [lotyp / wayofdev](https://github.com/wayofdev) * The official [spiral/cycle-bridge](https://github.com/spiral/cycle-bridge) for Spiral Framework -* Alternative implementation of Cycle ORM for Laravel — [wakebit/laravel-cycle](https://github.com/wakebit/laravel-cycle) (abandoned) +* Alternative implementation of Cycle ORM for Laravel — [wakebit/laravel-cycle](https://github.com/wakebit/laravel-cycle)
diff --git a/docs/components/env-table/index.tsx b/docs/components/env-table/index.tsx index ffb9c0b7..c6ecf248 100644 --- a/docs/components/env-table/index.tsx +++ b/docs/components/env-table/index.tsx @@ -1,7 +1,7 @@ import styles from './style.module.css' export function OptionTable({ options }: { options: [string, string, string, string][] }) { - const createMarkup = (htmlContent) => { + const createMarkup = (htmlContent: string) => { return { __html: htmlContent }; }; diff --git a/docs/pages/index.mdx b/docs/pages/index.mdx index b8d5b7aa..70815b3b 100644 --- a/docs/pages/index.mdx +++ b/docs/pages/index.mdx @@ -2,24 +2,21 @@ import ExternalLink from "../components/external-link"; # 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. +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 -While Eloquent is a powerful and convenient ORM for many projects, its Active Record implementation poses challenges for applications that require a clear separation between the domain logic (data model) and the infrastructure code (persistence). Ideally, the domain model should operate independently of the persistence layer, a principle that is central to DDD. This separation enhances testability, maintainability, and scalability, especially in complex applications or those developed by large teams with varying levels of expertise. Eloquent's approach, however, tends to blur these boundaries, leading to tightly coupled code that can hinder the enforcement of coding standards and complicate the application's evolution. +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 -Eloquent is Laravel's shining star for ORM, beloved for its simplicity and ActiveRecord implementation that makes database interactions straightforward. However, its tight coupling between the domain models and the database layer can be a double-edged sword, especially in large-scale or complex applications. This coupling tends to mix the business logic with persistence concerns, making the codebase harder to maintain, test, and evolve. Moreover, Eloquent's approach can lead to bloated models, where business logic and database operations are intertwined, complicating the enforcement of clean architecture principles. +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? -Laravel's Eloquent ORM is a fantastic tool for rapid development and common database interactions. However, as your application grows in complexity, Eloquent can encounter limitations when implementing strict Domain-Driven Design (DDD) patterns. - -The Active Record pattern tightly couples domain logic and data persistence within the same model, potentially leading to challenges in maintaining a clean separation of concerns. - -There were many attempts to bring DDD to Laravel: +Several notable attempts have been made to bring DDD to Laravel, such as: * Laravel Beyond CRUD approach by Spatie @@ -27,34 +24,36 @@ There were many attempts to bring DDD to Laravel: * Yet another Laravel 10 DDD interpretation -these often involve workarounds to adapt Eloquent rather than a fundamental shift in approach. +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 to Laravel, empowering you to unlock the full potential of DDD within your projects. +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: -* 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. +- **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 -## 🚀 Features - -### Laravel CycleORM Adapter Features -- **Seamless Integration**: The adapter is designed to work seamlessly with Laravel, allowing you to use CycleORM in your Laravel projects without any hassle. -- **Entity as Source of Truth for Database Migrations**: The adapter 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. -- **Laravel Collections Support**: The adapter provides support for Laravel Collections, allowing you to use them with your domain models and repositories -- **Database Factories**: Use Laravel database seeders together with CycleORM Entity Factories via wayofdev/laravel-cycle-orm-factories +- **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. - - -### CycleORM Features -- **Domain-Driven Design**: CycleORM is designed to work with complex domain models, making it a perfect fit for DDD. -- **Data Mapper**: CycleORM is a Data Mapper ORM, which means that it allows you to define your domain models and their relationships in a way that is more natural and expressive. +- **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? diff --git a/docs/pages/services.mdx b/docs/pages/services.mdx new file mode 100644 index 00000000..d474bfd0 --- /dev/null +++ b/docs/pages/services.mdx @@ -0,0 +1,26 @@ +import { Card, Cards } from 'nextra/components' + +# Services + + + + + + + diff --git a/docs/pages/usage.mdx b/docs/pages/usage.mdx index 8f04b05a..d25ce0c3 100644 --- a/docs/pages/usage.mdx +++ b/docs/pages/usage.mdx @@ -1 +1,36 @@ +import { Card, Cards } from 'nextra/components' + # Usage + + + + + + + + +