@sun-asterisk/sunlint 1.3.47 → 1.3.49

package/skill-assets/sunlint-code-quality/rules/php-laravel/LV001-form-request-validation.md

@@ -0,0 +1,64 @@
+---
+title: Use Form Request Classes for Validation
+impact: HIGH
+impactDescription: keeps controllers thin, centralizes validation logic and authorization, enables reuse
+tags: validation, form-request, controller, laravel, clean-architecture
+---
+
+## Use Form Request Classes for Validation
+
+Putting `$request->validate()` directly in controller actions mixes concerns, prevents reuse, and inflates controllers. Form Requests encapsulate validation + authorization as a dedicated class.
+
+**Wrong:**
+
+```php
+// Controller bloated with validation logic
+public function store(Request $request)
+{
+    $request->validate([
+        'name'  => 'required|string|max:255',
+        'email' => 'required|email|unique:users',
+        'age'   => 'required|integer|min:18',
+    ]);
+
+    User::create($request->all());
+}
+```
+
+**Correct:**
+
+```bash
+# Generate a Form Request
+php artisan make:request StoreUserRequest
+```
+
+```php
+// app/Http/Requests/StoreUserRequest.php
+class StoreUserRequest extends FormRequest
+{
+    public function authorize(): bool
+    {
+        return $this->user()->can('create', User::class);
+    }
+
+    public function rules(): array
+    {
+        return [
+            'name'  => 'required|string|max:255',
+            'email' => 'required|email|unique:users',
+            'age'   => 'required|integer|min:18',
+        ];
+    }
+}
+
+// Controller is now thin
+public function store(StoreUserRequest $request)
+{
+    User::create($request->validated()); // never $request->all()
+}
+```
+
+**Key points:**
+- Always use `$request->validated()` not `$request->all()` — only returns fields that passed validation
+- Authorization logic belongs in `authorize()`, not the controller
+- One Form Request per action (StoreUserRequest, UpdateUserRequest are separate)

package/skill-assets/sunlint-code-quality/rules/php-laravel/LV002-eager-load-no-n-plus-1.md

@@ -0,0 +1,58 @@
+---
+title: Eager Load Relationships to Prevent N+1 Queries
+impact: CRITICAL
+impactDescription: prevents N+1 query explosion that causes severe performance degradation in production
+tags: n+1, eager-loading, eloquent, performance, with, laravel
+---
+
+## Eager Load Relationships to Prevent N+1 Queries
+
+Accessing a relationship inside a loop without eager loading fires one query per iteration. With 1000 posts, that is 1001 queries. Always eager load with `with()` when you know you'll access the relationship.
+
+**Wrong:**
+
+```php
+// Executes 1 + N queries (one per post)
+$posts = Post::all();
+
+foreach ($posts as $post) {
+    echo $post->author->name;   // <- SELECT * FROM users WHERE id = ? (×N)
+    echo $post->category->name; // <- SELECT * FROM categories WHERE id = ? (×N)
+}
+```
+
+**Correct:**
+
+```php
+// Executes exactly 3 queries total
+$posts = Post::with(['author', 'category'])->get();
+
+foreach ($posts as $post) {
+    echo $post->author->name;
+    echo $post->category->name;
+}
+
+// Nested relationships
+$posts = Post::with(['author.profile', 'tags'])->get();
+
+// Selective columns to reduce memory
+$posts = Post::with(['author:id,name,avatar'])->get();
+
+// Conditional eager loading
+$posts = Post::with(['comments' => function ($q) {
+    $q->where('approved', true)->latest()->limit(5);
+}])->get();
+```
+
+**Detection signal:**
+- Any `->relationship` access inside a `foreach`, `map`, `each`, or `Collection` method without preceding `with()`
+- Use Laravel Telescope or Debugbar in development to detect N+1 — queries > 10 for a single request is a red flag
+
+**Also applies to:**
+```php
+// WRONG: counting without withCount
+$posts->each(fn($p) => $p->comments->count()); // N queries
+
+// CORRECT: withCount
+Post::withCount('comments')->get(); // 1 query
+```

package/skill-assets/sunlint-code-quality/rules/php-laravel/LV003-config-not-env.md

