start-vibing-stacks 2.1.1 → 2.3.0

package/stacks/php/skills/php-patterns/SKILL.md

@@ -1,8 +1,8 @@
-# PHP 8.3+ Patterns
+# PHP 8.3+ Patterns for Laravel
 
 ## Version Requirements
 
-- **PHP >= 8.3** — MANDATORY. Do not use deprecated patterns.
+- **PHP >= 8.3** — MANDATORY. Use all modern features.
 - **Composer >= 2.0** — For dependency management.
 - Use strict types: `declare(strict_types=1);` in EVERY file.
 
@@ -11,32 +11,48 @@
 ### Typed Properties & Constructor Promotion
 
 ```php
-class User {
+class CreateUserDTO {
     public function __construct(
-        private readonly string $name,
-        private readonly string $email,
-        private readonly int $age,
+        public readonly string $name,
+        public readonly string $email,
+        public readonly int $age,
     ) {}
 }
 ```
 
-### Enums
+### Enums (Use for Status, Types, Roles)
 
 ```php
-enum Status: string {
-    case Active = 'active';
-    case Inactive = 'inactive';
-    case Suspended = 'suspended';
+enum OrderStatus: string {
+    case Pending = 'pending';
+    case Processing = 'processing';
+    case Completed = 'completed';
+    case Cancelled = 'cancelled';
+
+    public function label(): string {
+        return match($this) {
+            self::Pending => 'Awaiting Processing',
+            self::Processing => 'In Progress',
+            self::Completed => 'Done',
+            self::Cancelled => 'Cancelled',
+        };
+    }
 }
+
+// In Eloquent model:
+protected $casts = [
+    'status' => OrderStatus::class,
+];
 ```
 
-### Readonly Classes (8.2+)
+### Readonly Classes for DTOs
 
 ```php
-readonly class UserDTO {
+readonly class PaymentResult {
     public function __construct(
-        public string $name,
-        public string $email,
+        public string $transactionId,
+        public float $amount,
+        public bool $success,
     ) {}
 }
 ```
