laravel-copilot-instructions/copilot-instruction/copilot-ai-guidelines.instructions.md

# Copilot Configuration for Laravel AI Guidelines

This file is intended to be used with GitHub Copilot or any AI code assistant.
It enforces the rules defined in **ai-guidelines.md** and ensures consistent,
optimized, secure, and validated Laravel 12.x code generation.

## 📌 Configuration Instructions

Place this file in one of the following locations:

```
/.copilot/config.json
```

or

```
/.github/copilot-instructions.md
```

---

# ✅ Copilot Instructions (Auto-Formatting, Auto-Validation, Optimized Laravel 12.x Code)

Copilot MUST follow these rules for all Laravel code:

---

## 1️⃣ General Laravel Code Rules

- Always write **clean, readable, maintainable** Laravel code.
- Follow **Laravel 12.x documentation**: https://laravel.com/docs/12.x/releases
- Use PSR-12 formatting.
- Follow naming conventions:
  - Classes → PascalCase
  - Methods/variables → camelCase
  - Database → snake_case
- Functions must be short and meaningful.
- Avoid unnecessary complexity.

---

## 2️⃣ Controllers (Thin Controllers Only)

- Must always use **try/catch**.
- Must always use **FormRequest validation**, never inline validation.
- Must return **standardized JSON responses** using ApiResponseTrait.
- Must use correct HTTP status codes:
  - 200 OK
  - 201 Created
  - 400 Bad Request
  - 401 Unauthorized
  - 404 Not Found
  - 422 Validation Error
  - 500 Server Error
- No DB logic allowed inside controllers.

---

## 3️⃣ Services (Business Logic)

- All core logic must be placed here.
- Must always use try/catch and log exceptions.
- Must use optimized Eloquent:
  - select()
  - when()
  - with()
  - paginate()
- Use DB::transaction for multi-step operations.
- Never return JSON (controller handles responses).

---

## 4️⃣ Models

- Use $fillable or $guarded.
- Use casts for JSON, arrays, and booleans.
- Use relationships and scopes.
- No business logic inside models.

---

## 5️⃣ Validation (Strict)

- Must always use FormRequest.
- All input must be validated.
- Never trust raw request data.

---

## 6️⃣ API Response Standardization

Use ApiResponseTrait:

```
success(data, message, status)
error(message, status)
```

- Every success/error response must use these wrappers.

---

## 7️⃣ Jobs / Queues

- All heavy tasks must be queued using Jobs.
- Jobs must use try/catch and log errors.
- Never handle heavy tasks inside controller/service.

---

## 8️⃣ Performance Rules

- Never return entire tables → must use pagination.
- Avoid N+1 → always use eager loading.
- Use select() to reduce data load.
- Use indexes in migrations.
- Optimize filters using when().
- Use caching for repeated queries.

---

## 9️⃣ Security Rules

- Hash passwords, never store plain text.
- Validate all inputs.
- Sanitize user data.
- Prevent SQL/XSS injection.
- Do not expose stack traces in responses.

---

## 🔟 Forbidden

Copilot must NOT:

- Use Repository Pattern.
- Use SOLID over-engineered architecture.
- Write raw SQL inside controllers.
- Put business logic inside controllers.
- Write nested DB queries inside loops.
- Generate large unpaginated queries.
- Return raw models in API.

---

# 🎯 Final Result

Copilot will now automatically generate:

- Clean Laravel 12.x code
- Always validated
- Always optimized
- Always readable
- Always secure
- Always using try/catch
- Always using proper HTTP codes
- Always using Laravel best practices

---

**End of Copilot Configuration**