@@ -0,0 +1,54 @@
+---
+title: Use config() Helper, Never env() Outside Config Files
+impact: HIGH
+impactDescription: config caching (php artisan config:cache) breaks env() calls at runtime — app silently returns null
+tags: config, env, caching, laravel, environment
+---
+
+## Use config() Instead of env() Outside Config Files
+
+`env()` only works reliably before config is cached. Once you run `php artisan config:cache` (required in production), `env()` returns `null` everywhere except in `config/*.php` files.
+
+**Wrong:**
+
+```php
+// Service class — breaks after config:cache
+class PaymentService
+{
+    public function charge()
+    {
+        $key = env('STRIPE_SECRET'); // NULL in production!
+    }
+}
+
+// Controller
+public function show()
+{
+    $debug = env('APP_DEBUG'); // NULL after config:cache
+}
+```
+
+**Correct:**
+
+```php
+// 1. Define in config/services.php
+return [
+    'stripe' => [
+        'secret' => env('STRIPE_SECRET'),  // env() ONLY here
+    ],
+];
+
+// 2. Use config() everywhere else
+class PaymentService
+{
+    public function charge()
+    {
+        $key = config('services.stripe.secret'); // always works
+    }
+}
+
+// 3. With default fallback
+$debug = config('app.debug', false);
+```
+
+**Rule:** `env()` appears only in `config/` directory. Everywhere else → `config()`.

package/skill-assets/sunlint-code-quality/rules/php-laravel/LV004-fillable-mass-assignment.md

@@ -0,0 +1,51 @@
+---
+title: Define $fillable — Never Use $guarded = []
+impact: CRITICAL
+impactDescription: disabling mass assignment protection allows attackers to write arbitrary model fields via crafted HTTP requests
+tags: mass-assignment, fillable, guarded, security, eloquent, laravel
+---
+
+## Define $fillable — Never Use $guarded = []
+
+Mass assignment attacks occur when a user passes unexpected fields (e.g. `is_admin=1`) that get written to the database. `$guarded = []` disables all protection.
+
+**Wrong:**
+
+```php
+class User extends Model
+{
+    protected $guarded = []; // All fields writable — DANGEROUS
+
+    // Or: no $fillable defined at all (same effect with $guarded=[])
+}
+
+// Attacker sends: POST /users { "name": "Bob", "is_admin": 1 }
+User::create($request->all()); // is_admin gets written!
+```
+
+**Correct:**
+
+```php
+class User extends Model
+{
+    // Explicit allowlist
+    protected $fillable = [
+        'name',
+        'email',
+        'password',
+    ];
+
+    // Fields like is_admin, email_verified_at are NOT here
+    // They are set explicitly:
+}
+
+// Controller
+User::create($request->validated()); // only validated+fillable fields written
+
+// When you must set a guarded field, use direct assignment:
+$user = new User($request->validated());
+$user->is_admin = false; // explicit, intentional
+$user->save();
+```
+
+**Also:** use `$request->validated()` not `$request->all()` so only schema-declared fields reach the model.

package/skill-assets/sunlint-code-quality/rules/php-laravel/LV005-policies-gates-authorization.md

@@ -0,0 +1,71 @@
+---
+title: Use Policies and Gates for Authorization
+impact: HIGH
+impactDescription: centralizes authorization logic, prevents scattered role checks, enables testing and auditing
+tags: authorization, policy, gate, roles, security, laravel
+---
+
+## Use Policies and Gates for Authorization
+
+Manual role checks scattered across controllers (`if ($user->role === 'admin')`) are fragile, hard to audit, and often inconsistently applied.
+
+**Wrong:**
+
+```php
+// Controller — authorization logic throughout
+public function update(Request $request, Post $post)
+{
+    if ($request->user()->id !== $post->user_id) {
+        abort(403);
+    }
+    if ($request->user()->role !== 'editor' && $request->user()->role !== 'admin') {
+        abort(403); // duplicated in show, destroy, etc.
+    }
+    $post->update($request->validated());
+}
+```
+
+**Correct:**
+
+```bash
+php artisan make:policy PostPolicy --model=Post
+```
+
+```php
+// app/Policies/PostPolicy.php
+class PostPolicy
+{
+    public function update(User $user, Post $post): bool
+    {
+        return $user->id === $post->user_id || $user->isEditor();
+    }
+
+    public function delete(User $user, Post $post): bool
+    {
+        return $user->id === $post->user_id || $user->isAdmin();
+    }
+}
+
+// Controller — thin and readable
+public function update(UpdatePostRequest $request, Post $post)
+{
+    $this->authorize('update', $post); // throws 403 if denied
+
+    $post->update($request->validated());
+}
+
+// Or in Form Request
+public function authorize(): bool
+{
+    return $this->user()->can('update', $this->route('post'));
+}
+```
+
+**Gates for non-model actions:**
+```php
+// AppServiceProvider
+Gate::define('access-reports', fn(User $u) => $u->hasRole('analyst'));
+
+// Anywhere
+if (Gate::denies('access-reports')) abort(403);
+```