@@ -44,45 +60,103 @@ readonly class UserDTO {
 ### Typed Class Constants (8.3+)
 
 ```php
-class Config {
-    public const string APP_NAME = 'MyApp';
-    public const int MAX_RETRIES = 3;
+class RateLimiter {
+    public const int MAX_ATTEMPTS = 5;
+    public const int DECAY_SECONDS = 60;
+    public const string CACHE_PREFIX = 'rate_limit';
 }
 ```
 
-### Match Expression
+### Match Expression (Prefer over switch)
 
 ```php
-$result = match($status) {
-    'active' => handleActive(),
-    'inactive' => handleInactive(),
-    default => throw new \InvalidArgumentException("Unknown status: {$status}"),
+$result = match($request->input('action')) {
+    'approve' => $service->approve($record),
+    'reject' => $service->reject($record),
+    'escalate' => $service->escalate($record),
+    default => throw new \InvalidArgumentException("Unknown action"),
 };
 ```
 
 ### Named Arguments
 
 ```php
-$response = new Response(
-    content: $html,
+$response = Response::json(
+    data: $collection,
     status: 200,
-    headers: ['Content-Type' => 'text/html'],
+    headers: ['X-Total-Count' => $total],
 );
 ```
 
 ### Null-safe Operator
 
 ```php
-$country = $user?->address?->country?->name;
+$country = $user?->address?->country?->name ?? 'Unknown';
+```
+
+### First-class Callable Syntax
+
+```php
+$filtered = $collection->filter($this->isEligible(...));
+```
+
+## Clean Code Patterns
+
+### Dependency Injection (Octane-safe)
+
+```php
+// CORRECT: Constructor injection
+class OrderService {
+    public function __construct(
+        private readonly PaymentGateway $gateway,
+        private readonly OrderRepository $orders,
+        private readonly LoggerInterface $logger,
+    ) {}
+}
+
+// WRONG: Service locator
+class OrderService {
+    public function process(): void {
+        $gateway = app(PaymentGateway::class); // Avoid in Octane
+    }
+}
 ```
 
-### Fibers (8.1+)
+### Service Architecture
+
+```
+App\Services\
+├── UserService.php              # Core user operations
+├── PaymentService.php           # Payment processing
+└── AdPlatforms\
+    ├── AdPlatformService.php    # Main service
+    └── Helpers\
+        ├── GoogleAdsHelper.php  # Extracted complex logic
+        └── MetaAdsHelper.php
+```
+
+**Rule:** When a service class exceeds ~200 lines, extract specific logic into `Helpers` sub-namespace.
+
+### Return Types & Exceptions
 
 ```php
-$fiber = new Fiber(function (): void {
-    $value = Fiber::suspend('fiber started');
-    echo "Resumed with: {$value}";
-});
+public function findOrFail(string $id): User
+{
+    return User::findOrFail($id);
+}
+
+public function process(Order $order): PaymentResult
+{
+    try {
+        return $this->gateway->charge($order);
+    } catch (GatewayException $e) {
+        $this->logger->error('Payment failed', [
+            'order_id' => $order->id,
+            'error' => $e->getMessage(),
+        ]);
+        throw new PaymentFailedException($order, $e);
+    }
+}
 ```
 
 ## FORBIDDEN Patterns
@@ -92,28 +166,14 @@ $fiber = new Fiber(function (): void {
 | `$var = isset($x) ? $x : $default` | `$var = $x ?? $default` |
 | `function foo($x)` (no types) | `function foo(string $x): void` |
 | `array()` | `[]` |
-| `mysql_*` functions | PDO or Doctrine |
-| Global variables | Dependency injection |
-| `eval()` | Never use eval |
 | Untyped properties | Always type properties |
-
-## Error Handling
-
-```php
-try {
-    $result = riskyOperation();
-} catch (SpecificException $e) {
-    logger()->error('Operation failed', [
-        'error' => $e->getMessage(),
-        'trace' => $e->getTraceAsString(),
-    ]);
-    throw new DomainException('Friendly message', 0, $e);
-}
-```
+| `static` properties on services | Instance properties (Octane-safe) |
+| Global variables | Dependency injection |
+| `switch` with simple mapping | `match` expression |
+| Large service classes (200+ lines) | Extract into Helpers |
+| `mixed` type without justification | Use specific types or union types |
 
 ## PSR Standards
 
-- **PSR-4**: Autoloading
-- **PSR-7**: HTTP Messages (if not using framework)
-- **PSR-12**: Coding Style
-- **PSR-15**: HTTP Handlers
+- **PSR-4**: Autoloading (Laravel default)
+- **PSR-12**: Coding Style (enforced by PHP-CS-Fixer)

package/stacks/php/skills/security-scan-php/SKILL.md

@@ -1,80 +1,198 @@
-# PHP Security Scan
+# Laravel Security Scan
 
-## OWASP Top 10 for PHP
+## OWASP Top 10 for Laravel
 
 ### A01 - Broken Access Control
 
 ```php
-// ❌ NEVER trust user input for authorization
-$userId = $_GET['user_id'];
+// WRONG: Trust user input for authorization
+$userId = $request->input('user_id');
 $user = User::find($userId);
 
-// ✅ Use authenticated session
-$user = Auth::user();
+// CORRECT: Use authenticated session
+$user = $request->user();
+
+// CORRECT: Scope queries by authenticated user
+$query = Resource::query();
+if (!$request->user()->isAdmin()) {
+    $query->where('user_id', $request->user()->id);
+}
 ```
 
+**Rules:**
+- NEVER return unscoped queries — always filter by authenticated user
+- Use Policies for authorization logic
+- Use Form Requests with `authorize()` method
+- Use Route Model Binding with scoping
+
 ### A02 - Cryptographic Failures
 
 ```php
-// ❌ NEVER
+// WRONG
 md5($password);
 sha1($password);
 
-// ✅ ALWAYS
-password_hash($password, PASSWORD_BCRYPT, ['cost' => 12]);
-password_verify($input, $hash);
+// CORRECT (Laravel handles this via Hash facade)
+Hash::make($password);
+Hash::check($input, $hashedPassword);
+
+// For API tokens: use Laravel Sanctum
+// Table: users_access_tokens (UUIDs + Soft Deletes)
+// All token actions logged via Loggable trait
 ```
 
 ### A03 - Injection
 
 ```php
-// ❌ SQL Injection
-$db->query("SELECT * FROM users WHERE id = {$_GET['id']}");
+// WRONG: SQL Injection via DB::raw
+$users = DB::select("SELECT * FROM users WHERE id = {$id}");
+DB::raw("WHERE name = '{$name}'");
 
-// ✅ Prepared statements (PDO)
-$stmt = $db->prepare("SELECT * FROM users WHERE id = :id");
-$stmt->execute([':id' => $id]);
+// CORRECT: Eloquent (preferred)
+$user = User::findOrFail($id);
 
-// ✅ Prepared statements (MySQLi)
-$stmt = $db->prepare("SELECT * FROM users WHERE id = ?");
-$stmt->bind_param('i', $id);
-$stmt->execute();
+// CORRECT: Query Builder with bindings
+$users = DB::table('users')->where('name', $name)->get();
+
+// CORRECT: Raw with parameter binding (last resort)
+$results = DB::select('SELECT * FROM users WHERE id = ?', [$id]);
 ```
 
 ### A07 - XSS Prevention
 
 ```php
-// ❌ Raw output
-echo $userInput;
+// WRONG: Unescaped output in Blade
+{!! $userInput !!}
 
-// ✅ Always escape
-echo htmlspecialchars($userInput, ENT_QUOTES, 'UTF-8');
+// CORRECT: Auto-escaped (Blade default)
+{{ $userInput }}
 
-// ✅ In templates (Blade)
-{{ $userInput }}  // Auto-escaped
-{!! $trustedHtml !!}  // Only for trusted content
+// Only use {!! !!} for TRUSTED, pre-sanitized HTML
+{!! $trustedHtmlFromCMS !!}
 ```
 
-## Security Checklist
+### A08 - Insecure Deserialization
+
+```php
+// WRONG: Unserialize user data
+$data = unserialize($request->input('data'));
+
+// CORRECT: Use JSON with Model casts
+protected $casts = [
+    'metadata' => 'array',
+    'settings' => 'array',
+];
+
+// CORRECT: Defensive JSON handling
+$data = is_string($model->data) 
+    ? json_decode($model->data, true) 
+    : $model->data;
+```
+
+## Laravel-Specific Security
+
+### Mass Assignment Protection
+
+```php
+// WRONG: No protection
+$user = User::create($request->all());
+
+// CORRECT: Define $fillable
+class User extends Model {
+    protected $fillable = ['name', 'email'];
+}
+
+// CORRECT: Use Form Request validated data
+$user = User::create($request->validated());
+```
+
+### Environment Variables
+
+```php
+// WRONG: env() outside config files (null when cached)
+$apiKey = env('API_KEY');
 
-- [ ] All SQL uses prepared statements
-- [ ] All output is escaped (htmlspecialchars)
-- [ ] CSRF tokens on all forms
-- [ ] Passwords use password_hash/verify
-- [ ] File uploads validated (type, size, extension)
-- [ ] Sessions use httpOnly + secure cookies
-- [ ] Input validated before processing
-- [ ] No `eval()`, `exec()` with user input
-- [ ] No `extract()` on user data
-- [ ] Headers: X-Content-Type-Options, X-Frame-Options, CSP
+// CORRECT: Use config files
+// config/services.php
+'stripe' => ['key' => env('STRIPE_KEY')],
+
+// In code:
+$apiKey = config('services.stripe.key');
+```
+
+### CSRF & Authentication
+
+```php
+// Blade forms — CSRF automatic
+<form method="POST">
+    @csrf
+    ...
+</form>
+
+// API routes — use Sanctum middleware
+Route::middleware('auth:sanctum')->group(function () {
+    Route::apiResource('users', UserController::class);
+});
+```
+
+### File Upload Validation
+
+```php
+public function rules(): array
+{
+    return [
+        'avatar' => [
+            'required',
+            'image',
+            'mimes:jpg,jpeg,png,webp',
+            'max:2048', // 2MB
+            'dimensions:max_width=2000,max_height=2000',
+        ],
+    ];
+}
+```
+
+## Octane Security Considerations
+
+```php
+// WRONG: Static state leaks user data between requests
+class AuthService {
+    private static ?User $currentUser = null; // LEAKS!
+}
+
+// WRONG: Superglobals are stale in Octane
+$token = $_SERVER['HTTP_AUTHORIZATION'];
+
+// CORRECT: Use Request object
+$token = $request->bearerToken();
+$user = $request->user();
+```
+
+## Security Checklist
 
-## Sensitive Data Patterns (FORBIDDEN)
+- [ ] All queries use Eloquent or Query Builder (no raw SQL with user input)
+- [ ] All Blade output uses `{{ }}` (auto-escaped)
+- [ ] CSRF protection on all forms (`@csrf`)
+- [ ] Passwords use `Hash::make()` / `Hash::check()`
+- [ ] File uploads validated (type, size, dimensions)
+- [ ] API routes protected with Sanctum middleware
+- [ ] Models define `$fillable` (no `$guarded = []`)
+- [ ] Queries scoped by authenticated user (unless admin)
+- [ ] No `env()` calls outside config files
+- [ ] No static state in services (Octane-safe)
+- [ ] No superglobals (`$_GET`, `$_POST`, `$_SESSION`)
+- [ ] Sensitive headers set (X-Content-Type-Options, X-Frame-Options, CSP)
+- [ ] Rate limiting on authentication endpoints
+
+## Sensitive Patterns (FORBIDDEN)
 
 | Pattern | Risk |
 |---------|------|
-| `$_GET` used directly in SQL | SQL Injection |
-| `echo $_POST[...]` | XSS |
+| `DB::raw()` with user input | SQL Injection |
+| `{!! $userInput !!}` | XSS |
 | `md5()` / `sha1()` for passwords | Weak hashing |
-| `eval($userInput)` | RCE |
-| `include $_GET['page']` | LFI/RFI |
-| `serialize()` user data | Object injection |
+| Dynamic code execution | RCE |
+| `unserialize()` on user data | Object injection |
+| `$request->all()` without `$fillable` | Mass assignment |
+| `env()` in runtime code | Null after config cache |
+| Static user state in services | Data leaks in Octane |

package/stacks/php/stack.json

@@ -27,13 +27,20 @@
       "name": "Laravel 12 + Octane (RoadRunner) + Inertia.js",
       "icon": "🚀",
       "detectFiles": ["artisan", "rr.yaml"],
-      "default": true
+      "default": true,
+      "skills": [
+        "laravel-patterns",
+        "laravel-octane"
+      ]
     },
     {
       "id": "laravel",
       "name": "Laravel 12 (standard)",
       "icon": "🏗️",
-      "detectFiles": ["artisan", "bootstrap/app.php"]
+      "detectFiles": ["artisan", "bootstrap/app.php"],
+      "skills": [
+        "laravel-patterns"
+      ]
     }
   ],
   "databases": [
@@ -46,12 +53,20 @@
       "id": "react-inertia",
       "name": "ReactJS 19 + Inertia.js + TailwindCSS 4",
       "icon": "⚛️",
-      "default": true
+      "default": true,
+      "frameworks": ["laravel", "laravel-octane"]
     },
     {
       "id": "blade",
       "name": "Blade + TailwindCSS 4",
-      "icon": "🖼️"
+      "icon": "🖼️",
+      "frameworks": ["laravel", "laravel-octane"]
+    },
+    {
+      "id": "livewire",
+      "name": "Livewire + Alpine.js",
+      "icon": "⚡",
+      "frameworks": ["laravel", "laravel-octane"]
     },
     {
       "id": "none",
@@ -68,8 +83,6 @@
     "phpstan-analysis",
     "composer-workflow",
     "security-scan-php",
-    "laravel-patterns",
-    "laravel-octane",
     "api-design"
   ],
   "requirements": [