Merge pull request #600 from wayofdev/feat/docs

lotyp · web-flow · commit 54d73e486d82 · 2024-03-07T12:19:32.000+02:00
diff --git a/.gitattributes b/.gitattributes
@@ -1,5 +1,6 @@
 /.build export-ignore
 /.github export-ignore
+/docs export-ignore
 /tests export-ignore
 .editorconfig export-ignore
 .env export-ignore
diff --git a/docs/.gitignore b/docs/.gitignore
@@ -0,0 +1,2 @@
+.next
+node_modules
diff --git a/docs/README.md b/docs/README.md
@@ -0,0 +1,23 @@
+# Nextra Docs Template
+
+This is a template for creating documentation with [Nextra](https://nextra.site).
+
+[**Live Demo →**](https://nextra-docs-template.vercel.app)
+
+[![](.github/screenshot.png)](https://nextra-docs-template.vercel.app)
+
+## Quick Start
+
+Click the button to clone this repository and deploy it on Vercel:
+
+[![](https://vercel.com/button)](https://vercel.com/new/clone?s=https%3A%2F%2Fgithub.com%2Fshuding%2Fnextra-docs-template&showOptionalTeamCreation=false)
+
+## Local Development
+
+First, run `pnpm i` to install the dependencies.
+
+Then, run `pnpm dev` to start the development server and visit localhost:3000.
+
+## License
+
+This project is licensed under the MIT License.
diff --git a/docs/next-env.d.ts b/docs/next-env.d.ts
@@ -0,0 +1,5 @@
+/// <reference types="next" />
+/// <reference types="next/image-types/global" />
+
+// NOTE: This file should not be edited
+// see https://nextjs.org/docs/basic-features/typescript for more information.
diff --git a/docs/next.config.js b/docs/next.config.js
@@ -0,0 +1,6 @@
+const withNextra = require('nextra')({
+  theme: 'nextra-theme-docs',
+  themeConfig: './theme.config.tsx',
+})
+
+module.exports = withNextra()
diff --git a/docs/package.json b/docs/package.json
@@ -0,0 +1,34 @@
+{
+  "name": "@wayofdev/laravel-cycle-orm-adapter-docs",
+  "version": "1.0.0",
+  "description": "Documentation for Laravel Cycle ORM Adapter",
+  "scripts": {
+    "dev": "next dev",
+    "build": "next build",
+    "start": "next start"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/shuding/nextra-docs-template.git"
+  },
+  "author": "Shu Ding <g@shud.in>",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/shuding/nextra-docs-template/issues"
+  },
+  "homepage": "https://github.com/shuding/nextra-docs-template#readme",
+  "dependencies": {
+    "next": "^13.5.6",
+    "nextra": "latest",
+    "nextra-theme-docs": "latest",
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0"
+  },
+  "devDependencies": {
+    "@types/node": "18.11.10",
+    "autoprefixer": "^10.4.18",
+    "postcss": "^8.4.35",
+    "tailwindcss": "^3.4.1",
+    "typescript": "^4.9.5"
+  }
+}
diff --git a/docs/pages/_meta.json b/docs/pages/_meta.json
@@ -0,0 +1,7 @@
+{
+  "index": "Introduction",
+  "installation": "Installation",
+  "configuration": "Configuration",
+  "usage": "Usage",
+  "services": "Services"
+}
diff --git a/docs/pages/configuration.mdx b/docs/pages/configuration.mdx
@@ -0,0 +1 @@
+# Configuration
diff --git a/docs/pages/index.mdx b/docs/pages/index.mdx
@@ -0,0 +1,59 @@
+# Introduction
+
+Unlock the full potential of [Domain-Driven Design](https://en.wikipedia.org/wiki/Domain-driven_design) in your Laravel projects with the [wayofdev/laravel-cycle-orm-adapter](https://github.com/wayofdev/laravel-cycle-orm-adapter) — the adapter package that seamlessly integrates the capabilities of [CycleORM](https://cycle-orm.dev) — DataMapper ORM into [Laravel Framework](https://laravel.com).
+
+This adapter bridges the gap between Laravel's rapid development capabilities and Cycle ORM'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 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.
+
+
+## 🤔 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:
+
+* [Laravel Beyond CRUD approach](https://laravel-beyond-crud.com) by Spatie
+
+* [Conciliating Laravel and DDD](https://lorisleiva.com/conciliating-laravel-and-ddd)  by Loris Leiva
+
+* [Yet another Laravel 10 DDD interpretation](https://github.com/Orphail/laravel-ddd)
+
+these often involve workarounds to adapt Eloquent rather than a fundamental shift in approach.
+
+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.
+
+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.
+
+
+## 🚀 Features
+
+### Laravel Cycle ORM Adapter Features
+- **Seamless Integration**: The adapter is designed to work seamlessly with Laravel, allowing you to use Cycle ORM 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](https://laravel.com/docs/10.x/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](https://github.com/wayofdev/laravel-cycle-orm-factories)
+- **Real Repositories**: [Avoid breaking the Repository Design Pattern in Laravel](https://medium.com/@sergiumneagu/laravel-why-youve-been-using-the-repository-pattern-the-wrong-way-952aedf1989b), maintaining a clear separation between your domain logic and the persistence layer.
+
+
+### Cycle ORM Features
+- **Domain-Driven Design**: Cycle ORM is designed to work with complex domain models, making it a perfect fit for DDD.
+- **Data Mapper**: Cycle ORM 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.
+- **Powerful Query Builder**: Cycle ORM provides a powerful query builder that allows you to write complex queries in a way that is easy to read and understand.
+- **Schema Management**: Cycle ORM provides powerful schema management capabilities, allowing you to define your database schema using PHP code.
+
+## 🛠️ Want to see it in action?
+
+Explore the Laravel CycleORM Starter Kit project: [laravel-cycle-orm-starter-kit](https://github.com/wayofdev/laravel-cycle-starter-tpl), 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.
diff --git a/docs/pages/installation.mdx b/docs/pages/installation.mdx
@@ -0,0 +1,43 @@
+# Installation
+
+Welcome to the installation guide for the Laravel Cycle ORM Adapter. This document will walk you through the setup process to get you up and running quickly.
+
+## 🚩 Prerequisites
+
+Before you begin, ensure your development environment meets the following requirements:
+
+- **PHP Version:** 8.2 or higher
+- **Laravel:** 10.x or higher
+
+## 🚀 Quick Start
+
+Installing the Laravel Cycle ORM Adapter is straightforward with Composer. Follow the steps below to add the adapter to your Laravel project.
+
+### Step 1: Install the Adapter
+
+For the core functionality, run the following Composer command in your terminal:
+
+```bash
+$ composer req wayofdev/laravel-cycle-orm-adapter
+```
+
+This command installs the wayofdev/laravel-cycle-orm-adapter package, integrating Cycle ORM into your Laravel application.
+
+### Step 2: Publish Configuration
+
+After installing the package, publish the configuration file using the `vendor:publish` command:
+
+```bash
+$ php artisan vendor:publish \
+  --provider="WayOfDev\Cycle\Bridge\Laravel\Providers\CycleServiceProvider"
+```
+
+## 🏭 Database Factories (Optional)
+
+If you need support for [Eloquent-like Factories](https://laravel.com/docs/10.x/eloquent-factories), install the following package:
+
+```bash
+$ composer req --dev wayofdev/laravel-cycle-orm-factories
+```
+
+which will install the [wayofdev/laravel-cycle-orm-factories](https://github.com/wayofdev/laravel-cycle-orm-factories) package to provide similar functionality
diff --git a/docs/pages/services/factories.mdx b/docs/pages/services/factories.mdx
@@ -0,0 +1 @@
+# Database Factories
diff --git a/docs/pages/services/seeders.mdx b/docs/pages/services/seeders.mdx
@@ -0,0 +1 @@
+# Database Seeders
diff --git a/docs/pages/services/testing.mdx b/docs/pages/services/testing.mdx
@@ -0,0 +1 @@
+# Testing
diff --git a/docs/pages/services/validation.mdx b/docs/pages/services/validation.mdx
@@ -0,0 +1,81 @@
+# Validation
+
+Laravel provides several different approaches to validate your application's incoming data. As we plan to use this package in larger projects, better approach would be to use Laravel [Form Request Validation](https://laravel.com/docs/10.x/validation#form-request-validation). This way we can keep our controllers clean and our code more readable.
+
+Both `unique` and `exists` validation rules, require the database to be queried. This packages provides this integration.
+
+## ⚡️ Unique
+
+The field under validation must be unique for a given Entity. If the column option is not specified, the field name will be used.
+
+To accomplish this, we can use `WayOfDev\Cycle\Bridge\Laravel\Rules\Unique` rule class.
+
+### Example Form Request
+
+This example shows how to use `Unique` rule class in a form request.
+
+```php
+<?php
+
+declare(strict_types=1);
+
+namespace Bridge\Laravel\Admin\Product\Requests;
+
+use Cycle\Database\DatabaseInterface;
+use WayOfDev\Cycle\Bridge\Laravel\Rules\Unique;
+
+final class StoreFormRequest
+{
+    public function rules(DatabaseInterface $database): array
+    {
+        return [
+            'name' => ['required'], // ... just a simple required rule
+            // ... other rules
+            'category.id' => [
+                'bail',
+                'required',
+                'uuid',
+                new Unique($database, 'categories', 'id')
+            ],
+        ];
+    }
+}
+```
+
+## ⚡️ Exists
+
+The field under validation must exist on a given Entity. If the column option is not specified, the field name will be used.
+
+To accomplish this, we can use `WayOfDev\Cycle\Bridge\Laravel\Rules\Exists` rule class.
+
+### Example Form Request
+
+This example shows how to use `Exists` rule class in a form request.
+
+```php
+<?php
+
+declare(strict_types=1);
+
+namespace Bridge\Laravel\Admin\Product\Requests;
+
+use Cycle\Database\DatabaseInterface;
+use WayOfDev\Cycle\Bridge\Laravel\Rules\Exists;
+
+final class StoreFormRequest
+{
+    public function rules(DatabaseInterface $database): array
+    {
+        return [
+            'name' => ['required'], // ... just a simple required rule
+            // ... other rules
+            'category.id' => [
+                'bail',
+                'required',
+                'uuid',
+                new Exists($database, 'categories', 'id')
+            ],
+        ];
+    }
+}
+```
diff --git a/docs/pages/usage.mdx b/docs/pages/usage.mdx
@@ -0,0 +1,3 @@
+# Usage
+
+This is the index page for the Advanced folder!
diff --git a/docs/pages/usage/annotations.mdx b/docs/pages/usage/annotations.mdx
@@ -0,0 +1 @@
+# Annotations (Attributes)
diff --git a/docs/pages/usage/console-commands.mdx b/docs/pages/usage/console-commands.mdx
@@ -0,0 +1 @@
+# Console Commands
diff --git a/docs/pages/usage/entities.mdx b/docs/pages/usage/entities.mdx
@@ -0,0 +1 @@
+# Entities
diff --git a/docs/pages/usage/entity-manager.mdx b/docs/pages/usage/entity-manager.mdx
diff --git a/docs/pages/usage/migrations.mdx b/docs/pages/usage/migrations.mdx
@@ -0,0 +1 @@
+# Migrations
diff --git a/docs/pages/usage/repositories.mdx b/docs/pages/usage/repositories.mdx
@@ -0,0 +1 @@
+# Repositories
diff --git a/docs/pnpm-lock.yaml b/docs/pnpm-lock.yaml
diff --git a/docs/postcss.config.js b/docs/postcss.config.js
diff --git a/docs/tailwind.config.js b/docs/tailwind.config.js
diff --git a/docs/theme.config.tsx b/docs/theme.config.tsx
diff --git a/docs/tsconfig.json b/docs/tsconfig.json
