Programming rules - JoseTor101/ApollosGearShop GitHub Wiki

General recommendations

  • Use Comments in English: All comments and documentation must be written in English for consistency.
  • Parameter Type-Hinting and return type: Always type-hint parameters for better clarity and validation and return type for functions:
function calculateTotalPrice(float $price, float $taxRate): float
{
   //your code
}
  • Getter and Setter Usage: Instead of directly accessing object properties, use getters and setters to maintain encapsulation.
<h1>{{ $review->getTitle() }}</h1>
<p>{{ $review->getDescription() }}</p>
  • Use Key-Value Format: When working with arrays, always use the key-value format to improve clarity and prevent errors.
$viewData = [
    'title' => __('Title'),
    'subtitle' => __('Subtitle'),
    'reviews' => $reviews,
];

1. Controllers

  • Use Dependency Injection: Utilize Laravel's dependency injection for injecting services and dependencies into your controllers, avoiding the use of facades within methods whenever possible.
  • Follow RESTful Conventions: Adhere to RESTful principles by naming your controller methods appropriately (index, show, store, update, destroy).
  • Avoid Business Logic in Controllers: Controllers should delegate business logic to service classes or models, keeping the controllers thin and focused on handling HTTP requests.

2. Models

  • Getters and Setters: Access model attributes using getters and setters for encapsulation and maintainability.
  • Keep Models Clean: Models should only contain the properties and methods that relate to the database table they represent. Avoid placing business logic or heavy processing in models.
  • Validation in Models: As a best practice, validate input data in models, ensuring that controllers only delegate tasks. For example:
public function validate(array $data): array
{
    $validator = Validator::make($data, [
        'description' => 'required|max:255',
        'score' => 'required|integer|min:1|max:5',
    ]);

    return $validator->validated();
}
  • Use Eloquent Relationships: Leverage Eloquent's built-in relationship methods (e.g., hasOne, belongsTo, hasMany) to define relationships between models.
  • Mass Assignment Protection: Use $fillable or $guarded properties to protect against mass assignment vulnerabilities.
  • Scope Queries: Utilize query scopes for reusable query logic, making your queries more readable and reusable across the application.

3. Views

  • Blade Templates Only: All views must be created using Blade templating engine. Do not mix PHP directly within Blade templates; use Blade's syntax instead.
  • Extend from Layouts: All views should extend from a base layout, typically layouts.app. This ensures a consistent look and feel across the application.
  • Avoid Logic in Views: Business logic should not be present in views. Keep views focused on presentation, using Blade's control structures (@if, @foreach) sparingly and appropriately.
  • Pass Data from Controllers: Data used in views should be passed from controllers or view composers, not hardcoded into the view files.
  • Access information from model with its corresponding getters and setters.

4. Routes

  • Route to Controllers: Every route must be associated with a controller method. Avoid using closures in route definitions, as they are harder to test and maintain.
  • Access controller sintax: We prefer static names, example: Example:
Route::get('/instruments', 'App\Http\Controllers\InstrumentController@index')->name('instrument.index');
  • RESTful Routes: Define routes following RESTful conventions, keeping route definitions concise and meaningful.
  • Named Routes: Always use named routes for easier referencing and maintenance within views and controllers.

Additional Suggestions

  • Lang Tags: Use language tags for translatable strings in the views. This ensures better maintainability and localization support.
<h1>{{ __('review.create_title') }}</h1>
⚠️ **GitHub.com Fallback** ⚠️