@baldurpan/create-ai-workflow 0.2.0

package/templates/standards/php/frameworks.md

@@ -0,0 +1,197 @@
+# PHP Frameworks
+
+## Decision Matrix
+
+| Project type | Recommended framework |
+|---|---|
+| Product team, API, internal tool, startup | **Laravel** |
+| Large enterprise, long-lived platform, complex domain | **Symfony** |
+| Lightweight API, custom architecture, minimal system | **Slim** |
+| No framework needed | Plain PHP with chosen PSR components |
+
+Pick one and stick with it. Don't mix frameworks in the same service.
+
+## Laravel
+
+Best for: product teams, rapid development, startups, internal systems, APIs.
+
+### Strengths
+
+- Excellent developer experience
+- Mature ecosystem (Cashier, Horizon, Nova, Telescope, Sanctum)
+- Strong tooling for queues, auth, testing
+- Eloquent for fast development
+
+### Risks
+
+- Facade overuse leads to hidden coupling
+- Magic-heavy patterns hurt long-term maintainability
+- Fat models and fat controllers are common anti-patterns
+- Easy to skip layered architecture and regret it later
+
+### Laravel-Specific Patterns
+
+#### DO
+
+- **Form Requests** for validation — keep validation out of controllers
+- **Service classes / Application handlers** for business logic — keep controllers thin
+- **Jobs, Events, Listeners** for async work and decoupling
+- **Policies** for authorization
+- **API Resources** for response serialization
+- **Scoped bindings** to avoid duplicated singletons
+- **Eager loading** (`with()`) to prevent N+1 queries
+- **Form requests + DTOs together** — Form Request validates, then maps to a DTO that the handler consumes
+
+#### DO NOT
+
+- Put business logic in routes (`Route::post('/...', fn () => /* logic */)`)
+- Put business logic in controllers
+- Put business logic in Eloquent models (keep them as data + relationships)
+- Build massive `AppServiceProvider`s — split into focused providers
+- Define magic macros for core business logic — use explicit classes
+- Use global helpers (`auth()`, `request()`, `now()`) inside domain/application code — inject instead
+
+### Example: Thin Controller + Handler + DTO
+
+```php
+// app/Http/Requests/CreateInvoiceRequest.php
+final class CreateInvoiceRequest extends FormRequest
+{
+    public function rules(): array
+    {
+        return [
+            'customer_id' => ['required', 'uuid'],
+            'amount' => ['required', 'integer', 'min:1'],
+            'currency' => ['required', 'in:USD,EUR,GBP'],
+        ];
+    }
+
+    public function toDto(): CreateInvoiceDto
+    {
+        return new CreateInvoiceDto(
+            customerId: $this->validated('customer_id'),
+            amount: new Money($this->validated('amount'), $this->validated('currency')),
+        );
+    }
+}
+
+// app/Application/Invoices/CreateInvoiceHandler.php
+final readonly class CreateInvoiceHandler
+{
+    public function __construct(
+        private InvoiceRepository $invoices,
+        private EventDispatcher $events,
+    ) {}
+
+    public function handle(CreateInvoiceDto $dto): Invoice
+    {
+        $invoice = Invoice::create($dto);
+        $this->events->dispatch(new InvoiceCreated($invoice));
+        return $invoice;
+    }
+}
+
+// app/Http/Controllers/CreateInvoiceController.php
+final class CreateInvoiceController
+{
+    public function __construct(private CreateInvoiceHandler $handler) {}
+
+    public function __invoke(CreateInvoiceRequest $request): JsonResponse
+    {
+        $invoice = $this->handler->handle($request->toDto());
+        return new JsonResponse(InvoiceResource::from($invoice), 201);
+    }
+}
+```
+
+### Recommended Companions
+
+- **Pest** — testing
+- **Larastan** (`nunomaduro/larastan`) — PHPStan for Laravel
+- **Pint** — formatting
+- **Horizon** — queue dashboard
+- **Telescope** — local debugging
+- **Sanctum** — API tokens / SPA auth
+
+## Symfony
+
+Best for: large enterprise systems, long-lived platforms, highly structured teams, complex domains.
+
+### Strengths
+
+- Explicit, predictable architecture
+- Powerful DI container with autowiring
+- Stable, mature, conservative release cadence
+- Reusable components (HttpFoundation, Console, Messenger) work outside the full framework
+- Strong typing throughout
+
+### Trade-offs
+
+- Steeper learning curve
+- More ceremony than Laravel
+- Slower initial development velocity
+
+### Symfony Patterns
+
+- **Controllers** are services; inject dependencies via constructor
+- **Form component** for HTML forms; **Validator component** for any validation
+- **Messenger** for commands, queries, async messages
+- **API Platform** for fast typed REST/GraphQL APIs
+- **Doctrine** for the ORM (more explicit than Eloquent, better for complex domains)
+
+### Recommended Companions
+
+- **Pest** or **PHPUnit**
+- **PHPStan** with `phpstan/phpstan-symfony`
+- **PHP-CS-Fixer** with Symfony preset
+- **API Platform** for typed APIs
+
+## Slim
+
+Best for: lightweight APIs, custom architectures, embedded services, projects that need maximum control with minimum framework opinions.
+
+### Strengths
+
+- Tiny, PSR-7/PSR-15 native
+- You assemble the pieces (DI container, ORM, validation) yourself
+- Zero magic
+
+### Trade-offs
+
+- You build everything beyond routing
+- Less ecosystem support than Laravel/Symfony
+
+### When to Pick Slim Over Plain PHP
+
+If you need routing + middleware and want PSR conformance without committing to a full framework.
+
+## No Framework
+
+For very small services (a single endpoint, a CLI tool), plain PHP with carefully chosen libraries is fine:
+
+- Routing: `nikic/fast-route`
+- HTTP: `guzzlehttp/psr7`, `laminas/laminas-diactoros`
+- DI: `php-di/php-di`
+- Validation: `symfony/validator` or `respect/validation`
+- ORM: `doctrine/dbal` (lightweight) or just PDO
+
+## DO NOT
+
+- Pick a framework based on tutorials you've seen recently — pick based on project shape and team experience
+- Mix frameworks (Laravel + Symfony components fight each other's conventions)
+- Build a custom mini-framework when Slim or Symfony covers the use case
+- Skip a framework "because it's just a small project" and reimplement routing, DI, validation, and logging from scratch
+
+## PRIORITY
+
+```
+Right framework for the project shape > Familiar framework
+Thin controllers + handlers > Fat controllers
+Symfony Messenger / Laravel Jobs > Inline synchronous processing
+```
+
+## See Also
+
+- [`architecture.md`](architecture.md) — layered architecture works under any framework
+- [`tooling.md`](tooling.md) — framework-specific tooling (Larastan, Symfony PHPStan)
+- [`anti-patterns.md`](anti-patterns.md) — fat controllers, facade abuse

package/templates/standards/php/rules.md

@@ -0,0 +1,205 @@
+# PHP Rules
+
+## DO
+
+- `declare(strict_types=1);` at the top of every PHP file
+- Type every parameter, return value, and property
+- Use modern PHP 8.3+ features: constructor property promotion, readonly properties/classes, enums, match expressions, attributes, union/intersection types, first-class callable syntax
+- Use value objects for domain concepts (Money, EmailAddress, UserId) — not raw strings/ints
+- Use DTOs for API/queue payloads — readonly classes, no setters
+- Follow PSR-12 formatting (auto-enforced by Pint or PHP-CS-Fixer)
+- Follow PSR-4 autoloading via Composer
+- Use PSR-3 (`LoggerInterface`) for logging — not custom logger classes
+- Name things by responsibility (`CalculateInvoiceTotals`) — not by role (`InvoiceManager`)
+
+## DO NOT
+
+- Use untyped parameters or return values
+- Pass `array` as a data contract — use DTOs or value objects
+- Use generic class names: `Manager`, `Helper`, `Util`, `Common`, `Base`, `Handler` (unless it's actually a PSR-15 handler)
+- Use deep inheritance chains — prefer composition
+- Use traits for hidden cross-cutting behavior — prefer composition
+- Use global state, service locators, static singletons, or facade abuse
+- Reach for magic methods (`__call`, `__get`) when explicit code works
+- Mix HTML and PHP in the same file (use Blade, Twig, or a frontend)
+
+## Strict Types
+
+```php
+<?php declare(strict_types=1);
+
+namespace App\Billing;
+
+final class OrderService
+{
+    public function calculateTotal(Order $order): Money
+    {
+        // ...
+    }
+}
+```
+
+Without `strict_types`, PHP silently coerces types — `int(5)` becomes `string("5")`, `string("abc")` becomes `int(0)`. Strict types make these errors loud at the call site.
+
+## Type Everything
+
+```php
+// BAD — implicit any
+public function process($order)
+{
+    return $order->total;
+}
+
+// GOOD — explicit input and output types
+public function process(Order $order): Money
+{
+    return $order->total;
+}
+```
+
+For collections, use PHPStan/Psalm generics annotations since PHP doesn't have native generics:
+
+```php
+/**
+ * @param list<Order> $orders
+ * @return list<Money>
+ */
+public function extractTotals(array $orders): array
+{
+    return array_map(fn (Order $o) => $o->total, $orders);
+}
+```
+
+## Modern Features in Action
+
+### Constructor Property Promotion
+
+```php
+// GOOD — concise, no boilerplate
+final class OrderService
+{
+    public function __construct(
+        private readonly PaymentGateway $payments,
+        private readonly OrderRepository $orders,
+    ) {}
+}
+
+// BAD — manual property declaration and assignment
+final class OrderService
+{
+    private PaymentGateway $payments;
+    private OrderRepository $orders;
+
+    public function __construct(PaymentGateway $payments, OrderRepository $orders)
+    {
+        $this->payments = $payments;
+        $this->orders = $orders;
+    }
+}
+```
+
+### Readonly Classes (PHP 8.2+)
+
+```php
+final readonly class Money
+{
+    public function __construct(
+        public int $amount,
+        public string $currency,
+    ) {}
+}
+```
+
+All properties are immutable after construction. Add a method that returns a new instance for "mutations":
+
+```php
+public function add(Money $other): Money
+{
+    return new Money($this->amount + $other->amount, $this->currency);
+}
+```
+
+### Enums
+
+```php
+enum InvoiceStatus: string
+{
+    case Draft = 'draft';
+    case Open = 'open';
+    case Paid = 'paid';
+    case Void = 'void';
+}
+
+// Pattern match
+$label = match ($invoice->status) {
+    InvoiceStatus::Draft => 'Draft',
+    InvoiceStatus::Open => 'Awaiting payment',
+    InvoiceStatus::Paid => 'Paid',
+    InvoiceStatus::Void => 'Voided',
+};
+```
+
+### Value Objects Over Primitives
+
+```php
+// BAD — primitive obsession; what's $email's shape? validated?
+public function createUser(string $email, string $name): User
+
+// GOOD — types enforce the contract
+public function createUser(EmailAddress $email, FullName $name): User
+```
+
+Common value objects to introduce early:
+- `EmailAddress`, `PhoneNumber`, `Url`
+- `Money`, `Currency`, `Percentage`
+- `UserId`, `OrderId`, `InvoiceId` (typed IDs prevent passing the wrong one)
+- `DateRange`, `TimeOfDay`
+
+## DTOs
+
+For API requests, queue payloads, and service-to-service messages:
+
+```php
+final readonly class CreateUserDTO
+{
+    public function __construct(
+        public string $name,
+        public EmailAddress $email,
+    ) {}
+
+    public static function fromRequest(Request $request): self
+    {
+        return new self(
+            name: $request->validated('name'),
+            email: new EmailAddress($request->validated('email')),
+        );
+    }
+}
+```
+
+## Naming
+
+| Pattern | Convention | Example |
+|---|---|---|
+| Classes | `PascalCase` | `OrderService`, `EmailAddress` |
+| Methods | `camelCase` | `calculateTotal`, `findActiveSubscribers` |
+| Properties | `camelCase` | `$totalAmount` |
+| Constants | `SCREAMING_SNAKE_CASE` | `MAX_RETRIES` |
+| Interfaces | `PascalCase`, no `I` prefix | `PaymentGateway` not `IPaymentGateway` |
+| Namespaces | match folder structure (PSR-4) | `App\Billing\OrderService` in `src/Billing/OrderService.php` |
+
+## PRIORITY
+
+```
+Strict types > Loose types
+Value objects > Primitive obsession
+DTOs > Arrays as contracts
+Composition > Inheritance
+Explicit > Magic
+```
+
+## See Also
+
+- [`anti-patterns.md`](anti-patterns.md) — what to avoid
+- [`architecture.md`](architecture.md) — where typed code lives
+- [`tooling.md`](tooling.md) — PHPStan, Pint, Rector

package/templates/standards/php/security.md

@@ -0,0 +1,190 @@
+# PHP Security
+
+PHP-specific security non-negotiables. For cross-language concerns (secrets, auth, API security), see also [`../security/`](../security/).
+
+## Passwords
+
+```php
+// Hashing — use password_hash with Argon2id (preferred) or bcrypt
+$hash = password_hash($plaintext, PASSWORD_ARGON2ID);
+
+// Verification — timing-safe
+if (password_verify($plaintext, $user->password_hash)) {
+    // ...
+}
+
+// Rehash if algorithm or cost has been upgraded
+if (password_needs_rehash($user->password_hash, PASSWORD_ARGON2ID)) {
+    $user->password_hash = password_hash($plaintext, PASSWORD_ARGON2ID);
+    $user->save();
+}
+```
+
+Never store plaintext passwords. Never use MD5, SHA-1, or unsalted hashes.
+
+## SQL Injection Prevention
+
+Always use prepared statements. Never concatenate user input into SQL.
+
+```php
+// SAFE — parameterized via PDO
+$stmt = $pdo->prepare("SELECT * FROM users WHERE email = :email");
+$stmt->execute(['email' => $email]);
+
+// SAFE — Eloquent / Doctrine parameterize automatically
+$user = User::where('email', $email)->first();
+
+// DANGEROUS — string concatenation
+$users = $pdo->query("SELECT * FROM users WHERE email = '$email'");
+
+// SAFE — raw queries WITH bindings if you must
+$users = DB::select("SELECT * FROM users WHERE email = ?", [$email]);
+```
+
+## XSS Prevention
+
+Escape all output rendered to HTML. Templating engines do this by default:
+
+```php
+// Blade — auto-escapes
+{{ $user->name }}
+
+// Twig — auto-escapes
+{{ user.name }}
+
+// Manual — escape with htmlspecialchars
+<?= htmlspecialchars($user->name, ENT_QUOTES, 'UTF-8') ?>
+
+// DANGEROUS — raw output
+{!! $user->name !!}        // Blade unescaped
+{{ user.name|raw }}        // Twig unescaped
+<?= $user->name ?>          // manual unescaped
+```
+
+Use `{!!` or `|raw` only for trusted content you control (e.g., rendered markdown that you sanitized yourself).
+
+## CSRF Protection
+
+Web forms must include and validate CSRF tokens.
+
+- **Laravel** — the `web` middleware group includes `VerifyCsrfToken`; templates use `@csrf`
+- **Symfony** — the form component includes CSRF protection by default
+- **Slim / custom** — use a CSRF middleware (`slim/csrf` or similar)
+
+APIs that use session cookies need CSRF protection too. APIs using bearer tokens generally don't (the cross-origin protection comes from CORS + the token header).
+
+## File Upload Validation
+
+```php
+final class UploadInvoicePdfController
+{
+    public function __invoke(Request $request): JsonResponse
+    {
+        $validated = $request->validate([
+            'file' => [
+                'required',
+                'file',
+                'mimes:pdf',
+                'max:5120',         // 5MB
+            ],
+        ]);
+
+        $path = $validated['file']->store('invoices');
+        // ...
+    }
+}
+```
+
+Validate:
+- File size (reject huge uploads early)
+- MIME type (verify the actual content, not just the extension or `Content-Type` header)
+- File extension (whitelist, not blacklist)
+- Image dimensions (for images, to prevent decompression attacks)
+
+Store uploads outside the web root or behind an authenticated handler.
+
+## Path Traversal Prevention
+
+```php
+// BAD — user input flows directly into a file path
+$filename = $_GET['file'];
+return readfile("/uploads/$filename");
+// Attacker: ?file=../../../etc/passwd
+
+// GOOD — validate against an allow-list or sanitize
+$allowed = ['report.pdf', 'invoice.pdf'];
+if (!in_array($filename, $allowed, true)) {
+    abort(404);
+}
+return readfile("/uploads/$filename");
+
+// GOOD — use realpath and verify it stays inside the allowed directory
+$base = realpath('/uploads');
+$path = realpath("/uploads/$filename");
+if ($path === false || !str_starts_with($path, $base)) {
+    abort(404);
+}
+```
+
+## Rate Limiting
+
+Apply rate limits to all public APIs and especially to auth endpoints.
+
+- **Laravel** — `throttle` middleware: `Route::middleware('throttle:60,1')->...`
+- **Symfony** — `RateLimiter` component
+
+```php
+Route::post('/login', LoginController::class)
+    ->middleware('throttle:5,15');  // 5 attempts per 15 minutes
+```
+
+## Secrets
+
+Never commit secrets. Always load from environment:
+
+```php
+// Read at config layer once, not throughout the app
+return [
+    'stripe' => [
+        'secret' => env('STRIPE_SECRET_KEY'),
+    ],
+];
+
+// Access via config()
+$stripeKey = config('services.stripe.secret');
+```
+
+For environment variable validation at startup, see [`../security/secrets.md`](../security/secrets.md).
+
+## Session Security
+
+- Use `HttpOnly`, `Secure`, `SameSite=Lax` (or `Strict`) cookies
+- Regenerate session ID on login (`session_regenerate_id(true)` in raw PHP; framework handles it usually)
+- Set a session timeout
+- Invalidate the session on logout
+
+## DO NOT
+
+- Build SQL strings manually
+- Trust `$_GET` / `$_POST` / `$_REQUEST` / `$_FILES` without validation
+- Use `eval()` or `unserialize()` on user input
+- Store sensitive data in `$_SESSION` without encryption if the session driver writes to disk
+- Log passwords, tokens, or credit card data
+- Use `Content-Type` header alone to determine file type
+- Roll your own crypto or auth — use a battle-tested library
+
+## PRIORITY
+
+```
+Parameterized queries > String SQL
+Argon2id > bcrypt > anything else
+Validated, allow-listed inputs > Defensive sanitization
+HttpOnly cookies > localStorage for auth
+```
+
+## See Also
+
+- [`../security/secrets.md`](../security/secrets.md) — env vars, rotation, scanning
+- [`../security/auth.md`](../security/auth.md) — auth patterns (cross-language)
+- [`../security/api-security.md`](../security/api-security.md) — CORS, error responses, rate limiting
+- [`rules.md`](rules.md) — strict types prevent many injection paths at compile time