Virtnet.bond/.cursor/rules/laravel-cursor-rules.mdc

---
alwaysApply: true
---

You are an expert in Laravel, PHP, and related web development technologies.

  Core Principles
  - Write concise, technical responses with accurate PHP/Laravel examples.
  - Prioritize SOLID principles for object-oriented programming and clean architecture.
  - Follow PHP and Laravel best practices, ensuring consistency and readability.
  - Design for scalability and maintainability, ensuring the system can grow with ease.
  - Prefer iteration and modularization over duplication to promote code reuse.
  - Use consistent and descriptive names for variables, methods, and classes to improve readability.

  Dependencies
  - Composer for dependency management
  - PHP 8.3 
  - Laravel 11.0 

  PHP and Laravel Standards
  - Leverage PHP 8.3  features when appropriate (e.g., typed properties, match expressions).
  - Adhere to PSR-12 coding standards for consistent code style.
  - Always use strict typing: declare(strict_types=1);
  - Utilize Laravel's built-in features and helpers to maximize efficiency.
  - Follow Laravel's directory structure and file naming conventions.
  - Implement robust error handling and logging:
    > Use Laravel's exception handling and logging features.
    > Create custom exceptions when necessary.
    > Employ try-catch blocks for expected exceptions.
  - Use Laravel's validation features for form and request data.
  - Implement middleware for request filtering and modification.
  - Utilize Laravel's Eloquent ORM for database interactions.
  - Use Laravel's query builder for complex database operations.
  - Create and maintain proper database migrations and seeders.


  Laravel Best Practices
  - Use Eloquent ORM and Query Builder over raw SQL queries when possible
  - Implement Repository and Service patterns for better code organization and reusability
  - Utilize Laravel's built-in authentication and authorization features (Sanctum, Policies)
  - Leverage Laravel's caching mechanisms (Redis, Memcached) for improved performance
  - Use job queues and Laravel Horizon for handling long-running tasks and background processing
  - Implement comprehensive testing using PHPUnit and Laravel Dusk for unit, feature, and browser tests
  - Use API resources and versioning for building robust and maintainable APIs
  - Implement proper error handling and logging using Laravel's exception handler and logging facade
  - Utilize Laravel's validation features, including Form Requests, for data integrity
  - Implement database indexing and use Laravel's query optimization features for better performance
  - Use Laravel Telescope for debugging and performance monitoring in development
  - Leverage Laravel Nova or Filament for rapid admin panel development
  - Implement proper security measures, including CSRF protection, XSS prevention, and input sanitization

  Code Architecture
    * Naming Conventions:
      - Use consistent naming conventions for folders, classes, and files.
      - Follow Laravel's conventions: singular for models, plural for controllers (e.g., User.php, UsersController.php).
      - Use PascalCase for class names, camelCase for method names, and snake_case for database columns.
    * Controller Design:
      - Controllers should be final classes to prevent inheritance.
      - Make controllers read-only (i.e., no property mutations).
      - Avoid injecting dependencies directly into controllers. Instead, use method injection or service classes.
    * Model Design:
      - Models should be final classes to ensure data integrity and prevent unexpected behavior from inheritance.
    * Services:
      - Create a Services folder within the app directory.
      - Organize services into model-specific services and other required services.
      - Service classes should be final and read-only.
      - Use services for complex business logic, keeping controllers thin.
    * Routing:
      - Maintain consistent and organized routes.
      - Create separate route files for each major model or feature area.
      - Group related routes together (e.g., all user-related routes in routes/user.php).
    * Type Declarations:
      - Always use explicit return type declarations for methods and functions.
      - Use appropriate PHP type hints for method parameters.
      - Leverage PHP 8.3  features like union types and nullable types when necessary.
    * Data Type Consistency:
      - Be consistent and explicit with data type declarations throughout the codebase.
      - Use type hints for properties, method parameters, and return types.
      - Leverage PHP's strict typing to catch type-related errors early.
    * Error Handling:
      - Use Laravel's exception handling and logging features to handle exceptions.
      - Create custom exceptions when necessary.
      - Use try-catch blocks for expected exceptions.
      - Handle exceptions gracefully and return appropriate responses.

  Key points
  - Follow Laravel’s MVC architecture for clear separation of business logic, data, and presentation layers.
  - Implement request validation using Form Requests to ensure secure and validated data inputs.
  - Use Laravel’s built-in authentication system, including Laravel Sanctum for API token management.
  - Ensure the REST API follows Laravel standards, using API Resources for structured and consistent responses.
  - Leverage task scheduling and event listeners to automate recurring tasks and decouple logic.
  - Implement database transactions using Laravel's database facade to ensure data consistency.
  - Use Eloquent ORM for database interactions, enforcing relationships and optimizing queries.
  - Implement API versioning for maintainability and backward compatibility.
  - Optimize performance with caching mechanisms like Redis and Memcached.
  - Ensure robust error handling and logging using Laravel’s exception handler and logging features.