Programming Rules - JeroCardona/IMEC GitHub Wiki

Programming Rules - Detailed Version

Repository

Requirements

All tasks and requirements must be managed on GitHub Projects.
Tasks should begin with user or admin to specify the development area.
Clearly define the responsible developer for each task.

Commits

Use consistent commit messages starting with the following verbs:
- Implement: When adding new features. E.g., Implement authentication system.
- Fix: When fixing errors or bugs. E.g., Fix session handling issue.
- Delete: When removing obsolete code. E.g., Delete unused controller.
- Update: For small changes and optimizations. E.g., Update user dashboard design.

Git Branches

Each developer works on an individual branch. Submit a pull request to merge into the development branch.
The master branch is for production-ready code.

Pull Requests

Reviewed and approved by the project architect or technical lead.

Controllers

General Principles:

Each controller must handle only one responsibility (Single Responsibility Principle).
Reusable logic should not be placed in controllers but in utility classes or services.

Function Design:

Naming: Each method should have a clear and descriptive name related to its purpose.
Return Type: Each method must specify its return type. If a method doesn’t return anything, specify void.
Parameter Types: Ensure every parameter has a defined type (int, string, array, etc.).

Example:
```
public function getUser(int $id): User
{
    // function logic
}
```

Avoidances:

Do not use echo or dd() for debugging in production code.
Avoid writing complex logic directly in controllers—delegate it to services or utility classes.

Data Management:

Use $viewData to pass data from the controller to the views, ensuring that data is clean and well-structured.

Session Handling:

Use session data to handle flash messages, alerts, and temporary information across requests.

When Creating Additional Controllers:

Follow RESTful conventions. For example:
- GET requests for retrieving data.
- POST for creating new records.
- PUT/PATCH for updating.
- DELETE for deleting.
If a new controller is needed, ensure it handles one specific domain or entity.

Models

Attribute Declaration:

Separate primitive attributes from non-primitive ones, clearly indicating the data type for each:

/**
 * USER ATTRIBUTES
 * $this->attributes['id'] - int - the user primary key (id)
 * $this->attributes['email'] - string - the user's email address
 * $this->attributes['created_at'] - timestamp - the creation date of the user
 * 
 * $this-> orders - Order[] - contains the associated orders
 */

Data Validation:

Place validation logic in the model itself using static validation functions.

public static function validate(array $data): array
{
    return Validator::make($data, [
        'name' => 'required|string',
        'email' => 'required|email|unique:users,email',
    ])->validate();
}

Return Type and Parameters:

Every method must clearly define its return type and parameter types.

Example:
```
public function getOrders(): array
{
    return $this->orders;
}
```

Relationships:

For models with relationships, use BelongsTo and HasMany to clearly establish the relationships with other models.
```
public function orders(): HasMany
{
    return $this->hasMany(Order::class);
}
```

Getters/Setters:

Use getters for created_at and updated_at attributes.
Avoid using setters for primary keys (such as id).

Additional Models:

Create additional models only when necessary to represent new entities or relationships.
Ensure each model adheres to single responsibility: a model should only handle the data for one entity.

Functions

General Function Design:

Verb Naming: Functions must be named using a verb that describes the action. E.g., calculateTotalPrice, fetchUserData.
Return Type: Always declare the return type of the function (string, int, bool, array, object, void, etc.).

Example:
```
public function calculateTotalPrice(array $items): float
{
    // Logic for calculating total price
}
```
Parameter Types: Every parameter must have a specified type. Use int, float, array, string, etc.

Error Handling:

Functions should handle errors gracefully. Instead of returning null, return a proper error message or throw exceptions if something goes wrong.

Views

File Structure:

Use .blade.php for all view files, to take advantage of Blade templating.
Do not open/close PHP tags directly in views. Instead, use Blade syntax.

Accessing Data:

Access object attributes using getters, for example, {{ $user->getName() }}.

Partial Views:

Shared components like navbar, sidebar, and footer should be placed in the partials folder for reusability.

Routes

Route Definitions:

Each route must be associated with a specific controller method.
Avoid defining functions or logic inside routes—keep routes clean and simple.

Route Groups:

Organize routes into separate files based on their domain (e.g., user, admin, api).