start-vibing-stacks 2.8.0 → 2.9.0

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

@@ -1,9 +1,23 @@
 ---
 name: laravel-patterns
-version: 1.0.0
+version: 2.0.0
+description: Laravel 12 model/controller/service/job patterns — UUIDs, Loggable
+  trait, mass-assignment, JSON casts, thin Service-driven controllers, idempotent
+  jobs, batch processing. API-first by default (controllers return Resources, NOT
+  `Inertia::render()`). Use for any Laravel domain code. Pairs with
+  `laravel-api-architecture` (the pipeline) and `laravel-octane` (worker safety).
 ---
 
-# Laravel Patterns & Standards
+# Laravel 12 Patterns & Standards
+
+> **Default architecture is API-first.** Controllers return `JsonResponse` /
+> `JsonResource` consumed by a React+Axios SPA. The full pipeline
+> (Route → Controller → FormRequest → Policy → Service → Resource → JSON) lives
+> in `laravel-api-architecture`. This skill covers the building blocks
+> (Models, Services, Jobs, Caching) that compose into that pipeline.
+>
+> **Do NOT add new `Inertia::render()` controllers.** Inertia is supported only
+> for legacy projects (see `inertia-react` skill, marked LEGACY).
 
 ## Model Standards
 
@@ -66,75 +80,65 @@ $user = User::create($request->validated());
 
 ## Controller Standards
 
-### Thin Controllers
-
-Controllers should ONLY handle HTTP concerns. Delegate to Services.
+### Thin API Controllers (default)
 
-#### Inertia Controllers (Frontend pages)
+Controllers ONLY handle HTTP concerns. Delegate to Services. Validation goes
+through FormRequest, authorization through Policy. Full end-to-end example
+lives in `laravel-api-architecture` — this section is the contract.
 
 ```php
-use Inertia\Inertia;
-use Inertia\Response as InertiaResponse;
+namespace App\Http\Controllers\Api;
+
+use App\Http\Controllers\Controller;
+use App\Http\Requests\Order\StoreOrderRequest;
+use App\Http\Resources\OrderResource;
+use App\Models\Order;
+use App\Services\OrderService;
+use Illuminate\Http\JsonResponse;
+use Illuminate\Http\Resources\Json\AnonymousResourceCollection;
 
 class OrderController extends Controller
 {
     public function __construct(
-        private readonly OrderService $orderService,
+        private readonly OrderService $orders,
     ) {}
 
-    public function index(Request $request): InertiaResponse
+    public function index(IndexOrderRequest $request): AnonymousResourceCollection
     {
-        return Inertia::render('Orders/Index', [
-            'orders' => OrderResource::collection(
-                $this->orderService->listForUser($request->user())
-            ),
-        ]);
+        $paginated = $this->orders->listFor($request->user(), $request->validated());
+        return OrderResource::collection($paginated);
     }
 
-    public function store(StoreOrderRequest $request): RedirectResponse
+    public function store(StoreOrderRequest $request): JsonResponse
     {
-        $this->orderService->create($request->validated());
-
-        return redirect()
-            ->route('orders.index')
-            ->with('success', __('orders.created'));
+        $order = $this->orders->create($request->user(), $request->validated());
+        return OrderResource::make($order)->response()->setStatusCode(201);
     }
-}
-```
-
-#### API Controllers (JSON responses)
-
-```php
-class OrderApiController extends Controller
-{
-    public function __construct(
-        private readonly OrderService $orderService,
-    ) {}
 
-    public function store(StoreOrderRequest $request): JsonResponse
+    public function show(Order $order): OrderResource
     {
-        $order = $this->orderService->create($request->validated());
-
-        return OrderResource::make($order)
-            ->response()
-            ->setStatusCode(201);
+        $this->authorize('view', $order);
+        return OrderResource::make($order);
     }
 
-    public function resetAttempts(Order $order): JsonResponse
+    public function resetAttempts(Order $order): OrderResource
     {
-        $this->orderService->resetAttempts($order);
-
-        return response()->json(['message' => 'Attempts reset']);
+        $this->authorize('update', $order);
+        $this->orders->resetAttempts($order);
+        return OrderResource::make($order->fresh());
     }
 }
 ```
 
 **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)
+- No business logic in controllers — delegate to Services.
+- One Service per controller method (composition: a controller may use multiple
+  services overall, but each method calls one entry point).
+- Use FormRequest for validation; use `$this->authorize()` only on routes that
+  rely on RouteModelBinding without a FormRequest.
+- API: always wrap responses in `JsonResource` / `JsonResource::collection`.
+- DI in constructors only — never `app()` / `resolve()` / `new`.
+- Action endpoints get `POST /resource/{id}/action` (NOT generic `PATCH`).
 
 ### Form Request Validation
 
