@event4u/agent-config 1.9.1

package/.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

package/.agent-src/guidelines/php/performance.md

@@ -0,0 +1,92 @@
+# Performance Guidelines
+
+> Performance conventions — caching, Redis, eager loading, query optimization, response time targets.
+
+**Related Skills:** `performance`, `database`
+**Related Guidelines:** [database.md](database.md), [eloquent.md](eloquent.md)
+
+## Caching
+
+### Cache driver
+
+Redis is the primary cache driver (also used for queues and sessions).
+Config: `config/cache.php`, `config/database.php` (Redis connections).
+
+### Patterns
+
+```php
+// TTL-based
+$value = Cache::remember('key', now()->addMinutes(30), fn () => ExpensiveQuery::run());
+
+// Forever (manual invalidation)
+Cache::forever('key', $value);
+
+// Invalidate
+Cache::forget('key');
+```
+
+### Cache invalidation
+
+- Invalidate when underlying data changes.
+- Use event-driven invalidation — model events clear related caches.
+- Use cache tags (when supported) for group invalidation.
+- Prefer short TTLs over complex invalidation logic.
+
+### Multi-tenant caching
+
+**Always include tenant/customer ID in cache keys:**
+
+```php
+// ✅ Tenant-scoped
+$key = "customer:{$customerId}:projects:count";
+
+// ❌ Shared across tenants
+$key = "projects:count";
+```
+
+## Eager Loading
+
+- Always eager load relationships used in API Resources.
+- Use `with()` at query level — not `$with` model property.
+- Use `withCount()` for counting without loading.
+- Use `load()` for lazy eager loading.
+
+## Query Patterns
+
+```php
+$count = Project::query()->where('status', 'active')->count();
+$exists = Project::query()->where('email', $email)->exists();
+$ids = Project::query()->pluck('id');
+$total = Order::query()->sum('amount');
+```
+
+Use `DB::enableQueryLog()` during development to detect N+1 queries.
+
+## Background Jobs
+
+Queue when: email/notification sending, external API calls, heavy calculations, import/export.
+
+## Redis Patterns
+
+- Cache: standard key-value
+- Queues: job backend via Horizon
+- Rate limiting: `RateLimiter` facade
+- Locks: `Cache::lock()` for distributed locking
+
+## Response Time Targets
+
+| Endpoint type | Target |
+|---|---|
+| Simple CRUD | < 200ms |
+| Complex queries | < 500ms |
+| List endpoints | Always paginated |
+| Background jobs | No strict limit (monitor via Horizon) |
+
+## Do NOT
+
+- Cache without tenant isolation in multi-tenant contexts.
+- Use `get()` or `all()` on large tables — paginate or chunk.
+- Run heavy computation synchronously in API requests — queue it.
+- Add indexes blindly — analyze query patterns first.
+- Use `sleep()` or long-running loops in web requests.
+- Assume cache is always available — handle misses gracefully.

package/.agent-src/guidelines/php/resources.md

