Coding standards

1. General

• Use PHP with Laravel conventions.
• Use strict, readable, maintainable code.
• Follow the existing Laravel project structure.
• Reuse existing classes, services, models, requests, resources, traits, and utilities before creating new ones.
• Do not duplicate logic.
• Do not make unrelated changes.
• Do not invent business rules, API behavior, calculations, fields, enums, or validation rules.
• Follow the approved backend/API contract.
• Keep business logic out of controllers whenever possible.
• Prefer simple solutions over unnecessary abstraction.
• Consistency is more important than personal coding preference.

2. File & folder naming

Use clear, descriptive names and follow Laravel conventions.

Controllers

PascalCase.

AuthController.php
SessionController.php
WellnessController.php
DashboardController.php
WorkloadController.php

Models

PascalCase and singular.

User.php
BowlingSession.php
WellnessCheck.php
DailyWorkload.php

Services

PascalCase with Service suffix.

AuthService.php
SessionService.php
WorkloadService.php
WellnessService.php

Form requests

PascalCase with Request suffix.

LoginRequest.php
CreateSessionRequest.php
StoreWellnessRequest.php

API resources

PascalCase with Resource suffix.

UserResource.php
SessionResource.php
DashboardResource.php

Jobs

PascalCase with descriptive names.

ProcessDailyWorkload.php
CalculateDailyMetrics.php

Commands

PascalCase with descriptive names.

ProcessDailyWorkloadCommand.php

Tests

Descriptive PascalCase names.

SessionTest.php
WorkloadCalculationTest.php
AuthenticationTest.php

3. Classes

Use PascalCase. Class names must clearly describe their responsibility.

class workloadservice
{
}

class WorkloadService
{
}

Avoid generic classes such as Helper, Manager, Common, or Utils unless the responsibility is genuinely clear and justified.

4. Methods / functions

Use camelCase and action-based names.

getDashboard()
createSession()
saveWellnessCheck()
calculateDailyLoad()
processDailyWorkload()
determineShieldPhase()

GetDashboard()
get_dashboard()
doStuff()

Preferred action prefixes:

• create, update, delete, get, find
• calculate, process, validate, determine, build, format

Boolean methods should normally use is, has, can, should, or was.

isCompleted()
hasSession()
canAccess()
shouldProcess()
wasSuccessful()

5. Variables

Use camelCase and descriptive names. Avoid unclear abbreviations.

$dailyLoad
$sessionDate
$userProfile
$workloadRatio
$isActive

$daily_load
$DailyLoad
$dl
$d
$x
$tmp
$val

Boolean variables use is, has, can, should, or was: $isActive, $hasCompleted, $canSubmit, $shouldProcess, $wasSuccessful.

6. Function parameters

Use descriptive camelCase names and type declarations whenever possible.

function calculateDailyLoad(
    int $ballsBowled,
    int $effortRating,
    float $auxiliaryMultiplier
)

function calculateDailyLoad(
    int $b,
    int $e,
    float $m
)

7. Return types

Use explicit return types where practical. Avoid unnecessary untyped or mixed returns.

public function calculateDailyLoad(): float
{
}

public function createSession(): BowlingSession
{
}

public function isCompleted(): bool
{
}

8. Properties

Use camelCase, explicit visibility, and the most restrictive visibility that fits.

private int $userId;
private float $dailyLoad;
private bool $isActive;

9. Constants

Use UPPER_SNAKE_CASE. Define a genuine constant once. Do not scatter the same fixed value.

private const MAX_RETRY_ATTEMPTS = 3;
ACUTE_EWMA_ALPHA
CHRONIC_EWMA_ALPHA
DEFAULT_TIMEOUT

maxRetryAttempts
MaxRetryAttempts
max_retry_attempts

10. Configuration values

Do not hardcode environment-specific values. Prefer Laravel configuration. Secrets belong in .env. Never commit credentials.

$apiUrl = 'https://example.com';

config('services.example.url');

11. Magic numbers and strings

Avoid unexplained magic values. If a value is an approved business rule, centralize it (for example SYSTEM_FATIGUE_THRESHOLD). Do not create or change business-rule values unless they are defined in the approved requirements.

if ($ratio >= 1.5) {
}

12. Enums

Use PascalCase for enum names. Use the exact approved API/database values. Never invent enum values.

• SessionType
• EffortLevel
• KineticChainFeel
• OtherDemandType
• ShieldPhase

13. Arrays

Use descriptive camelCase keys.

[
    'sessionType' => $sessionType,
    'effortRating' => $effortRating,
    'dailyLoad' => $dailyLoad,
]