@event4u/agent-config 1.9.1

package/.agent-src/guidelines/php/patterns/dtos.md

@@ -0,0 +1,199 @@
+# DTOs & Value Objects
+
+> Typed data instead of untyped arrays.
+
+## DTO (Data Transfer Object)
+
+Structured, immutable data container for passing data between layers.
+
+### When to Use
+
+✅ Passing validated request data to a service/action
+✅ Returning structured data from a service
+✅ Replacing `array<string, mixed>` in method signatures
+
+### Prefer a DTO base class (if available)
+
+If the project uses a DTO package with attribute-based mapping (e.g., `SimpleDto`, `spatie/data-transfer-object`),
+new DTOs **should extend the project's base class**. Check `composer.json` for DTO-related packages.
+
+#### Attribute-based DTO Example
+
+```php
+use App\Models\Equipment;
+use Vendor\DataHelpers\SimpleDto;
+use Vendor\DataHelpers\SimpleDto\Attributes\ConvertEmptyToNull;
+use Vendor\DataHelpers\SimpleDto\Attributes\DateTimeFormat;
+use Vendor\DataHelpers\SimpleDto\Attributes\Decimal;
+use Vendor\DataHelpers\SimpleDto\Attributes\HasModel;
+use Vendor\DataHelpers\SimpleDto\Attributes\Length;
+use Vendor\DataHelpers\SimpleDto\Attributes\Map;
+use Vendor\DataHelpers\SimpleDto\Attributes\Unsigned;
+use Carbon\Carbon;
+
+#[ConvertEmptyToNull]
+#[HasModel(Equipment::class)]
+class EquipmentDto extends SimpleDto
+{
+    public function __construct(
+        // Primary Key
+        #[Map('id_equipment')]
+        public ?int $id = null,
+
+        // Equipment identification
+        #[Map('equipment_nr'),
+            Length(50)]
+        public string $equipmentNumber = '',
+
+        #[Map('bezeichnung'),
+            Length(250)]
+        public string $title = '',
+
+        // External IDs (from client software)
+        #[Map('ext_uid'),
+            Length(250)]
+        public ?string $externalUid = null,
+
+        // Status
+        #[Map('is_active'),
+            Unsigned,
+            Length(1)]
+        public bool $isActive = true,
+
+        // Financial
+        #[Map('hourly_rate'),
+            Unsigned,
+            Decimal(10, 2)]
+        public float $hourlyRate = 0.0,
+
+        // Timestamps
+        #[Map('created_at'),
+            DateTimeFormat('Y-m-d H:i:s')]
+        public ?Carbon $createdAt = null,
+
+        #[Map('updated_at'),
+            DateTimeFormat('Y-m-d H:i:s')]
+        public ?Carbon $updatedAt = null,
+    ) {}
+}
+```
+
+#### Key attribute-based DTO features
+
+- **`#[Map('db_column')]`** — Maps a readable property name to a database column or API field name
+- **`#[Length(n)]`** — Validates max string length
+- **`#[Decimal(precision, scale)]`** — Validates decimal format
+- **`#[Unsigned]`** — Validates non-negative values
+- **`#[DateTimeFormat('Y-m-d H:i:s')]`** — Casts to/from Carbon with the given format
+- **`#[Email]`** — Validates email format
+- **`#[ConvertEmptyToNull]`** — Class-level: converts empty strings to `null`
+- **`#[HasModel(Model::class)]`** — Links the DTO to an Eloquent model for `fromModel()` / `toModel()`
+
+#### Creating and using DTOs
+
+```php
+// From array (e.g. API response, request data)
+$dto = EquipmentDto::fromArray($data);
+
+// From Eloquent model (requires #[HasModel] + DtoMappingTrait on the model)
+$dto = EquipmentDto::fromModel($equipment);
+
+// To array (uses #[Map] names as keys)
+$array = $dto->toArray();
+
+// To Eloquent model
+$model = $dto->toModel(Equipment::class);
+
+// Collections
+$dtos = EquipmentDto::collection($arrayOfData);
+```
+
+#### Attribute-based DTO rules
+
+- Extend the project's DTO base class
+- Use constructor property promotion with public properties
+- Use `#[Map('column_name')]` to map properties to database/API field names
+- Use validation attributes (`#[Length]`, `#[Decimal]`, `#[Email]`, etc.) for constraints
+- Use `#[ConvertEmptyToNull]` at class level when empty strings should become `null`
+- Use `#[HasModel(Model::class)]` when the DTO maps to an Eloquent model
+- No business logic — just data and mapping
+- Check if the base class requires mutable or immutable properties
+
+### Plain DTO (Fallback)
+
+When no DTO package is available or attribute-based mapping is not suitable (e.g. for very simple
+value transfer between methods), a plain readonly DTO is acceptable:
+
+```php
+final readonly class CreateOrderDTO
+{
+    public function __construct(
+        public int $customerId,
+        public string $description,
+        public int $totalInCents,
+    ) {}
+
+    public static function fromRequest(CreateOrderRequest $request): self
+    {
+        /** @var array{customer_id: int, description: string, total: int} $data */
+        $data = $request->validated();
+
+        return new self(
+            customerId: $data['customer_id'],
+            description: $data['description'],
+            totalInCents: $data['total'],
+        );
+    }
+}
+```
+
+#### Plain DTO Rules
+
+- Always `final readonly class`
+- Constructor property promotion
+- Static factory method `fromRequest()`, `fromArray()`, etc.
+- No business logic — just data
+
+## Value Object
+
+Represents a domain concept with validation and equality semantics.
+
+### When to Use
+
+✅ Domain concepts: `Money`, `Email`, `DateRange`, `Coordinates`
+✅ Value needs validation on creation
+✅ Two instances with same values should be considered equal
+
+### Example
+
+```php
+final readonly class Money
+{
+    public function __construct(
+        public int $amountInCents,
+        public string $currency = 'EUR',
+    ) {
+        if ($this->amountInCents < 0) {
+            throw new InvalidArgumentException('Amount must not be negative');
+        }
+    }
+
+    public function add(self $other): self
+    {
+        if ($this->currency !== $other->currency) {
+            throw new InvalidArgumentException('Cannot add different currencies');
+        }
+
+        return new self(
+            amountInCents: Math::add($this->amountInCents, $other->amountInCents),
+            currency: $this->currency,
+        );
+    }
+}
+```
+
+## When NOT to Use
+
+❌ Data only used in one place and structure is obvious — a simple array is fine
+❌ Wrapping a single primitive with no validation or behavior
+