@@ -0,0 +1,100 @@
+# API Resource Guidelines
+
+> Project-specific API Resource conventions. Base class, versioning (v1/v2), OpenAPI schemas.
+
+**Related Skills:** `api-endpoint`, `api-design`, `openapi`
+**Related Guidelines:** [controllers.md](controllers.md)
+
+## Core Rule
+
+**Every controller MUST return an API Resource** — never return raw arrays, models, or `response()->json()`.
+
+## Base Class
+
+Extend `App\Http\Resources\JsonResource` (not Laravel's base class directly).
+
+## Resource Structure
+
+```php
+use App\Http\Resources\JsonResource;
+use App\Models\ExternalCustomerDatabase\Link\Link;
+use OpenApi\Attributes as OA;
+
+#[OA\Schema(
+    schema: 'v2_Link',
+    properties: [
+        new IntegerProperty(property: 'id', example: 1),
+        new StringProperty(property: 'text', example: 'Example link'),
+    ]
+)]
+class LinkResource extends JsonResource
+{
+    /** @var Link */
+    public $resource;
+
+    public static $wrap = 'data';
+
+    /** @return array<string, mixed> */
+    public function toArray($request): array
+    {
+        $link = $this->resource;
+
+        return [
+            'id' => $link->getId(),
+            'text' => $link->getText(),
+        ];
+    }
+}
+```
+
+## Required Elements
+
+| Element | Rule |
+|---|---|
+| `/** @var ModelClass */` on `$resource` | Always — types the resource for PHPStan and OpenAPI |
+| `public static $wrap = 'data';` | Required for v2 resources. v1 resources use `$wrap = null` |
+| `#[OA\Schema(...)]` | Required — OpenAPI documentation |
+| `/** @return array<string, mixed> */` | PHPDoc on `toArray()` |
+
+## Controller Return Types
+
+Controllers MUST type-hint the return value as the Resource class:
+
+```php
+// Single resource
+public function __invoke(ShowRequest $request, Project $project): ProjectResource
+{
+    return ProjectResource::make($project);
+}
+
+// Collection
+public function __invoke(ListRequest $request): ResourceCollection
+{
+    return ProjectResource::collection($projects);
+}
+```
+
+## Key Conventions
+
+- **Type `$resource`** via `@var` PHPDoc — do NOT cast inline in `toArray()`
+- **Use getter methods** on the model (`$link->getId()`), not direct attribute access (`$link->id`)
+- **Use `Resource::make()`** in controllers, not `new Resource()`
+- **Nested resources**: use `::make()` for single items, `::collection()` for lists
+- **Conditional null**: `$model->getRelation() ? RelatedResource::make($model->getRelation()) : null`
+
+## Versioning
+
+| Version | Property Names | `$wrap` |
+|---|---|---|
+| **v1** | Clean English (`number`, `status`, `title`) | `null` |
+| **v2** | Legacy DB columns (`nr_lv`, `lv_status`, `bezeichnung`) | `'data'` |
+
+## Resource Variants
+
+| Pattern | Example | Purpose |
+|---|---|---|
+| `{Entity}Resource` | `ProjectResource` | Full entity |
+| `{Entity}MinimalResource` | `ProjectMinimalResource` | Lightweight for lists |
+| `Simple{Entity}Resource` | `SimpleUserResource` | Embedded in other resources |
+| `{Entity}StatisticsResource` | `ProjectStatisticsResource` | Aggregated data |
+

package/.agent-src/guidelines/php/security.md

@@ -0,0 +1,110 @@
+# Security Guidelines
+
+> Security conventions — authentication, authorization, input validation, SQL injection, XSS, CSRF, headers.
+
+**Related Skills:** `security`, `laravel-validation`
+**Related Guidelines:** [validations.md](validations.md)
+
+## Authentication
+
+- Check `tymon/jwt-auth` or `laravel/sanctum` in `composer.json`.
+- Check `config/auth.php` for guards and providers.
+- API: JWT tokens or API keys (depending on endpoint).
+- Customer identification after auth — see `multi-tenancy` skill.
+
+## Authorization (Policies)
+
+```php
+// In FormRequest
+public function authorize(): bool
+{
+    return $this->user()->can('view', $this->route('project'));
+}
+
+// In Controller
+$this->authorize('update', $project);
+```
+
+- Create policies in `app/Policies/`.
+- Register in `AuthServiceProvider` (if not auto-discovery).
+- Check `agents/gates.md` for custom gates.
+
+## Input Validation
+
+- Always use FormRequest classes — never validate in controllers.
+- Be specific: types, lengths, formats.
+- Never trust client-side validation.
+
+```php
+// ✅ Strict
+'email' => ['required', 'email:rfc,dns', 'max:255'],
+'amount' => ['required', 'decimal:0,2', 'min:0', 'max:999999.99'],
+```
+
+## SQL Injection Prevention
+
+- Always use Eloquent or Query Builder (parameterized by default).
+- Never concatenate user input into raw SQL.
+- Use `DB::raw()` only for expressions, never with user input.
+
+## XSS Prevention
+
+- API: use API Resource classes (no HTML rendering).
+- Blade: `{{ }}` (escaped) — never `{!! !!}` with user input.
+- Sanitize HTML input for rich text (`htmlpurifier`).
+
+## CSRF
+
+- API routes excluded (token-based auth).
+- Web routes have CSRF via `VerifyCsrfToken` middleware.
+
+## Rate Limiting
+
+- Apply to auth endpoints (login, password reset).
+- Use `throttle:` middleware on sensitive routes.
+- Check `RouteServiceProvider` or `bootstrap/app.php` for definitions.
+
+## Sensitive Data
+
+- Never log passwords, tokens, API keys.
+- `encrypt()` / `decrypt()` for sensitive data at rest.
+- Environment variables for secrets — never hardcode.
+
+## Security Headers
+
+| Header | Value |
+|---|---|
+| `X-Content-Type-Options` | `nosniff` |
+| `X-Frame-Options` | `DENY` or `SAMEORIGIN` |
+| `Strict-Transport-Security` | `max-age=31536000; includeSubDomains` |
+| `Content-Security-Policy` | Project-specific |
+| `Referrer-Policy` | `strict-origin-when-cross-origin` |
+
+Set in middleware — not in individual controllers. CORS: `config/cors.php`.
+
+## Session Security
+
+- `httpOnly` and `secure` flags on cookies.
+- `SameSite=Lax` or `Strict`.
+- Regenerate session ID after login.
+
+## Mass Assignment
+
+```php
+// ✅ Only validated data
+$project = Project::create($request->validated());
+
+// ❌ Dangerous
+$project = Project::create($request->all());
+```
+
+## Do NOT
+
+- Bypass FormRequest validation.
+- Use `$request->all()` for mass assignment.
+- Disable CSRF for web routes.
+- Store plaintext passwords/secrets.
+- Expose internal error details in production.
+- Trust `X-Forwarded-For` without proxy config.
+- Use `md5()`/`sha1()` for password hashing.
+- Store tokens in localStorage — use httpOnly cookies.

package/.agent-src/guidelines/php/sql.md

@@ -0,0 +1,97 @@
+# SQL Guidelines
+
+> Raw SQL conventions — parameterization, MariaDB/MySQL syntax, common mistakes.
+
+**Related Skills:** `sql-writing`, `database`
+**Related Guidelines:** [database.md](database.md)
+
+## Iron Law
+
+```
+NEVER build SQL strings with PHP variable interpolation or concatenation.
+ALWAYS use parameterized queries or query builder.
+```
+
+## Parameterized Queries
+
+```php
+// ✅ Correct
+DB::select('SELECT * FROM users WHERE email = ?', [$email]);
+DB::select('SELECT * FROM users WHERE email = :email', ['email' => $email]);
+
+// ❌ DANGEROUS
+DB::select("SELECT * FROM users WHERE email = '{$email}'");
+```
+
+## Raw Expressions in Eloquent
+
+```php
+// ✅ DB::raw with static SQL
+User::query()->select(DB::raw('COUNT(*) as count, status'))->groupBy('status')->get();
+
+// ✅ selectRaw with bindings
+Order::query()->selectRaw('SUM(total) as revenue')->whereRaw('created_at >= ?', [$start])->get();
+
+// ❌ PHP variable in raw SQL
+Order::query()->whereRaw("created_at >= '{$start}'")->get();
+```
+
+## Common Mistakes
+
+```php
+// ❌ PHP array syntax in SQL
+DB::statement("UPDATE users SET roles = ['admin'] WHERE id = 1");
+// ✅ SQL JSON syntax
+DB::statement("UPDATE users SET roles = JSON_ARRAY('admin') WHERE id = ?", [1]);
+
+// ❌ PHP null
+DB::statement("UPDATE users SET deleted_at = null WHERE id = 1");
+// ✅ SQL NULL
+DB::statement('UPDATE users SET deleted_at = NULL WHERE id = ?', [1]);
+
+// ❌ PHP boolean
+DB::statement("UPDATE users SET active = true WHERE id = 1");
+// ✅ MariaDB uses 1/0
+DB::statement('UPDATE users SET active = 1 WHERE id = ?', [1]);
+
+// ❌ String concat for IN
+$ids = implode(',', $userIds);
+DB::select("SELECT * FROM users WHERE id IN ({$ids})");
+// ✅ Query builder
+DB::table('users')->whereIn('id', $userIds)->get();
+```
+
+## MariaDB/MySQL Syntax
+
+```sql
+-- String quoting: single quotes for values, backticks for identifiers
+SELECT `user`.`name` FROM `users` WHERE `name` = 'John';
+
+-- JSON columns (MariaDB 10.2+)
+SELECT JSON_VALUE(settings, '$.theme') FROM users;
+
+-- UPSERT
+INSERT INTO counters (key, value) VALUES ('visits', 1) ON DUPLICATE KEY UPDATE value = value + 1;
+
+-- Date functions
+SELECT * FROM orders WHERE created_at >= DATE_SUB(NOW(), INTERVAL 30 DAY);
+```
+
+## When Raw SQL is Needed
+
+| Use case | Raw SQL needed? |
+|---|---|
+| Standard CRUD, filtering, joins | No — query builder |
+| Complex subqueries, window functions | Yes |
+| Performance-critical index hints | Yes |
+| Bulk operations (INSERT...SELECT) | Yes |
+| Full-text search (MATCH...AGAINST) | Yes |
+
+## Do NOT
+
+- Interpolate PHP variables into SQL — always parameterize.
+- Use PHP syntax in raw SQL — use SQL equivalents.
+- Use `float` for money — use `DECIMAL(10, 2)`.
+- Forget backtick quoting for reserved words as column names.
+- Use `OFFSET` for large table pagination — use cursor.
+- Write raw SQL when query builder can express it clearly.

package/.agent-src/guidelines/php/validations.md

@@ -0,0 +1,119 @@
+# Validation Guidelines
+
+> Project-specific FormRequest conventions. Array syntax, route params, property mapping.
+
+**Related Skills:** `laravel-validation`, `api-endpoint`
+**Related Guidelines:** [controllers.md](controllers.md)
+
+## Core Rules
+
+- Every controller has a matching FormRequest: `{Action}{Entity}Request`
+- Every FormRequest **must** have an `authorize()` method (using Policies)
+- Validation messages **should** use translations (`__('validation.xxx')`)
+
+## Rule Syntax
+
+Always use **array syntax** for rules — never pipe-separated strings.
+
+```php
+// ✅ Good
+'email' => ['required', 'email', 'max:60'],
+
+// ❌ Bad
+'email' => 'required|email|max:60',
+```
+
+Use Laravel's `Illuminate\Validation\Rules` classes when possible:
+
+```php
+// ✅ Good
+'email' => [new Exists('connection.staff', 'email')],
+
+// ❌ Bad
+'email' => ['exists:connection.staff,email'],
+```
+
+## Route Parameters
+
+Validate route parameters via `prepareForValidation()`:
+
+```php
+public function prepareForValidation(): void
+{
+    /** @var Project $project */
+    $project = $this->route('project');
+
+    $this->merge([
+        'latitude' => $project->getLatitude(),
+        'longitude' => $project->getLongitude(),
+    ]);
+}
+```
+
+## Property Mapping
+
+When request keys differ from model properties, handle mapping in the FormRequest
+(not in Controller or Service):
+
+```php
+// ✅ Best — FormRequest as single source of truth
+public function prepareForValidation(): void
+{
+    $this->merge([
+        'id' => $this->input('user_id'),
+        'name' => $this->input('user_name'),
+    ]);
+    $this->offsetUnset('user_id');
+    $this->offsetUnset('user_name');
+}
+```
+
+## Inline vs FormRequest
+
+- Inline: only for small, truly local cases.
+- FormRequest: when validation is reused, complex, involves authorization, nested structures, or custom messages.
+
+## Conditional Validation
+
+- Use Laravel's conditional features intentionally.
+- Keep conditions readable.
+- Complex conditions → normalize first, then compose clearer rules.
+
+## Nested and Array Input
+
+- Be explicit with nested keys and wildcard rules.
+- Validate structure as well as leaf values.
+- Don't accept loosely structured input when shape matters.
+
+## File Validation
+
+- Validate presence, type, size explicitly.
+- Don't trust client-provided metadata alone.
+- Align with downstream processing expectations.
+
+## Custom Rules
+
+- Create custom rule objects when logic is reused or domain-specific.
+- Keep custom rules focused on validation only — no side effects.
+- Custom Rule objects must return `$fail` callback, not throw exceptions.
+
+## Authorization Boundary
+
+- Use `authorize()`, policies, or gates consistently.
+- Keep authorization failure and validation failure conceptually separate.
+- Don't mix role/business auth logic into validation rules.
+
+## API Validation
+
+- Respect existing API error response structure.
+- Keep validation consistent across endpoints.
+- Don't introduce a new validation response shape in an established API.
+
+## Do NOT
+
+- Validate in controllers — use FormRequests.
+- Use `$request->all()` — use `$request->validated()`.
+- Skip validation for API endpoints.
+- Put business logic in validation classes.
+- Create custom rules when built-in rules suffice.
+

package/.agent-src/guidelines/php/websocket.md

@@ -0,0 +1,100 @@
+# WebSocket Guidelines
+
+> WebSocket conventions — Laravel Broadcasting, channel types, connection management, payloads.
+
+**Related Skills:** `websocket`, `laravel-reverb`
+
+## Laravel Broadcasting Setup
+
+```php
+// config/broadcasting.php
+'connections' => [
+    'reverb' => [
+        'driver' => 'reverb',
+        'key' => env('REVERB_APP_KEY'),
+        'secret' => env('REVERB_APP_SECRET'),
+    ],
+],
+```
+
+## Broadcasting Events
+
+```php
+class OrderStatusUpdated implements ShouldBroadcast
+{
+    use Dispatchable, InteractsWithSockets, SerializesModels;
+
+    public function __construct(public readonly Order $order) {}
+
+    public function broadcastOn(): array
+    {
+        return [new PrivateChannel('orders.' . $this->order->customer_id)];
+    }
+
+    public function broadcastAs(): string
+    {
+        return 'order.status.updated';
+    }
+
+    public function broadcastWith(): array
+    {
+        return [
+            'order_id' => $this->order->id,
+            'status' => $this->order->status,
+        ];
+    }
+}
+```
+
+## Channel Types
+
+| Type | Prefix | Auth | Use case |
+|---|---|---|---|
+| Public | none | No | Public notifications, live feeds |
+| Private | `private-` | Yes | User-specific updates |
+| Presence | `presence-` | Yes | Who's online, collaborative editing |
+
+## Channel Authorization
+
+```php
+// routes/channels.php
+Broadcast::channel('orders.{customerId}', function (User $user, int $customerId) {
+    return $user->customer_id === $customerId;
+});
+```
+
+## Client (Laravel Echo)
+
+```ts
+echo.private(`orders.${customerId}`)
+  .listen('.order.status.updated', (event) => {
+    console.log('Order updated:', event.order_id, event.status)
+  })
+```
+
+## Connection Management
+
+### Reconnection
+
+Exponential backoff: `delay = min(1000 * 2^retryCount, 30000)`, max 10 retries.
+
+### Heartbeat
+
+- Server ping every 30s, client responds with pong.
+- No pong within 10s → close and reconnect.
+
+## Core Rules
+
+- Always authorize private and presence channels.
+- Keep payloads small — IDs and changed fields, not full objects.
+- Implement reconnection with exponential backoff.
+- Use heartbeats to detect dead connections.
+- Handle offline gracefully — queue messages, sync on reconnect.
+- Use `broadcastWith()` to control the payload.
+
+## Do NOT
+
+- Send entire model objects — select only needed fields.
+- Rely on WebSocket delivery — use acknowledgments.
+- Skip channel authorization for user-specific data.
+- Create too many channels — group related events.