@event4u/agent-config 14.22.0 → 15.0.0

package/dist/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/dist/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/dist/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/dist/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/dist/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/dist/agent-src/guidelines/php/patterns/strategy.md

@@ -0,0 +1,247 @@
+# 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)
+
+## Sniff test — when an enum/string discriminator wants to become a Strategy
+
+Run these three questions **before** writing a second `match`/`switch` arm,
+a second `if/elseif` branch, or a second hardcoded class per provider/type.
+Two "yes" answers → extract Strategy + Registry. Three "yes" → it is
+already overdue.
+
+1. **Same-shape branches?** Do two or more branches/classes implement the
+   *same operation* on the *same data*, differing only in provider-specific
+   details (URL, field mapping, credentials, response parsing)?
+2. **Closed-list edits?** Adding a new case requires editing an enum, a
+   `match` block, an allowlist constant, *and* a service class — i.e. the
+   change is mechanical but spans ≥3 files?
+3. **Discriminator leakage?** Does the discriminator (`Type::FOO`,
+   `'stripe'`, an `is_csv()` check) appear in ≥3 places that should not
+   have to know about `FOO` specifically?
+
+If yes → see *Refactoring recipe* below.
+
+## 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),
+        };
+    }
+}
+```
+
+## Refactoring recipe — from discriminator to Strategy
+
+Two anti-patterns appear in real codebases and both refactor into the same
+Strategy + Registry shape. Each step is a separate commit so reviewers can
+follow the safety chain.
+
+### Sub-pattern A — *hardcoded single provider per class*
+
+Each provider gets its own `FooImportService`, `FooJob`, `FooCommand`,
+and every method body repeats `Provider::FOO->value` or
+`Provider::FOO->getId()`. Adding a new provider means copy-pasting an
+entire class tree.
+
+```php
+// Before — one class per provider, discriminator hardcoded.
+final class StripeImportService
+{
+    public function id(): int     { return Provider::STRIPE->getId(); }
+    public function name(): string { return Provider::STRIPE->value; }
+    public function import(): void { /* Stripe-specific logic */ }
+}
+
+final class PaypalImportService
+{
+    public function id(): int     { return Provider::PAYPAL->getId(); }
+    public function name(): string { return Provider::PAYPAL->value; }
+    public function import(): void { /* PayPal-specific logic */ }
+}
+```
+
+```php
+// After — one interface, N strategies, one registry.
+interface ImportStrategy
+{
+    public function provider(): Provider;
+    public function import(): void;
+}
+
+final class StripeImport implements ImportStrategy
+{
+    public function provider(): Provider { return Provider::STRIPE; }
+    public function import(): void       { /* Stripe-specific logic */ }
+}
+// ...PaypalImport implements ImportStrategy similarly.
+```
+
+Recipe (one commit per step):
+
+1. Extract the interface (`ImportStrategy`) and move one provider class
+   to implement it. Existing call sites keep using the old class.
+2. Repeat for the remaining providers — still no callers changed.
+3. Introduce the Registry (next section). Migrate call sites one by one
+   from `new StripeImportService()` to `$registry->for(Provider::STRIPE)`.
+4. Delete the old per-provider classes.
+
+### Sub-pattern B — *allowlist constant on a single coordinator*
+
+A central service holds an allowlist of supported discriminator values.
+Every new provider edits the constant *and* a method that branches on it.
+
+```php
+// Before — closed-list edit per new provider.
+final class EquipmentImportService
+{
+    private const FULL_SYNC_PROVIDERS = [
+        Provider::STRIPE,
+        Provider::PAYPAL,
+        Provider::INVOICE,
+    ];
+
+    public function supportsFullSync(Provider $p): bool
+    {
+        return in_array($p, self::FULL_SYNC_PROVIDERS, true);
+    }
+}
+```
+
+The fix is a **capability flag on the strategy interface** — the strategy
+declares its own capabilities, and the coordinator asks the strategy
+instead of consulting an allowlist.
+
+```php
+interface ImportStrategy
+{
+    public function provider(): Provider;
+    public function import(): void;
+    public function supportsFullSync(): bool;   // capability flag
+}
+```
+
+A new provider now adds itself by implementing the interface — no central
+list to edit, no in_array call to maintain. The coordinator becomes:
+
+```php
+$strategy = $registry->for($provider);
+if ($strategy->supportsFullSync()) {
+    $strategy->fullSync();
+}
+```
+
+## Registry companion
+
+A Registry resolves the discriminator → strategy lookup that previously
+lived in the `match` block. It owns the only place the enum is mapped to
+classes; everything downstream sees only the interface.
+
+```php
+final class ImportStrategyRegistry
+{
+    /** @var array<string, ImportStrategy> */
+    private array $byProvider;
+
+    /** @param iterable<ImportStrategy> $strategies */
+    public function __construct(iterable $strategies)
+    {
+        foreach ($strategies as $strategy) {
+            $this->byProvider[$strategy->provider()->value] = $strategy;
+        }
+    }
+
+    public function for(Provider $provider): ImportStrategy
+    {
+        return $this->byProvider[$provider->value]
+            ?? throw new InvalidArgumentException(
+                "No import strategy registered for {$provider->value}"
+            );
+    }
+}
+```
+
+Wire-up in Laravel — tag the strategies, inject the tag into the registry:
+
+```php
+// In a ServiceProvider::register()
+$this->app->tag([
+    StripeImport::class,
+    PaypalImport::class,
+    InvoiceImport::class,
+], 'import.strategies');
+
+$this->app->bind(
+    ImportStrategyRegistry::class,
+    fn ($app) => new ImportStrategyRegistry($app->tagged('import.strategies')),
+);
+```
+
+A new provider now adds itself by:
+
+1. Implementing `ImportStrategy`.
+2. Adding one line to the `tag()` call.
+
+No `match` block grows. No allowlist edits. No coordinator method changes.
+
+## When NOT to Use
+
+❌ Only two cases with **trivial logic** — a simple `match` or ternary is
+   enough. *"Trivial"* means the two arms each fit on one line and share
+   no structural shape. Two arms that each call a method on a service
+   are not trivial — see the sniff test.
+❌ The "strategies" share no common interface or behavior — if the
+   operations differ, you do not have a Strategy candidate.
+❌ The discriminator is set once at boot and never re-evaluated — a
+   single binding in the container is simpler than a Registry.
+

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

@@ -0,0 +1,28 @@
+# Design Patterns
+
+> Proven patterns for PHP / Laravel projects. Use them when they reduce complexity, not when they add it.
+
+**Related Skills:** `php-service`, `dto-creator`, `jobs-events`, `security`, `eloquent`
+**Related Rules:** `scope-control.md`, `architecture.md`
+
+## Overview
+
+| Pattern | Skill | When to use |
+|---|---|---|
+| [Service Layer / Actions](patterns/service-layer.md) | `php-service` | Business logic that doesn't belong in controllers |
+| [Dependency Injection](patterns/dependency-injection.md) | `php-service` | Decouple classes from concrete implementations |
+| [Strategy](patterns/strategy.md) | `php-coder` | Multiple interchangeable algorithms at runtime |
+| [Factory](patterns/factory.md) | `php-coder` | Complex object creation |
+| [DTOs / Value Objects](patterns/dtos.md) | `dto-creator` | Structured data instead of untyped arrays |
+| [Policies](patterns/policies.md) | `security` | Centralized authorization logic |
+| [Events / Listeners](patterns/events.md) | `jobs-events` | Decoupled side effects (mails, logs, syncs) |
+| [Pipeline / Middleware](patterns/pipelines.md) | `laravel` | Sequential processing steps / filter chains |
+| [Repository](patterns/repositories.md) | `eloquent` | Complex or reusable database queries |
+
+## When NOT to Use Patterns
+
+- Don't introduce a pattern for a 5-line function
+- Don't create an interface if there will only ever be one implementation
+- Don't use events for everything — direct calls are easier to follow
+- Don't wrap simple Eloquent queries in repositories
+- KISS and YAGNI always trump pattern purity