package/.agent-src/guidelines/php/patterns/events.md

@@ -0,0 +1,67 @@
+# Event / Listener Pattern
+
+> Decouple side effects from core logic.
+
+## Idea
+
+A core process dispatches an **Event**, other parts of the system react via **Listeners**.
+The core process doesn't know (or care) who listens.
+
+## Typical Use Cases
+
+✅ Notifications (email, push) after an action
+✅ Logging, audit trails
+✅ Syncing data to external systems
+✅ Cache invalidation
+✅ Triggering follow-up jobs
+
+## Example
+
+```php
+// Event — immutable data container
+final readonly class OrderPlaced
+{
+    public function __construct(
+        public int $orderId,
+        public int $customerId,
+    ) {}
+}
+
+// Listener
+final class SendOrderConfirmation
+{
+    public function handle(OrderPlaced $event): void
+    {
+        // send email...
+    }
+}
+```
+
+## Dispatching
+
+```php
+// In a service or action
+OrderPlaced::dispatch($order->getId(), $order->getCustomerId());
+
+// Or via event helper
+event(new OrderPlaced($order->getId(), $order->getCustomerId()));
+```
+
+## Laravel Discovery
+
+Since Laravel 11, events and listeners are auto-discovered — no manual registration
+needed. Configured in `bootstrap/app.php`.
+
+## Rules
+
+- Events are `final readonly` — immutable data containers
+- Pass **IDs**, not model instances (smaller payload, avoids serialization issues)
+- One listener per side effect — don't cram multiple things into one listener
+- Use queued listeners (`ShouldQueue`) for slow operations (emails, API calls)
+
+## When NOT to Use
+
+❌ Direct, synchronous flow where caller needs the result — just call the service directly
+❌ Only one "listener" that always runs — a direct method call is simpler and easier to follow
+❌ Everything — too many events make the application flow hard to trace
+

package/.agent-src/guidelines/php/patterns/factory.md

