start-vibing-stacks 2.1.1 → 2.3.0

package/stacks/php/skills/laravel-octane/SKILL.md

@@ -1,92 +1,170 @@
 # Laravel Octane (RoadRunner) Patterns
 
-## Critical Rules
+## How Octane Works
 
-Octane runs your app in a **long-lived process** — different from traditional PHP.
+Octane runs your app in a **long-lived worker process**. The application boots ONCE and handles many requests without restarting. This is fundamentally different from traditional PHP where each request boots a fresh process.
 
-### ✅ DO
+**Consequence:** Any state stored in static properties, globals, or singletons persists across requests and can leak between users.
 
-```php
-// Dependency Injection over resolve()
-public function __construct(
-    private readonly UserService $userService,
-) {}
+## Critical Rules
 
-// Use Request object
-public function store(Request $request): JsonResponse
+### DO: Dependency Injection
+
+```php
+// CORRECT: Constructor injection (resolved fresh per request scope)
+class OrderController extends Controller
 {
-    $name = $request->input('name');
+    public function __construct(
+        private readonly OrderService $orderService,
+        private readonly CacheManager $cache,
+    ) {}
 }
 
-// Persistent DB connections with flush
-// config/database.php
-'options' => [PDO::ATTR_PERSISTENT => true]
-// Octane::prepare to flush connections between requests
+// CORRECT: Method injection in controller actions
+public function store(StoreOrderRequest $request, PaymentGateway $gateway): JsonResponse
+{
+    $result = $gateway->charge($request->validated());
+    return response()->json($result, 201);
+}
 ```
 
-### ❌ NEVER
+### DO: Use the Request Object
 
 ```php