@@ -143,20 +147,63 @@ class StoreOrderRequest extends FormRequest
 {
     public function authorize(): bool
     {
-        return $this->user()->can('create', Order::class);
+        return $this->user()->can('create', Order::class);   // routes to Policy
     }
 
     public function rules(): array
     {
         return [
             'product_id' => ['required', 'uuid', 'exists:products,id'],
-            'quantity' => ['required', 'integer', 'min:1', 'max:100'],
-            'notes' => ['nullable', 'string', 'max:500'],
+            'quantity'   => ['required', 'integer', 'min:1', 'max:100'],
+            'notes'      => ['nullable', 'string', 'max:500'],
         ];
     }
+
+    protected function prepareForValidation(): void
+    {
+        $this->merge(['notes' => $this->notes ? trim($this->notes) : null]);
+    }
 }
 ```
 
+**Rules:**
+- `authorize()` MUST call a Policy via `$user->can(...)`. Returning `true`
+  without policy is allowed ONLY for `index` actions where Service-level
+  user scoping is the gate.
+- `rules()` exhaustive: type, length, allowed enum values, FK existence
+  (`exists:table,id`), file mime/size where applicable.
+- `prepareForValidation()` for input normalization (trim, lowercase email).
+- One FormRequest per Controller action: `StoreOrderRequest`,
+  `UpdateOrderRequest`, `IndexOrderRequest`, etc. — group under
+  `app/Http/Requests/Order/`.
+
+### Policy (mandatory for protected resources)
+
+```php
+namespace App\Policies;
+
+use App\Models\Order;
+use App\Models\User;
+
+class OrderPolicy
+{
+    // Super-admin bypass — return null (NOT false) to fall through
+    public function before(User $user, string $ability): ?bool
+    {
+        return $user->isSuperAdmin() ? true : null;
+    }
+
+    public function viewAny(User $user): bool   { return true; }            // scope in Service
+    public function view(User $user, Order $o): bool { return $user->isAdmin() || $o->user_id === $user->id; }
+    public function create(User $user): bool    { return $user->isAdmin() || $user->isUser(); }
+    public function update(User $user, Order $o): bool { return $user->isAdmin() || $o->user_id === $user->id; }
+    public function delete(User $user, Order $o): bool { return $user->isAdmin(); }
+}
+```
+
+**Rule pattern:** `superadmin` → bypass via `before()`; `admin` → broad access;
+`user` → only own resources (`$model->user_id === $user->id`).
+
 ## Service Architecture
 
 ### Service Layer Pattern
@@ -401,19 +448,34 @@ return [
 - Always add to BOTH `lang/en/*.php` and `lang/pt/*.php`
 - Error strings in `lang/*/errors.php`
 
-### Translations with Inertia (On-Demand)
+### Translations for API-First Frontend (default)
 
-Translations are sent to the frontend per-page via `config/translations_inertia.php`:
+The React SPA owns its own i18n bundle (e.g. `react-intl`, `i18next`). Backend
+exposes translations via a single API endpoint that the frontend caches:
 
 ```php
-// config/translations_inertia.php
-return [
-    'global' => ['common', 'errors', 'validation'],
-    'pages' => [
-        'dashboard' => ['dashboard'],
-        'orders/*' => ['orders', 'products'],
-    ],
-];
+// routes/api.php
+Route::get('/i18n/{locale}', [I18nController::class, 'show'])
+    ->whereIn('locale', ['en', 'pt']);
+
+// app/Http/Controllers/Api/I18nController.php
+public function show(string $locale): JsonResponse
+{
+    return response()
+        ->json(Cache::rememberForever("i18n:{$locale}", function () use ($locale) {
+            $bag = [];
+            foreach (File::files(lang_path($locale)) as $file) {
+                $bag[$file->getFilenameWithoutExtension()] = require $file->getPathname();
+            }
+            return $bag;
+        }))
+        ->setMaxAge(3600);
+}
 ```
 
-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).
+**Rules:**
+- Centralize ALL user-facing strings in `lang/{locale}/*.php` (single source of truth).
+- Frontend pulls them once on boot, caches in memory + `localStorage`.
+- Cache invalidation: bump a version number or clear cache on deploy.
+- For projects already using Inertia, see the **legacy** `inertia-react` and
+  `laravel-inertia-i18n` skills.

package/stacks/php/stack.json

@@ -24,22 +24,26 @@
   "frameworks": [
     {
       "id": "laravel-octane",
-      "name": "Laravel 12 + Octane (RoadRunner) + Inertia.js",
+      "name": "Laravel 12 + Octane (RoadRunner) + Sanctum SPA API",
       "icon": "🚀",
       "detectFiles": ["artisan", "rr.yaml"],
       "default": true,
       "skills": [
         "laravel-patterns",
-        "laravel-octane"
+        "laravel-octane",
+        "laravel-api-architecture",
+        "api-security"
       ]
     },
     {
       "id": "laravel",
-      "name": "Laravel 12 (standard)",
+      "name": "Laravel 12 (standard) + Sanctum SPA API",
       "icon": "🏗️",
       "detectFiles": ["artisan", "bootstrap/app.php"],
       "skills": [
-        "laravel-patterns"
+        "laravel-patterns",
+        "laravel-api-architecture",
+        "api-security"
       ]
     }
   ],
@@ -50,10 +54,17 @@
   ],
   "frontendOptions": [
     {
-      "id": "react-inertia",
-      "name": "ReactJS 19 + Inertia.js + TailwindCSS 4",
+      "id": "react-api",
+      "name": "ReactJS 19 + Vite + Axios (Sanctum SPA API)",
       "icon": "⚛️",
       "default": true,
+      "frameworks": ["laravel", "laravel-octane"],
+      "baseSkillsDir": "react"
+    },
+    {
+      "id": "react-inertia",
+      "name": "ReactJS 19 + Inertia.js (LEGACY)",
+      "icon": "🪦",
       "frameworks": ["laravel", "laravel-octane"]
     },
     {
@@ -84,6 +95,8 @@
     "composer-workflow",
     "security-scan-php",
     "api-design",
+    "api-security",
+    "laravel-api-architecture",
     "openapi-design"
   ],
   "requirements": [