@@ -0,0 +1,53 @@
+# Factory Pattern
+
+> Encapsulate complex object creation.
+
+## Idea
+
+When creating an object requires configuration, conditional logic, or multiple steps,
+extract that logic into a Factory class.
+
+## Laravel Context
+
+- **Model Factories** — Laravel ships with factories for test/seed data (`database/factories/`)
+- **Custom Factories** — for domain objects, API clients, or composed objects
+
+## When to Use
+
+✅ Object creation involves multiple steps or configuration
+✅ Different implementations based on a type/config value
+✅ API client setup with auth, base URL, middleware
+
+## When NOT to Use
+
+❌ Simple `new MyClass()` or `MyClass::create()` — no factory needed
+❌ Laravel Model Factories already cover the use case (test data)
+
+## Example
+
+```php
+final class ApiClientFactory
+{
+    public function __construct(private ConfigRepository $config) {}
+
+    public function create(ClientSoftwareType $type): ApiClient
+    {
+        return match ($type) {
+            ClientSoftwareType::KS21 => new Ks21ApiClient(
+                baseUrl: $this->config->get('services.ks21.url'),
+                apiKey: $this->config->get('services.ks21.key'),
+            ),
+            ClientSoftwareType::PROBAUS => new ProBauSApiClient(
+                baseUrl: $this->config->get('services.probaus.url'),
+            ),
+        };
+    }
+}
+```
+
+## Rules
+
+- Factory methods should return typed interfaces, not concrete classes (when possible)
+- Keep factory logic focused — don't add business logic here
+- Name: `{Thing}Factory` or static `{Thing}::create()` for simple cases
+

package/.agent-src/guidelines/php/patterns/pipelines.md

@@ -0,0 +1,66 @@
+# Pipeline / Middleware Pattern
+
+> Sequential processing steps — already built into Laravel.
+
+## Idea
+
+Pass data through a series of steps (pipes), where each step can transform,
+validate, or filter the data. Each pipe has a single responsibility.
+
+## Laravel Built-in
+
+- **HTTP Middleware** — request/response pipeline (authentication, CORS, logging)
+- **Pipeline facade** — `Illuminate\Pipeline\Pipeline` for custom pipelines
+- **Filter pipeline** — used in controllers for query filtering (see [controllers.md](../controllers.md))
+
+## Typical Use Cases
+
+✅ Request processing (middleware)
+✅ Import/export data transformation
+✅ Multi-step validation or enrichment
+✅ Query filter chains
+
+## Example: Custom Pipeline
+
+```php
+$result = Pipeline::send($importData)
+    ->through([
+        ValidateHeaders::class,
+        NormalizeEncoding::class,
+        MapColumns::class,
+        FilterInvalidRows::class,
+    ])
+    ->thenReturn();
+```
+
+Each pipe implements `handle()`:
+
+```php
+final class NormalizeEncoding
+{
+    public function handle(ImportData $data, Closure $next): mixed
+    {
+        $data->normalize();
+        return $next($data);
+    }
+}
+```
+
+## Query Filter Pipeline
+
+Already used in this project via `paginatedPipeline`:
+
+```php
+$results = Model::query()
+    ->paginatedPipeline([
+        StringFilter::on('name')->isLike()->some(),
+        DateFilter::on('created_at')->all(),
+        OrderFilter::on(['id', 'name'])->default(['id' => 'asc']),
+    ]);
+```
+
+## When NOT to Use
+
+❌ Only 2 steps with trivial logic — sequential method calls are clearer
+❌ Steps have complex dependencies on each other — pipelines assume independence
+

package/.agent-src/guidelines/php/patterns/policies.md

@@ -0,0 +1,66 @@
+# Policy Pattern
+
+> Centralized authorization logic — built into Laravel.
+
+## Idea
+
+Authorization rules belong in **Policy classes**, not scattered across controllers,
+middleware, or model methods.
+
+## Laravel Mechanism
+
+- One Policy per Model (or resource)
+- Methods map to actions: `view`, `create`, `update`, `delete`, `restore`
+- Called via `$this->authorize()` in controllers or `Gate::allows()` anywhere
+- FormRequests call policies in `authorize()` method
+
+## Example
+
+```php
+final class OrderPolicy
+{
+    public function view(User $user, Order $order): bool
+    {
+        return $user->getId() === $order->getUserId();
+    }
+
+    public function update(User $user, Order $order): bool
+    {
+        return $user->getId() === $order->getUserId()
+            && $order->getStatus() !== OrderStatus::COMPLETED;
+    }
+
+    public function delete(User $user, Order $order): bool
+    {
+        return $user->isAdmin();
+    }
+}
+```
+
+## In FormRequests
+
+```php
+public function authorize(): bool
+{
+    /** @var Order $order */
+    $order = $this->route('order');
+
+    /** @var User $user */
+    $user = $this->user();
+
+    return $user->can('update', $order);
+}
+```
+
+## Rules
+
+- One Policy per Model — `App\Policies\{Model}Policy`
+- Keep policy methods simple — delegate complex checks to the model or a service
+- Return `bool` — no exceptions in policies
+- Laravel auto-discovers policies by convention (no manual registration needed)
+
+## When NOT to Use
+
+❌ Global rules (e.g., "must be authenticated") — use middleware instead
+❌ Business rules (e.g., "order must have items") — that's validation, not authorization
+