package/skill-assets/sunlint-code-quality/rules/php-laravel/LV006-queue-heavy-tasks.md

@@ -0,0 +1,68 @@
+---
+title: Queue Heavy Tasks — Never Block the Request Cycle
+impact: HIGH
+impactDescription: synchronous email/external API calls cause request timeouts and degrade user experience under load
+tags: queues, jobs, email, performance, background, laravel
+---
+
+## Queue Heavy Tasks — Never Block the Request Cycle
+
+Any task over ~200ms (sending email, calling external APIs, generating reports, processing images) must be dispatched to a queue, not executed synchronously in the HTTP request.
+
+**Wrong:**
+
+```php
+// Request handler blocked for seconds
+public function register(StoreUserRequest $request)
+{
+    $user = User::create($request->validated());
+
+    // Blocks for 1-3 seconds — user waits, timeout risk
+    Mail::to($user)->send(new WelcomeEmail($user));
+
+    // Calls Slack API — blocks if Slack is slow
+    Http::post(config('services.slack.webhook'), ['text' => "New user: {$user->email}"]);
+
+    return response()->json($user, 201);
+}
+```
+
+**Correct:**
+
+```bash
+php artisan make:job SendWelcomeEmail
+php artisan make:job NotifySlackNewUser
+```
+
+```php
+public function register(StoreUserRequest $request)
+{
+    $user = User::create($request->validated());
+
+    // Dispatch to queue — returns immediately
+    SendWelcomeEmail::dispatch($user)->onQueue('emails');
+    NotifySlackNewUser::dispatch($user)->onQueue('notifications');
+
+    return response()->json($user, 201); // responds in <50ms
+}
+
+// Job class
+class SendWelcomeEmail implements ShouldQueue
+{
+    use Queueable, Dispatchable, InteractsWithQueue, SerializesModels;
+
+    public function __construct(private User $user) {}
+
+    public function handle(): void
+    {
+        Mail::to($this->user)->send(new WelcomeEmail($this->user));
+    }
+
+    public function failed(Throwable $e): void
+    {
+        Log::error('WelcomeEmail failed', ['user' => $this->user->id, 'error' => $e->getMessage()]);
+    }
+}
+```
+
+**Queue-worthy operations:** email, SMS, push notifications, Slack/webhook, PDF generation, image resize, CSV export, expensive calculations, third-party API calls.

package/skill-assets/sunlint-code-quality/rules/php-laravel/LV007-hash-passwords.md

@@ -0,0 +1,51 @@
+---
+title: Use Hash::make() for Passwords — Never md5/sha1/bcrypt()
+impact: CRITICAL
+impactDescription: MD5/SHA1 are broken for passwords; Laravel's Hash facade uses bcrypt/argon2 with proper salting automatically
+tags: password, hashing, bcrypt, security, hash, laravel
+---
+
+## Use Hash::make() for Passwords
+
+Laravel's `Hash` facade automatically uses the configured driver (bcrypt by default, upgradeable to argon2id). Never use PHP's raw `password_hash()` directly without going through Laravel's config, and never use `md5()` or `sha1()`.
+
+**Wrong:**
+
+```php
+// md5/sha1 — broken, no salting, rainbow-table vulnerable
+$user->password = md5($request->password);
+$user->password = sha1($request->password);
+
+// Raw PHP without config — bypasses algorithm config
+$user->password = password_hash($request->password, PASSWORD_BCRYPT);
+```
+
+**Correct:**
+
+```php
+// Creating a user
+$user = User::create([
+    'name'     => $request->name,
+    'email'    => $request->email,
+    'password' => Hash::make($request->password), // salted + bcrypt/argon2
+]);
+
+// Verifying on login — NEVER compare raw strings
+if (!Hash::check($request->password, $user->password)) {
+    throw ValidationException::withMessages([
+        'email' => ['These credentials do not match our records.'],
+    ]);
+}
+
+// Rehash on login if algorithm changed
+if (Hash::needsRehash($user->password)) {
+    $user->update(['password' => Hash::make($request->password)]);
+}
+```
+
+**Config:** Change algorithm in `config/hashing.php`:
+```php
+'driver' => 'argon2id', // upgrade from default bcrypt for new projects
+```
+
+**In migrations:** password column must be `string(255)`, not `string(32)` — bcrypt hashes are 60 chars, argon2id up to 95.

