Expand getting-started with design pattern usage examples

Add concrete service-repository, actions+DTO, lean, hand-picked patterns, custom presets, filters, enums and JSON response examples.

Author: Karim-Ashraf

docs/getting-started.md

@@ -98,34 +98,259 @@ All responses use `ProductResource` and a consistent JSON envelope; validation e
 
 ## 6. Choosing a design pattern (architecture)
 
-You have three ways to control what gets generated, from broadest to finest:
+You have three ways to control what gets generated:
 
-**Per command** — pass `--architecture` (or `-a`):
+| Approach | When to use | Example |
+| --- | --- | --- |
+| `--architecture=` | One module needs a different style | `--architecture=actions` |
+| Config / `.env` default | Whole project uses one style | `LARA_ARCHITECT_ARCHITECTURE=actions` |
+| `--patterns=` | Mix-and-match for this module only | `--patterns=model,migration,service,controller` |
+
+Other useful flags: `--force`, `--no-uuid`, `--no-soft-deletes`, `--dry-run`.
+
+### 6.1 Service–Repository (default)
+
+Best when you want a clear layer between HTTP, business rules, and data access.
+
+```bash
+php artisan make:module Product \
+  --architecture=service-repository \
+  --fields="name:string, price:decimal, sku:string:unique, status:enum"
+```
+
+**How the pieces fit together**
+
+```
+Controller  →  ProductService  →  ProductRepository  →  Product (Eloquent)
+     ↑                ↑
+StoreProductRequest   prepareForCreate / created hooks
+ProductFilter (index)
+```
+
+**Controller** injects the service:
+
+```php
+public function __construct(
+    private readonly ProductService $productService,
+) {}
+
+public function store(StoreProductRequest $request): JsonResponse
+{
+    $product = $this->productService->create($request->validated());
+
+    return $this->respondCreated(new ProductResource($product));
+}
+```
+
+**Extend the repository** with module-specific queries:
+
+```php
+// app/Repositories/ProductRepository.php
+public function findBySku(string $sku): ?Product
+{
+    return $this->findBy('sku', $sku);
+}
+
+public function active(): Collection
+{
+    return $this->getBy(['status' => ProductStatus::Active]);
+}
+```
+
+**Extend the service** with business logic (still transactional):
+
+```php
+// app/Services/ProductService.php
+protected function prepareForCreate(array $data): array
+{
+    $data['sku'] = strtoupper($data['sku']);
+
+    return $data;
+}
+
+protected function created(Model $model, array $data): void
+{
+    // e.g. dispatch ProductCreated event, clear cache, ...
+}
+
+public function archive(Product $product): Product
+{
+    return $this->update($product, ['status' => ProductStatus::Archived]);
+}
+```
+
+**Soft-delete helpers** (available on both repository and service):
+
+```php
+$service->delete($product);           // soft delete
+$service->restore($product);          // restore one
+$service->restoreAll([1, 2, 3]);      // restore by ids (or all trashed if empty)
+$service->forceDelete($product);      // permanent
+$service->trashed();                  // list soft-deleted
+$service->deleteMany([1, 2, 3]);
+$service->deleteAll();
+```
+
+### 6.2 Actions + DTO
+
+Best when each use-case should be a single, reusable class (ADR-style / single-responsibility).
 
 ```bash
-php artisan make:module Order --architecture=actions --fields="total:decimal, status:enum"
+php artisan make:module Order \
+  --architecture=actions \
+  --fields="total:decimal, status:enum, notes:text:nullable"
 ```
 
-The `actions` preset skips the service/repository and instead generates `CreateOrder` / `UpdateOrder` / `DeleteOrder` action classes plus an `OrderData` DTO, and the controller dispatches those actions.
+**What you get**
 