-// Static state (leaks between requests!)
-class Service {
-    private static array $cache = []; // ❌ LEAKS
+public function store(Request $request): JsonResponse
+{
+    $name = $request->input('name');
+    $token = $request->bearerToken();
+    $ip = $request->ip();
+    $user = $request->user();
 }
-
-// Global variables
-global $user; // ❌
-
-// Modifying config at runtime
-config(['app.name' => 'New']); // ❌ Affects ALL requests
-
-// die() or exit()
-die('error'); // ❌ Kills the worker
-
-// Superglobals
-$_GET['id']; // ❌ Stale between requests
-$_POST['name']; // ❌
-$_SESSION['user']; // ❌
 ```
 
-### AppServiceProvider — Connection Flush
+### DO: Persistent DB Connections with Flush
 
 ```php
-// app/Providers/AppServiceProvider.php
-use Laravel\Octane\Facades\Octane;
-
-public function boot(): void
-{
-    // MANDATORY: flush DB connections between requests
-    Octane::prepare(fn ($sandbox) => $sandbox->flushDatabaseConnections());
-}
+// config/database.php
+'mysql' => [
+    'options' => [
+        PDO::ATTR_PERSISTENT => true,
+    ],
+],
+
+// Octane automatically flushes connections between requests
+// via Octane::prepare() — no manual work needed
 ```
 
-**Rule:** ALWAYS pair persistent connections with `Octane::prepare` flush in AppServiceProvider.
-
-### Memoization in Workers
+### DO: Instance-scoped Memoization
 
 ```php
 // ✅ Scoped to instance, cleared per request
 class ProcessLeadsJob implements ShouldQueue
 {
     private array $lookupCache = [];
-    
+
     public function handle(): void
     {
         foreach ($this->leads as $lead) {
-            $result = $this->lookupCache[$lead->key] 
+            $result = $this->lookupCache[$lead->key]
                 ??= $this->expensiveLookup($lead->key);
         }
-        // Cache is GC'd when job instance is destroyed
+        // Cache is garbage collected when job instance is destroyed
     }
 }
+```
+
+## NEVER Do These in Octane
+
+### No Static State
+
+```php
+// WRONG: Static properties persist across ALL requests
+class AuthService {
+    private static ?User $currentUser = null; // LEAKS between users!
+    private static array $cache = [];          // Grows forever!
+}
 
-// ❌ Static cache (persists across jobs in Octane!)
-private static array $cache = [];
+// CORRECT: Instance properties (scoped to request)
+class AuthService {
+    private ?User $currentUser = null;
+    private array $cache = [];
+}
+```
+
+### No Global Variables
+
+```php
+// WRONG
+global $config;
+$GLOBALS['user'] = $user;
+
+// CORRECT: Use DI or config()
+$value = config('app.name');
+```
+
+### No Runtime Config Mutation
+
+```php
+// WRONG: Affects ALL concurrent requests in the worker
+config(['app.timezone' => 'America/Sao_Paulo']);
+config(['services.stripe.key' => $newKey]);
+
+// CORRECT: Pass values explicitly
+$this->service->processWithTimezone('America/Sao_Paulo');
+```
+
+### No Process Termination
+
+```php
+// WRONG: Kills the entire worker process
+die('Something went wrong');
+exit(1);
+dd($variable);
+
+// CORRECT: Throw exceptions (handled by Laravel)
+throw new RuntimeException('Something went wrong');
+abort(500, 'Internal error');
+
+// For debugging: use dump() without die
+dump($variable); // Outputs without killing worker
+Log::debug('Debug info', ['var' => $variable]);
+```
+
+### No Superglobals
+
+```php
+// WRONG: Stale data from previous requests
+$_GET['id'];
+$_POST['name'];
+$_SESSION['user'];
+$_SERVER['HTTP_AUTHORIZATION'];
+$_COOKIE['token'];
+
+// CORRECT: Use Request object
+$request->input('id');
+$request->post('name');
+$request->session()->get('user');
+$request->header('Authorization');
+$request->cookie('token');
+```
+
+### No Singleton Abuse
+
+```php
+// WRONG: Singleton state leaks
+app()->singleton('cart', fn () => new Cart());
+// The same Cart instance serves ALL users!
+
+// CORRECT: Use scoped bindings
+app()->scoped('cart', fn () => new Cart());
+// Fresh instance per request, cleared between requests
 ```
 
 ## RoadRunner Configuration (rr.yaml)
 
 ```yaml
+version: '3'
+
 server:
   command: "php artisan octane:start --server=roadrunner --host=0.0.0.0 --port=8000"
 
@@ -94,17 +172,41 @@ http:
   address: 0.0.0.0:8000
   pool:
     num_workers: 4
-    max_jobs: 500        # Restart worker after 500 requests (memory safety)
+    max_jobs: 500
     supervisor:
-      max_worker_memory: 128  # MB
+      max_worker_memory: 128
 
 logs:
   level: info
+  encoding: json
 ```
 
+### Worker Tuning
+
+| Setting | Default | Description |
+|---------|---------|-------------|
+| `num_workers` | CPU cores | Number of worker processes |
+| `max_jobs` | 500 | Restart worker after N requests (memory safety) |
+| `max_worker_memory` | 128 MB | Kill worker if exceeds memory |
+
+**Rule:** Always set `max_jobs` to prevent memory leaks from accumulating.
+
 ## Database Safety
 
 - **NEVER** execute `db:wipe`, `migrate:fresh`, `migrate:refresh`, `db:reset`
 - **ALWAYS** use incremental migrations (`make:migration`)
-- If migration fails → fix the file or create a new one
+- If migration fails, fix the file or create a new one
 - Assume **all environments contain critical data**
+
+## Octane Checklist
+
+- [ ] No `static` properties on service classes
+- [ ] No global variables or `$GLOBALS`
+- [ ] No `config()` mutations at runtime
+- [ ] No `die()`, `exit()`, or `dd()` in production code
+- [ ] No superglobals (`$_GET`, `$_POST`, `$_SESSION`, `$_SERVER`)
+- [ ] No `app()->singleton()` for request-scoped data (use `scoped`)
+- [ ] All services use constructor DI (not `app()` or `resolve()`)
+- [ ] Memoization scoped to instance, not static
+- [ ] `max_jobs` configured in `rr.yaml` for memory safety
+- [ ] Persistent DB connections enabled with Octane flush

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

@@ -10,8 +10,8 @@ use Illuminate\Database\Eloquent\Concerns\HasUuids;
 class User extends Model
 {
     use HasUuids;
-    
-    // Auto-generates UUID for 'id' column
+
+    protected $fillable = ['name', 'email'];
 }
 ```
 
@@ -34,10 +34,11 @@ class User extends Model
 ### JSON Column Handling
 
 ```php
-// ✅ Defensive decoding — assume double-encoding possible
+// Defensive decoding — assume double-encoding possible
 protected $casts = [
     'metadata' => 'array',
     'data' => 'array',
+    'status' => OrderStatus::class,  // Enum casting
 ];
 
 // For manual handling:
@@ -46,54 +47,185 @@ $data = is_string($model->data)
     : $model->data;
 ```
 
+### Mass Assignment
+
+```php
+// ALWAYS define $fillable explicitly
+protected $fillable = ['name', 'email', 'status'];
+
+// Use validated data from Form Requests
+$user = User::create($request->validated());
+
+// NEVER use $guarded = [] (allows everything)
+```
+
+## Controller Standards
+
+### Thin Controllers
+
+Controllers should ONLY handle HTTP concerns. Delegate to Services.
+
+#### Inertia Controllers (Frontend pages)
+
+```php
+use Inertia\Inertia;
+use Inertia\Response as InertiaResponse;
+
+class OrderController extends Controller
+{
+    public function __construct(
+        private readonly OrderService $orderService,
+    ) {}
+
+    public function index(Request $request): InertiaResponse
+    {
+        return Inertia::render('Orders/Index', [
+            'orders' => OrderResource::collection(
+                $this->orderService->listForUser($request->user())
+            ),
+        ]);
+    }
+
+    public function store(StoreOrderRequest $request): RedirectResponse
+    {
+        $this->orderService->create($request->validated());
+
+        return redirect()
+            ->route('orders.index')
+            ->with('success', __('orders.created'));
+    }
+}
+```
+
+#### API Controllers (JSON responses)
+
+```php
+class OrderApiController extends Controller
+{
+    public function __construct(
+        private readonly OrderService $orderService,
+    ) {}
+
+    public function store(StoreOrderRequest $request): JsonResponse
+    {
+        $order = $this->orderService->create($request->validated());
+
+        return OrderResource::make($order)
+            ->response()
+            ->setStatusCode(201);
+    }
+
+    public function resetAttempts(Order $order): JsonResponse
+    {
+        $this->orderService->resetAttempts($order);
+
+        return response()->json(['message' => 'Attempts reset']);
+    }
+}
+```
+
+**Rules:**
+- No business logic in controllers
+- Use Form Requests for validation
+- Inertia: return `Inertia::render()` for GET, `redirect()` for POST/PUT/DELETE
+- API: use API Resources for response formatting
+- Use DI for services (constructor injection)
+
+### Form Request Validation
+
+```php
+class StoreOrderRequest extends FormRequest
+{
+    public function authorize(): bool
+    {
+        return $this->user()->can('create', Order::class);
+    }
+
+    public function rules(): array
+    {
+        return [
+            'product_id' => ['required', 'uuid', 'exists:products,id'],
+            'quantity' => ['required', 'integer', 'min:1', 'max:100'],
+            'notes' => ['nullable', 'string', 'max:500'],
+        ];
+    }
+}
+```
+
 ## Service Architecture
 
+### Service Layer Pattern
+
+```php
+class OrderService
+{
+    public function __construct(
+        private readonly PaymentGateway $gateway,
+        private readonly NotificationService $notifications,
+    ) {}
+
+    public function create(array $data): Order
+    {
+        return DB::transaction(function () use ($data) {
+            $order = Order::create($data);
+            $this->gateway->authorize($order);
+            $this->notifications->orderCreated($order);
+
+            return $order;
+        });
+    }
+
+    public function resetAttempts(Order $order): void
+    {
+        $order->update([
+            'status' => OrderStatus::Pending,
+            'attempts' => 0,
+        ]);
+    }
+}
+```
+
 ### Helpers for Complex Services
 
 ```
 App\Services\
-├── UserService.php           # Core service
+├── UserService.php              # Core service
 ├── PaymentService.php
 └── AdPlatforms\
-    ├── AdPlatformService.php  # Main service
+    ├── AdPlatformService.php    # Main service
     └── Helpers\
         ├── GoogleAdsHelper.php  # Extracted logic
         └── MetaAdsHelper.php
 ```
 
-**Rule:** Extract specific logic into `Helpers` sub-namespaces. Avoid bloated service classes.
-
-### Service Naming
-
-- **Convention:** `snake_case` for service container bindings
-- **Class names:** `PascalCase` as standard
+**Rule:** Extract into `Helpers` sub-namespace when service exceeds ~200 lines.
 
 ## API Standards
 
 ### Date Formatting
 
 ```php
-// Trait: FormatsDatesForApi
 trait FormatsDatesForApi
 {
-    protected function formatDateTime($date, Request $request): ?string
-    {
+    protected function formatDateTime(
+        ?Carbon $date,
+        Request $request,
+    ): ?string {
         if (!$date) return null;
-        // DB stores UTC, convert to user timezone in API Resource only
         $tz = $request->header('X-Timezone', 'UTC');
         return $date->setTimezone($tz)->toISOString();
     }
 }
 
-// Usage in API Resource:
 class UserResource extends JsonResource
 {
     use FormatsDatesForApi;
-    
+
     public function toArray(Request $request): array
     {
         return [
             'id' => $this->id,
+            'name' => $this->name,
             'created_at' => $this->formatDateTime($this->created_at, $request),
         ];
     }
@@ -123,57 +255,89 @@ trait FormatsDatesForApi
 ### Action Endpoints
 
 ```php
-// ✅ Dedicated POST endpoints for specific business actions
+// Dedicated POST endpoints for specific business actions
 Route::post('/leads/{lead}/reset-attempts', [LeadController::class, 'resetAttempts']);
 Route::post('/domains/{domain}/refresh-list', [DomainController::class, 'refreshList']);
 
-// ❌ Don't use generic PATCH for specific actions
-Route::patch('/leads/{lead}', ...); // Too generic for business logic
+// DON'T use generic PATCH for business logic
+```
+
+### API Resources (Always Use)
+
+```php
+class LeadResource extends JsonResource
+{
+    public function toArray(Request $request): array
+    {
+        return [
+            'id' => $this->id,
+            'name' => $this->name,
+            'status' => $this->status->value,
+            'domain' => DomainResource::make($this->whenLoaded('domain')),
+            'created_at' => $this->formatDateTime($this->created_at, $request),
+        ];
+    }
+}
 ```
 
-### Job Design
+## Job Design
 
 ```php
-// ✅ Idempotent jobs — safe to retry
 class SendConversionJob implements ShouldQueue
 {
-    public function handle(): void
+    use Dispatchable, InteractsWithQueue, Queueable, SerializesModels;
+
+    public int $tries = 3;
+    public int $backoff = 60;
+
+    public function handle(ConversionGateway $gateway): void
     {
-        // Check status BEFORE processing
+        // Idempotent: check status BEFORE processing
         if ($this->lead->conversion_sent) {
-            return; // Already processed
+            return;
         }
-        
-        // Use unique keys for external APIs
-        $api->sendConversion(
+
+        $gateway->send(
             unique_key: $this->lead->order_id,
-            data: $this->lead->toArray(),
+            data: $this->lead->toConversionArray(),
         );
-        
+
         $this->lead->update(['conversion_sent' => true]);
     }
 }
 ```
 
 **Rules:**
-- Jobs MUST be idempotent
+- Jobs MUST be idempotent (safe to retry)
+- Use unique keys for external API calls
 - Reset jobs: set `status = pending`, reset counters
-- Batch processing for high-volume data (chunks)
+- Batch/chunk for high-volume data
+
+### Batch Processing
+
+```php
+Lead::query()
+    ->where('status', OrderStatus::Pending)
+    ->chunkById(100, function ($leads) {
+        foreach ($leads as $lead) {
+            ProcessLeadJob::dispatch($lead);
+        }
+    });
+```
 
 ## Authorization & Caching
 
 ### User-Scoped Queries
 
 ```php
-// ✅ Always filter by authenticated user
 public function index(Request $request): JsonResponse
 {
     $query = Domain::query();
-    
+
     if (!$request->user()->isAdmin()) {
         $query->where('user_id', $request->user()->id);
     }
-    
+
     return DomainResource::collection($query->paginate());
 }
 ```
@@ -181,13 +345,15 @@ public function index(Request $request): JsonResponse
 ### Redis Caching
 
 ```php
-// User-specific cache keys for data isolation
 $domains = Cache::store('redis')
     ->remember(
         "domains:user:{$userId}",
         now()->addMinutes(15),
         fn () => Domain::where('user_id', $userId)->get()
     );
+
+// Invalidate on write
+Cache::forget("domains:user:{$userId}");
 ```
 
 **Rules:**
@@ -198,12 +364,51 @@ $domains = Cache::store('redis')
 ## Migration Safety
 
 ```bash
-# ✅ Always incremental
+# ALWAYS incremental
 php artisan make:migration add_status_to_leads_table
 
-# ❌ NEVER (destroys data)
+# NEVER (destroys data)
 php artisan migrate:fresh
-php artisan migrate:refresh  
+php artisan migrate:refresh
 php artisan db:wipe
 php artisan db:reset
 ```
+
+## Translations
+
+```php
+// Store in lang/en/*.php and lang/pt/*.php
+// Organize by category within files
+return [
+    'orders' => [
+        'created' => 'Order created successfully',
+        'not_found' => 'Order not found',
+    ],
+    'errors' => [
+        'unauthorized' => 'You are not authorized',
+        'rate_limited' => 'Too many attempts',
+    ],
+];
+```
+
+**Rules:**
+- Centralize all user-facing strings in lang files. No hardcoded strings.
+- Always add to BOTH `lang/en/*.php` and `lang/pt/*.php`
+- Error strings in `lang/*/errors.php`
+
+### Translations with Inertia (On-Demand)
+
+Translations are sent to the frontend per-page via `config/translations_inertia.php`:
+
+```php
+// config/translations_inertia.php
+return [
+    'global' => ['common', 'errors', 'validation'],
+    'pages' => [
+        'dashboard' => ['dashboard'],
+        'orders/*' => ['orders', 'products'],
+    ],
+];
+```
+
+The `InertiaShare` class loads and caches translations per locale + route, merging global files with page-specific files. Frontend accesses them via the `__()` helper (see inertia-react skill).