package/skill-assets/sunlint-code-quality/rules/php-laravel/LV008-route-model-binding.md

@@ -0,0 +1,67 @@
+---
+title: Use Route Model Binding — No Manual find() in Controllers
+impact: MEDIUM
+impactDescription: eliminates repetitive find-or-404 boilerplate, centralizes authorization scope
+tags: route-model-binding, controller, eloquent, laravel, routing
+---
+
+## Use Route Model Binding
+
+Laravel resolves model instances automatically from route parameters. Writing `User::findOrFail($id)` manually in every controller method is redundant boilerplate.
+
+**Wrong:**
+
+```php
+// routes/api.php
+Route::get('/posts/{id}', [PostController::class, 'show']);
+
+// Controller
+public function show(int $id)
+{
+    $post = Post::findOrFail($id); // unnecessary boilerplate
+    $this->authorize('view', $post);
+    return PostResource::make($post);
+}
+```
+
+**Correct:**
+
+```php
+// routes/api.php — use the model name as parameter
+Route::get('/posts/{post}', [PostController::class, 'show']);
+
+// Controller — Laravel resolves Post automatically, throws 404 if not found
+public function show(Post $post)
+{
+    $this->authorize('view', $post);
+    return PostResource::make($post);
+}
+```
+
+**Custom binding key** (e.g. slug instead of id):
+
+```php
+// Model
+class Post extends Model
+{
+    public function getRouteKeyName(): string
+    {
+        return 'slug'; // /posts/my-post-slug
+    }
+}
+```
+
+**Scoped binding** (child must belong to parent):
+
+```php
+// /users/{user}/posts/{post} — post must belong to user
+Route::get('/users/{user}/posts/{post}', [PostController::class, 'show'])
+    ->scopeBindings();
+```
+
+**With eager loading:**
+
+```php
+// Customize resolution for eager-loading
+Route::bind('post', fn($value) => Post::with(['author', 'tags'])->findOrFail($value));
+```

package/skill-assets/sunlint-code-quality/rules/php-laravel/LV009-api-resources.md

@@ -0,0 +1,72 @@
+---
+title: Use API Resources for Response Transformation
+impact: HIGH
+impactDescription: prevents over-exposure of model fields, decouples DB schema from API contract, enables versioning
+tags: api-resources, response, transformation, security, laravel
+---
+
+## Use API Resources for Response Transformation
+
+Returning `$model->toArray()` or `response()->json($model)` exposes all model attributes including sensitive fields (`password`, `remember_token`, internal flags). API Resources control exactly what is serialized.
+
+**Wrong:**
+
+```php
+// Exposes ALL columns including password, remember_token, internal flags
+return response()->json($user);
+return response()->json(User::all());
+return response()->json($user->toArray());
+```
+
+**Correct:**
+
+```bash
+php artisan make:resource UserResource
+php artisan make:resource UserCollection
+```
+
+```php
+// app/Http/Resources/UserResource.php
+class UserResource extends JsonResource
+{
+    public function toArray(Request $request): array
+    {
+        return [
+            'id'         => $this->id,
+            'name'       => $this->name,
+            'email'      => $this->email,
+            'avatar_url' => $this->avatar_url,
+            'created_at' => $this->created_at->toIso8601String(),
+
+            // Conditional fields
+            'phone' => $this->when(
+                $request->user()?->id === $this->id,
+                $this->phone
+            ),
+
+            // Nested resource
+            'posts_count' => $this->whenCounted('posts'),
+        ];
+    }
+}
+
+// Controller
+public function show(User $user): UserResource
+{
+    return UserResource::make($user);
+}
+
+public function index(): JsonResponse
+{
+    $users = User::with('profile')->paginate(20);
+    return UserResource::collection($users)->response();
+}
+```
+
+**Password and sensitive fields must be in `$hidden`:**
+```php
+class User extends Model
+{
+    protected $hidden = ['password', 'remember_token', 'two_factor_secret'];
+}
+```

