|
| 1 | +# GitHub Copilot Custom Instructions for Snipe-IT |
| 2 | + |
| 3 | +These instructions guide Copilot to generate code that aligns with modern Laravel 11 standards, PHP 8.2/8.4 features, software engineering principles, and industry best practices to improve software quality, maintainability, and security. |
| 4 | + |
| 5 | +## ✅ General Coding Standards |
| 6 | + |
| 7 | +- Prefer short, expressive, and readable code. |
| 8 | +- Use **meaningful, descriptive variable, function, class, and file names**. |
| 9 | +- Apply proper PHPDoc blocks for classes, methods, and complex logic. |
| 10 | +- Organize code into small, reusable functions or classes with single responsibility. |
| 11 | +- Avoid magic numbers or hard-coded strings; use constants or config files. |
| 12 | + |
| 13 | +## ✅ PHP 8.2/8.4 Best Practices |
| 14 | + |
| 15 | +- Use **readonly properties** to enforce immutability where applicable. |
| 16 | +- Use **Enums** instead of string or integer constants. |
| 17 | +- Utilize **First-class callable syntax** for callbacks. |
| 18 | +- Leverage **Constructor Property Promotion**. |
| 19 | +- Use **Union Types**, **Intersection Types**, and **true/false return types** for strict typing. |
| 20 | +- Apply **Static Return Type** where needed. |
| 21 | +- Use the **Nullsafe Operator (?->)** for optional chaining. |
| 22 | +- Adopt **final classes** where extension is not intended. |
| 23 | +- Use **Named Arguments** for improved clarity when calling functions with multiple parameters. |
| 24 | + |
| 25 | +## ✅ Laravel 11 Project Structure & Conventions |
| 26 | + |
| 27 | +- Follow the official Laravel project structure: |
| 28 | + - `app/Http/Controllers` - Controllers |
| 29 | + - `app/Models` - Eloquent models |
| 30 | + - `app/Http/Requests` - Form request validation |
| 31 | + - `app/Http/Resources` - API resource responses |
| 32 | + - `app/Enums` - Enums |
| 33 | + - `app/Actions` - Single-responsibility action classes |
| 34 | + - `app/Policies` - Authorization logic |
| 35 | + |
| 36 | +- Controllers must: |
| 37 | + - Use dependency injection. |
| 38 | + - Use Form Requests for validation. The request class should utilize the rules set on the model. |
| 39 | + - Return typed responses (e.g., `JsonResponse`). |
| 40 | + - Use Transformers for API responses. |
| 41 | + |
| 42 | +## ✅ Eloquent ORM & Database |
| 43 | + |
| 44 | +- Use **Eloquent Models** with proper `$fillable` or `$guarded` attributes for mass assignment protection. |
| 45 | +- Utilize **casts** for date, boolean, JSON, and custom data types. |
| 46 | +- Apply **accessors & mutators** for attribute transformation. |
| 47 | +- Avoid direct raw SQL unless absolutely necessary; prefer Eloquent or Query Builder. |
| 48 | +- Migrations: |
| 49 | + - Always use migrations for schema changes. |
| 50 | + - Include proper constraints (foreign keys, unique indexes, etc.). |
| 51 | + - Prefer UUIDs or ULIDs as primary keys where applicable. |
| 52 | + |
| 53 | +## ✅ API Development |
| 54 | + |
| 55 | +- Use **Transformer classes** for consistent and structured JSON responses. |
| 56 | +- Apply **route model binding** where possible. |
| 57 | +- Use Form Requests for input validation. |
| 58 | + |
| 59 | +## ✅ Blade & Frontend (if applicable) |
| 60 | + |
| 61 | +- Keep Blade templates clean and logic-free; use View Composers or dedicated View Models for complex data. |
| 62 | +- Use `@props`, `@aware`, `@once` Blade features appropriately. |
| 63 | +- Utilize Alpine.js or Livewire for interactive frontend logic (optional). |
| 64 | + |
| 65 | +## ✅ Security Best Practices |
| 66 | + |
| 67 | +- Never trust user input; always validate and sanitize inputs. |
| 68 | +- Use prepared statements via Eloquent or Query Builder to prevent SQL injection. |
| 69 | +- Use Laravel's built-in CSRF, XSS, and validation mechanisms. |
| 70 | +- Store sensitive information in `.env`, never hard-code secrets. |
| 71 | +- Apply proper authorization checks using Policies or Gates. |
| 72 | +- Follow principle of least privilege for users, roles, and permissions. |
| 73 | + |
| 74 | +## ✅ Testing Standards |
| 75 | + |
| 76 | +- Use **factories** for test data setup. |
| 77 | +- Include feature tests for user-facing functionality. |
| 78 | +- Include unit tests for business logic, services, and helper classes. |
| 79 | +- Mock external services using Laravel's `Http::fake()` or equivalent. |
| 80 | +- Maintain high code coverage but focus on meaningful tests over 100% coverage obsession. |
| 81 | + |
| 82 | +## ✅ Software Quality & Maintainability |
| 83 | + |
| 84 | +- Follow **SOLID Principles**: |
| 85 | + - Single Responsibility Principle (SRP) |
| 86 | + - Open/Closed Principle (OCP) |
| 87 | + - Liskov Substitution Principle (LSP) |
| 88 | + - Interface Segregation Principle (ISP) |
| 89 | + - Dependency Inversion Principle (DIP) |
| 90 | + |
| 91 | +- Follow **DRY** (Don't Repeat Yourself) and **KISS** (Keep It Simple, Stupid) principles. |
| 92 | +- Apply **YAGNI** (You Aren't Gonna Need It) to avoid overengineering. |
| 93 | +- Document complex logic with PHPDoc and inline comments. |
| 94 | + |
| 95 | +## ✅ Performance & Optimization |
| 96 | + |
| 97 | +- Eager load relationships to avoid N+1 queries. |
| 98 | +- Use caching with Laravel's Cache system for frequently accessed data. |
| 99 | +- Paginate large datasets using `paginate()` instead of `get()`. |
| 100 | +- Queue long-running tasks using Laravel Queues. |
| 101 | +- Optimize database indexes for common queries. |
| 102 | + |
| 103 | +## ✅ Modern Laravel Features to Use |
| 104 | + |
| 105 | +- Use **Event Broadcasting** if real-time updates are needed. |
| 106 | +- Use **Full-text search** if search functionality is required. |
| 107 | +- Use **Rate Limiting** for API routes. |
| 108 | + |
| 109 | +## ✅ Additional Copilot Behavior Preferences |
| 110 | + |
| 111 | +- Generate **strictly typed**, modern PHP code using latest language features. |
| 112 | +- Prioritize **readable, clean, maintainable** code over cleverness. |
| 113 | +- Avoid legacy or deprecated Laravel patterns (facade overuse, logic-heavy views, etc.). |
| 114 | +- Suggest proper class placement based on Laravel directory structure. |
| 115 | +- Suggest tests alongside new features where applicable. |
| 116 | +- Default to **immutability**, **dependency injection**, and **encapsulation** best practices. |
| 117 | + No newline at end of file |
0 commit comments