-**As a project default** — set it once in `config/lara-architect.php` (or `.env`):
+```
+app/
+├── Actions/Orders/CreateOrder.php
+├── Actions/Orders/UpdateOrder.php
+├── Actions/Orders/DeleteOrder.php
+├── DTOs/OrderData.php
+├── Enums/OrderStatus.php
+├── Models/Order.php
+└── Http/Controllers/OrderController.php   # calls CreateOrder::run(...), etc.
+```
+
+**Controller** dispatches actions (no service injection):
+
+```php
+public function store(StoreOrderRequest $request): JsonResponse
+{
+    $order = CreateOrder::run(OrderData::fromRequest($request));
+
+    return $this->respondCreated(new OrderResource($order));
+}
+
+public function update(UpdateOrderRequest $request, Order $order): JsonResponse
+{
+    $order = UpdateOrder::run($order, OrderData::fromRequest($request));
+
+    return $this->respondSuccess(new OrderResource($order), 'Order updated successfully.');
+}
+
+public function destroy(Order $order): JsonResponse
+{
+    DeleteOrder::run($order);
+
+    return $this->respondDeleted();
+}
+```
+
+**Add a custom action** for a non-CRUD use-case:
+
+```php
+// app/Actions/Orders/MarkOrderPaid.php
+namespace App\Actions\Orders;
+
+use App\Enums\OrderStatus;
+use App\Models\Order;
+use KarimAshraf\LaraArchitect\Actions\Action;
+
+class MarkOrderPaid extends Action
+{
+    protected function handle(Order $order): Order
+    {
+        $order->update(['status' => OrderStatus::Active]);
+
+        return $order->refresh();
+    }
+}
+
+// anywhere in the app:
+MarkOrderPaid::run($order);
+```
+
+**DTO usage** outside the controller:
+
+```php
+$data = OrderData::fromArray([
+    'total' => 99.5,
+    'status' => 'active',
+    'notes' => null,
+]);
+
+$data->toArray();           // snake_case keys, enums as values
+$data->toFilteredArray();   // nulls removed — good for partial updates
+```
+
+### 6.3 Lean (Eloquent in the controller)
+
+Best for tiny resources or admin prototypes where a full stack is overkill.
+
+```bash
+php artisan make:module Tag \
+  --architecture=lean \
+  --fields="name:string:unique"
+```
+
+Generates only: model, migration, form requests, resource, controller. The controller talks to Eloquent directly — no service, repository, or actions.
+
+### 6.4 Hand-picked patterns
+
+Skip presets and compose your own stack for one module:
+
+```bash
+# Model + service, no repository
+php artisan make:module Invoice \
+  --patterns=model,migration,service,requests,resource,controller \
+  --fields="number:string:unique, total:decimal"
+
+# Actions without DTO
+php artisan make:module Note \
+  --patterns=model,migration,actions,requests,resource,controller \
+  --fields="body:text"
+
+# Read-only resource (no write layer)
+php artisan make:module Report \
+  --patterns=model,migration,resource,controller \
+  --fields="title:string"
+```
+
+List every registered pattern anytime:
+
+```bash
+php artisan architect:patterns
+```
+
+### 6.5 Project default and custom presets
+
+**Set a project-wide default** in `config/lara-architect.php` or `.env`:
+
+```env
+LARA_ARCHITECT_ARCHITECTURE=actions
+```
 
 ```php
 'generation' => [
-    'default_architecture' => env('LARA_ARCHITECT_ARCHITECTURE', 'actions'),
+    'default_architecture' => env('LARA_ARCHITECT_ARCHITECTURE', 'service-repository'),
 ],
 ```
 
-Now every `make:module` without `--architecture` uses it.
+**Add your own preset** — a named list of patterns — then use it like any built-in:
 
-**Hand-picked patterns** — skip presets entirely with `--patterns`:
+```php
+// config/lara-architect.php
+'architectures' => [
+    'service-repository' => [/* ... */],
+    'actions' => [/* ... */],
+    'lean' => [/* ... */],
+
+    // your team style:
+    'api-full' => [
+        'model', 'migration', 'factory', 'enum',
+        'repository', 'service', 'filter',
+        'requests', 'resource', 'controller',
+    ],
+],
+```
 
 ```bash
-php artisan make:module Tag --patterns=model,migration,resource,controller --fields="name:string:unique"
+php artisan make:module Customer --architecture=api-full --fields="name:string, email:string:unique"
 ```
 