package/skill-assets/sunlint-code-quality/rules/php-laravel/LV010-chunk-large-datasets.md

@@ -0,0 +1,58 @@
+---
+title: Use chunk()/cursor() for Large Datasets — Never Model::all()
+impact: HIGH
+impactDescription: Model::all() on a large table loads all rows into memory, causing OOM errors and PHP timeouts
+tags: chunk, cursor, memory, performance, eloquent, laravel
+---
+
+## Use chunk()/cursor() for Large Datasets
+
+`Model::all()` or `->get()` with no limit fetches every row into PHP memory. On a 100k-row table this causes memory exhaustion.
+
+**Wrong:**
+
+```php
+// Memory bomb — loads all rows into PHP array
+$users = User::all();
+foreach ($users as $user) {
+    $user->sendNewsletter();
+}
+
+// Slightly better but still: loads 50k orders at once
+$orders = Order::where('status', 'pending')->get();
+foreach ($orders as $order) {
+    ProcessOrder::dispatch($order);
+}
+```
+
+**Correct:**
+
+```php
+// chunk: fetches 200 rows at a time, re-queries per batch
+User::chunk(200, function ($users) {
+    foreach ($users as $user) {
+        $user->sendNewsletter();
+    }
+});
+
+// cursor: uses lazy collection (PHP generator), one row in memory at a time
+// Best for read-only iteration without modifying records
+foreach (User::cursor() as $user) {
+    $user->sendNewsletter();
+}
+
+// chunkById: safer than chunk for updates (avoids row-skip bug)
+User::where('status', 'inactive')
+    ->chunkById(500, function ($users) {
+        User::whereIn('id', $users->pluck('id'))->delete();
+    });
+
+// For commands/jobs that process everything
+User::select(['id', 'email', 'name']) // only needed columns
+    ->where('newsletter', true)
+    ->chunkById(1000, function ($batch) {
+        SendNewsletterJob::dispatch($batch->pluck('id')->all());
+    });
+```
+
+**Rule of thumb:** any query without `->limit()` or `->paginate()` in a loop or report command must use `chunk()` or `cursor()`.

package/skill-assets/sunlint-code-quality/rules/php-laravel/LV011-db-transactions.md

@@ -0,0 +1,73 @@
+---
+title: Wrap Multi-Step Database Operations in Transactions
+impact: HIGH
+impactDescription: partial failures leave the database in an inconsistent state without transactions
+tags: transactions, database, atomicity, eloquent, laravel
+---
+
+## Wrap Multi-Step Database Operations in Transactions
+
+Any sequence of writes that must succeed or fail together (e.g. create order + deduct stock + charge payment) must run inside a `DB::transaction()`.
+
+**Wrong:**
+
+```php
+// If deductStock() succeeds but createTransaction() fails,
+// stock is deducted but no order exists — corrupted state
+public function placeOrder(Cart $cart, User $user): Order
+{
+    $order = Order::create([...]);
+    $this->deductStock($cart->items);    // can throw
+    $this->createTransaction($order);    // can throw — order exists, stock reduced
+    $this->clearCart($cart);
+    return $order;
+}
+```
+
+**Correct:**
+
+```php
+use Illuminate\Support\Facades\DB;
+
+public function placeOrder(Cart $cart, User $user): Order
+{
+    return DB::transaction(function () use ($cart, $user) {
+        $order = Order::create([
+            'user_id' => $user->id,
+            'total'   => $cart->total(),
+        ]);
+
+        $this->deductStock($cart->items);    // exception -> full rollback
+        $this->createTransaction($order);    // exception -> full rollback
+        $this->clearCart($cart);
+
+        return $order;
+    });
+    // Any Throwable inside auto-rolls back and re-throws
+}
+```
+
+**With custom exception handling:**
+
+```php
+DB::transaction(function () {
+    // ...
+}, attempts: 3); // retry on deadlock (3 attempts)
+```
+
+**Manual control when needed:**
+```php
+DB::beginTransaction();
+try {
+    // ...
+    DB::commit();
+} catch (Throwable $e) {
+    DB::rollBack();
+    throw $e;
+}
+```
+
+**Note:** Dispatching jobs inside a transaction should use `afterCommit()`:
+```php
+ProcessOrder::dispatch($order)->afterCommit(); // only dispatches if transaction commits
+```