Programming Rules

Naming Conventions

• The name of any class should be in PascalCase.
• Variable and function names should be in camelCase.
• Primitive attribute names should be in snake_case, like in database columns.
• Descriptive names should be used for variables and functions/methods.
• All code must be written in English.
• The author of the code must be included at the top of every newly created file.

Type Definitions

1. For functions with parameters or return values that can accept multiple types (e.g., string | int), use the format <type 1> | <type 2>.
2. Special Case for Null Values: Instead of string | null, use the shorthand ?string as required by Laravel Pint.

Testing

• Use the #[Test] attribute (import use PHPUnit\Framework\Attributes\Test;) to mark unit tests. Avoid using /** @test */, as it is deprecated.

Access Methods

• Each controller must define getters and setters for any data it handles and expose them to views for consistency and maintainability.
• For relationships involving multiple instances of a model, replace setters with add and remove methods.
• Ensure bidirectional relationships between related models by linking attributes in both.
• Use a viewData dictionary-like structure to send all data to Blade views consistently.

Routes

• All routes must follow a standardized key-value format, e.g.:

  Route::get('/admin/games', 'App\Http\Controllers\AdminGameController@index')->name('admin-game.index');

• Use the route() helper for clean routing and attribute access, e.g.:

  ... href"{{ route('game.show', ['id' => $game->getId()]) }} ...

Controllers

• Ensure controllers adhere to the Single Responsibility Principle.
• Create dedicated controllers for error handling and session management.
• Handle form validation at the model level.
• Use flash messages for notifications after successful operations like creation, updates, or deletions.

Models

• Annotate each model with a comment listing its attributes and relationships.
• Include a factory for seeding data.
• Avoid creating models or controllers for intermediate tables in many-to-many relationships unless the table includes additional attributes.
• The attributes that are foreign keys needs a (Foreign key) mark at the end of its comment in the attributes comment, and a // Foreign key comment above it's principal function. The principal function is the basic one (not get, set, add or remove, just the one with the name of the other table), e.g.:

(In CustomUser, there's a foreign key to Order, a one to many relationship.)
// app\Models\CustomUser.php

(...)

/**
  * CUSTOM USER ATTRIBUTES
  (...)
  * $this->orders - Order[] - contains the orders associated with the custom user. (Foreign key)
  (...)
  */

(...)

// Foreign key
public function orders(): HasMany
{
    return $this->hasMany(Order::class);
}

Views

• All views must extend the app layout and use Blade (.blade.php).
• Avoid PHP open and close tags (<?php ?>) in views.
• Admin views (index, show, create, edit) should maintain uniform structure and style, using admin-game as a reference.
• Group routes requiring admin or user authentication (auth) in web.php, not individual controllers.

Formatting and Structure

• Use Pint for automated code formatting.
• Centralize text management using Language Files for multilingual support.
• Always include parameter types and return types in function definitions.

Utils

• Reusable functions or logic shared across models or controllers should be placed in app\Utils.

Documentation and Comments

• Follow the /GUIDES/ directory for implementation instructions.
• Add comments only when necessary for understanding code logic.

Branching Strategy

• Adhere to a three-branch workflow: main, develop, and personal branches.
  1. Work in personal branches.
  2. Merge personal branches into develop.
  3. Incorporate changes from develop into personal branches.
  4. Merge develop into main only with unanimous approval.

Deployment and Cloning

• Follow the deployment or cloning steps in the README for consistent environments.

Post-Route Creation Commands

After creating or modifying routes, run:

php artisan config:cache
php artisan route:cache
php artisan view:cache
php artisan cache:clear