-Other useful flags: `--force` (overwrite existing files), `--no-uuid`, `--no-soft-deletes`.
-
 ## 7. Field definition reference
 
 ```
@@ -146,17 +371,86 @@ published_at:datetime:nullable              # date-range filters (published_at_f
 category_id:foreignid                       # foreign key column
 ```
 
-## 8. Beyond the generator
+## 8. Patterns you use after generation
+
+These work with generated modules and with hand-written code.
+
+### Query filters
+
+```php
+// GET /api/products?search=desk&price_min=100&status=active
+public function index(ProductFilter $filter): AnonymousResourceCollection
+{
+    return ProductResource::collection(
+        $this->productService->filter($filter),
+    );
+}
+
+// or on the model / repository:
+Product::filter($filter)->paginate();
+$repository->filter($filter, perPage: 20);
+```
+
+Add a custom filter method — any public method on the filter maps from the query string (`?featured=1` → `featured()`):
+
+```php
+// app/Http/Filters/ProductFilter.php
+public function featured(string $value): void
+{
+    $this->builder->where('is_featured', filter_var($value, FILTER_VALIDATE_BOOLEAN));
+}
+```
+
+### Enums (`EnumHelpers`)
+
+Generated enums use the package trait. Override any helper by redeclaring it:
+
+```php
+namespace App\Enums;
+
+use KarimAshraf\LaraArchitect\Enums\Concerns\EnumHelpers;
+
+enum ProductStatus: string
+{
+    use EnumHelpers;
 
-The generated classes extend the package's base classes, which you can also use directly in hand-written code:
+    case Draft = 'draft';
+    case Active = 'active';
+    case Archived = 'archived';
 
-- `BaseRepository` / `BaseService` — CRUD plus soft-delete operations: `restore()`, `restoreAll()`, `deleteAll()`, `deleteMany()`, `forceDelete()`, `trashed()`
-- `Action` — single-purpose, transaction-wrapped classes invoked with `MyAction::run(...)`
-- `QueryFilter` + the `Filterable` model trait — request-driven filtering
-- `BaseData` — DTOs hydrated from requests/arrays, with enum and nested-DTO support
-- `BaseFormRequest` + `RespondsWithJson` — consistent JSON envelopes
+    public function label(): string
+    {
+        return __("products.status.{$this->value}");
+    }
+}
+
+ProductStatus::values();                    // ['draft', 'active', 'archived']
+ProductStatus::options();                   // value => label (uses your label())
+ProductStatus::Active->is(ProductStatus::Active);
+```
+
+### Form requests + JSON responses
+
+```php
+class StoreProductRequest extends BaseFormRequest
+{
+    public function rules(): array
+    {
+        return [
+            'name' => ['required', 'string', 'max:255'],
+            'status' => ['required', Rule::enum(ProductStatus::class)],
+        ];
+    }
+}
+
+// In any controller using RespondsWithJson:
+return $this->respondCreated($resource);
+return $this->respondSuccess($resource, 'Updated.');
+return $this->respondDeleted();
+return $this->respondError('Something went wrong.', 422);
+```
 
-See the [README](../README.md#runtime-building-blocks) for examples of each.
+More detail: [README — Runtime building blocks](../README.md#runtime-building-blocks).
 
 ## 9. Customizing the generated code
 

docs/index.md

@@ -5,6 +5,7 @@ Welcome to the LaraArchitect documentation. The [README](../README.md) is the pr
 ## Quick links
 
 - [Getting started: from install to a working CRUD API](getting-started.md)
+- [Design pattern examples](getting-started.md#6-choosing-a-design-pattern-architecture) — service-repository, actions + DTO, lean, custom presets
 - [Requirements & supported versions](../README.md#requirements)
 - [Installation](../README.md#installation)
 - [The module generator](../README.md#the-module-generator) — architecture presets, field definitions, enum fields, query filters