package/.agent-src/guidelines/php/patterns/repositories.md

@@ -0,0 +1,122 @@
+# Repository Pattern
+
+> Only use when it solves a real problem. Eloquent already has many repository-like features built in.
+
+## Purpose
+
+Repositories encapsulate **complex or reusable** database queries. They keep controllers and
+services clean by hiding query details behind expressive method names.
+
+## Rule of Thumb
+
+- **CRUD app** → usually no separate repository needed
+- **Complex business app** → use selectively where it adds value
+- **Never** create a repository automatically for every model
+
+## When to Use a Repository
+
+✅ **Multiple data sources** — DB + API + Cache behind one interface
+
+✅ **Complex queries** — joins, subqueries, raw expressions, aggregations:
+
+```php
+// ✅ Good — complex query with joins, eager loading, raw ordering
+class DatabasePlanningRepository
+{
+    public function findByDateAndCrewIds(CarbonInterface $date, array $crewIds): Collection
+    {
+        return Appointment::with([
+                'project' => ['manager', 'capacityPlanningItem'],
+                'plannedUsers' => fn ($q) => $q->where('termin_date', $date->format('Y-m-d')),
+            ])
+            ->selectRaw("*, IF(termin_uhrzeit IS NULL OR termin_uhrzeit = '00:00:00', 1, 0) as sort_order")
+            ->whereDate('termin_date', $date)
+            ->whereIn('tree_group_id', $crewIds)
+            ->orderByRaw('termin_order, sort_order, termin_uhrzeit')
+            ->get();
+    }
+}
+```
+
+✅ **Reusable queries** — same complex query needed in multiple services or controllers
+
+✅ **Domain-centric access** — the method name documents business intent:
+
+```php
+$repository->findActiveEmployeesWithExpiredCertificates();
+$repository->findOverdueAppointmentsByCustomer($customerId);
+```
+
+## When NOT to Use a Repository
+
+❌ **Thin CRUD wrappers** — wrapping `findById`, `create`, `update`, `delete` around
+Eloquent adds a layer with zero value. Eloquent already provides all of this:
+
+```php
+// ❌ Overengineering — don't do this
+class UserRepository
+{
+    public function findById(int $id): ?User { return User::find($id); }
+    public function create(array $data): User { return User::create($data); }
+    public function delete(int $id): void { User::destroy($id); }
+}
+
+// ✅ Just use the model directly
+$user = User::find($id);
+$user = User::where('email', $email)->first();
+$activeUsers = User::where('is_active', true)->get();
+```
+
+❌ **Single-use queries** — if a query is only used in one place and is not complex,
+keep it inline in the service or controller.
+
+## Better Alternatives for Simple Cases
+
+Instead of a repository for every model, prefer:
+
+- **Query Scopes** — reusable query fragments on the model itself
+- **Services / Actions** — business logic with inline queries
+- **Specialized query classes** — for one complex, reusable query
+
+## Structure
+
+- Namespace: `App\Repositories\{Domain}\` or `App\Modules\{Module}\App\Repositories\`
+- Use an **interface** (contract) when the repository is injected via DI and may need mocking:
+
+```php
+// Contract
+interface UserRepositoryContract
+{
+    public function findByCredentials(string $username, string $password): User;
+}
+
+// Implementation
+class DatabaseUserRepository implements UserRepositoryContract
+{
+    public function findByCredentials(string $username, string $password): User
+    {
+        // complex query logic...
+    }
+}
+```
+
+- Bind interface → implementation in a ServiceProvider
+- Do **NOT** mark repository classes `final` — they may need to be mocked in tests
+
+## Naming
+
+| Pattern                    | Example                              |
+|----------------------------|--------------------------------------|
+| Contract (interface)       | `UserRepositoryContract`             |
+| Implementation             | `DatabaseUserRepository`             |
+| Module repository          | `ClientSoftwareImportTemplateRepository` |
+
+## Rules
+
+- Return **typed** results: `Collection<int, Model>`, `?Model`, `Model`
+- Throw domain exceptions (e.g., `EntityNotFoundException`) instead of returning `null`
+  when the caller expects a result
+- Use `@param` and `@return` DocBlocks for generic collection types
+- Keep repositories focused — one repository per model/aggregate, not one giant "query bag"
+- Prefer Eloquent/Query Builder over raw SQL
+

package/.agent-src/guidelines/php/patterns/service-layer.md

@@ -0,0 +1,64 @@
+# Service Layer / Action Pattern
+
+> The most valuable pattern in Laravel projects.
+
+## Idea
+
+Controllers stay thin and delegate business logic to dedicated classes.
+These classes have a single responsibility and an expressive name.
+
+## Naming
+
+- **Action** — single operation: `CreateOrderAction`, `PublishArticle`
+- **Service** — broader domain scope: `PaymentService`, `ImportService`
+
+Use Actions for focused, one-off operations. Use Services when grouping related operations.
+
+## When to Use
+
+✅ Logic is more than "validate + save"
+✅ Logic is reused across controllers, commands, observers or jobs
+✅ Logic involves multiple models, external APIs, or side effects
+✅ You want to test business logic independently from HTTP layer
+
+## When NOT to Use
+
+❌ Simple CRUD — `$model->update($request->validated())` can stay in the controller
+❌ One-liner logic — don't create a class for a single Eloquent call
+
+## Example
+
+```php
+final class CreateOrderAction
+{
+    public function __construct(
+        private PaymentService $paymentService,
+        private NotificationService $notificationService,
+    ) {}
+
+    public function execute(CreateOrderDTO $data): Order
+    {
+        $order = Order::create($data->toArray());
+
+        $this->paymentService->charge($order);
+        $this->notificationService->sendOrderConfirmation($order);
+
+        return $order;
+    }
+}
+```
+
+## In Controllers
+
+Inject via constructor or method injection:
+
+```php
+public function __invoke(
+    CreateOrderRequest $request,
+    CreateOrderAction $action,
+): OrderResource {
+    $order = $action->execute(CreateOrderDTO::fromRequest($request));
+    return OrderResource::make($order);
+}
+```
+

package/.agent-src/guidelines/php/patterns/strategy.md

@@ -0,0 +1,69 @@
+# Strategy Pattern
+
+> Choose the right algorithm at runtime — instead of if/else chains.
+
+## Idea
+
+Define a family of interchangeable algorithms behind an interface.
+Select the implementation based on context (config, user input, enum value).
+
+## Typical Use Cases
+
+- Payment providers (Stripe, PayPal, Invoice)
+- Export formats (CSV, PDF, Excel)
+- Pricing / discount rules
+- Notification channels (Email, SMS, Push)
+- Import parsers (JSON, XML, CSV)
+
+## Example
+
+```php
+interface DiscountStrategy
+{
+    public function calculate(int $subtotalInCents): int;
+}
+
+final class PercentageDiscount implements DiscountStrategy
+{
+    public function __construct(private int $percent) {}
+
+    public function calculate(int $subtotalInCents): int
+    {
+        return Math::divide(Math::multiply($subtotalInCents, $this->percent), 100);
+    }
+}
+
+final class FixedDiscount implements DiscountStrategy
+{
+    public function __construct(private int $amountInCents) {}
+
+    public function calculate(int $subtotalInCents): int
+    {
+        return min($this->amountInCents, $subtotalInCents);
+    }
+}
+```
+
+## Selection via Enum
+
+```php
+enum DiscountType: string
+{
+    case PERCENTAGE = 'percentage';
+    case FIXED = 'fixed';
+
+    public function strategy(int $value): DiscountStrategy
+    {
+        return match ($this) {
+            self::PERCENTAGE => new PercentageDiscount($value),
+            self::FIXED => new FixedDiscount($value),
+        };
+    }
+}
+```
+
+## When NOT to Use
+
+❌ Only two cases with trivial logic — a simple `match` or ternary is enough
+❌ The "strategies" share no common interface or behavior
+