Skip to content

A free open source IT asset/license management system

Added copilot instructions file

snipe40843f93dc66
diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md
new file mode 100644
index 0000000000..effe4916a7
--- /dev/null
+++ b/.github/copilot-instructions.md
@@ -0,0 +1,121 @@
+# GitHub Copilot Custom Instructions for Snipe-IT
+
+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.
+
+## ✅ General Coding Standards
+
+- Prefer short, expressive, and readable code.
+- Use **meaningful, descriptive variable, function, class, and file names**.
+- Apply proper PHPDoc blocks for classes, methods, and complex logic.
+- Organize code into small, reusable functions or classes with single responsibility.
+- Avoid magic numbers or hard-coded strings; use constants or config files.
+
+## ✅ PHP 8.2/8.4 Best Practices
+
+- Use **readonly properties** to enforce immutability where applicable.
+- Use **Enums** instead of string or integer constants.
+- Utilize **First-class callable syntax** for callbacks.
+- Leverage **Constructor Property Promotion**.
+- Use **Union Types**, **Intersection Types**, and **true/false return types** for strict typing.
+- Apply **Static Return Type** where needed.
+- Use the **Nullsafe Operator (?->)** for optional chaining.
+- Adopt **final classes** where extension is not intended.
+- Use **Named Arguments** for improved clarity when calling functions with multiple parameters.
+
+## ✅ Laravel 11 Project Structure & Conventions
+
+- Follow the official Laravel project structure:
+ - `app/Http/Controllers` - Controllers
+ - `app/Models` - Eloquent models
+ - `app/Http/Requests` - Form request validation
+ - `app/Http/Resources` - API resource responses
+ - `app/Enums` - Enums
+ - `app/Services` - Business logic
+ - `app/Data` - Data Transfer Objects (DTOs)
+ - `app/Actions` - Single-responsibility action classes
+ - `app/Policies` - Authorization logic
+
+- Controllers must:
+ - Be thin.
+ - Use dependency injection.
+ - Use Form Requests for validation.
+ - Return typed responses (e.g., `JsonResponse`).
+ - Use Resource classes for API responses.
+
+
+## ✅ Eloquent ORM & Database
+
+- Use **Eloquent Models** with proper `$fillable` or `$guarded` attributes for mass assignment protection.
+- Utilize **casts** for date, boolean, JSON, and custom data types.
+- Apply **accessors & mutators** for attribute transformation.
+- Avoid direct raw SQL unless absolutely necessary; prefer Eloquent or Query Builder.
+- Migrations:
+ - Always use migrations for schema changes.
+ - Include proper constraints (foreign keys, unique indexes, etc.).
+ - Prefer UUIDs or ULIDs as primary keys where applicable.
+
+## ✅ API Development
+
+- Use **API Resource classes** for consistent and structured JSON responses.
+- Apply **route model binding** where possible.
+- Use Form Requests for input validation.
+
+## ✅ Blade & Frontend (if applicable)
+
+- Keep Blade templates clean and logic-free; use View Composers or dedicated View Models for complex data.
+- Use `@props`, `@aware`, `@once` Blade features appropriately.
+- Utilize Alpine.js or Livewire for interactive frontend logic (optional).
+
+## ✅ Security Best Practices
+
+- Never trust user input; always validate and sanitize inputs.
+- Use prepared statements via Eloquent or Query Builder to prevent SQL injection.
+- Use Laravel's built-in CSRF, XSS, and validation mechanisms.
+- Store sensitive information in `.env`, never hard-code secrets.
+- Apply proper authorization checks using Policies or Gates.
+- Follow principle of least privilege for users, roles, and permissions.
+
+## ✅ Testing Standards
+
+- Use **factories** for test data setup.
+- Include feature tests for user-facing functionality.
+- Include unit tests for business logic, services, and helper classes.
+- Mock external services using Laravel's `Http::fake()` or equivalent.
+- Maintain high code coverage but focus on meaningful tests over 100% coverage obsession.
+
+## ✅ Software Quality & Maintainability
+
+- Follow **SOLID Principles**:
+ - Single Responsibility Principle (SRP)
+ - Open/Closed Principle (OCP)
+ - Liskov Substitution Principle (LSP)
+ - Interface Segregation Principle (ISP)
+ - Dependency Inversion Principle (DIP)
+
+- Follow **DRY** (Don't Repeat Yourself) and **KISS** (Keep It Simple, Stupid) principles.
+- Apply **YAGNI** (You Aren't Gonna Need It) to avoid overengineering.
+- Document complex logic with PHPDoc and inline comments.
+
+## ✅ Performance & Optimization
+
+- Eager load relationships to avoid N+1 queries.
+- Use caching with Laravel's Cache system for frequently accessed data.
+- Paginate large datasets using `paginate()` instead of `get()`.
+- Queue long-running tasks using Laravel Queues.
+- Optimize database indexes for common queries.
+
+## ✅ Modern Laravel Features to Use
+
+- Use **Event Broadcasting** if real-time updates are needed.
+- Use **Full-text search** if search functionality is required.
+- Use **Rate Limiting** for API routes.
+
+## ✅ Additional Copilot Behavior Preferences
+
+- Generate **strictly typed**, modern PHP code using latest language features.
+- Prioritize **readable, clean, maintainable** code over cleverness.
+- Avoid legacy or deprecated Laravel patterns (facade overuse, logic-heavy views, etc.).
+- Suggest proper class placement based on Laravel directory structure.
+- Suggest tests alongside new features where applicable.
+- Default to **immutability**, **dependency injection**, and **encapsulation** best practices.
+ No newline at end of file