Naming Conventions Guide

Last Updated: 2026-01-22 Status: Active Audience: Developers

This guide documents the naming conventions used throughout the Client Portal codebase to ensure consistency and maintainability.

Table of Contents

1. PHP Classes
2. Methods and Functions
3. Variables
4. Database
5. Files and Directories
6. Routes
7. Configuration
8. Views
9. Tests

PHP Classes

Controllers

// Good
namespace App\Http\Controllers;
class ClientController extends Controller {}

namespace App\Http\Controllers\Admin;
class DashboardController extends Controller {}

// Bad
class clientController {}  // Wrong case
class ClientsController {} // Don't pluralize

Models

// Good
class Client extends Model {}
class ProjectFile extends Model {}
class InvoiceItem extends Model {}

// Bad
class Clients extends Model {}     // Don't pluralize
class project_file extends Model {} // Wrong case

Services

// Good
class InvoiceService {}
class CreateInvoiceAction {}

// Bad
class InvoiceServiceClass {} // Redundant suffix
class invoiceService {}      // Wrong case

Service Naming Standards (Detailed)

This section provides detailed naming standards for the Services directory.

Service Classes

All service classes should use the *Service.php suffix:

// Good
class TrendAnalysisService {}     // Analysis functionality
class FileUploadService {}        // Upload handling
class NotificationDeliveryService {} // Delivery logic

// Bad
class TrendAnalyzer {}    // Missing Service suffix
class FileUploader {}     // Missing Service suffix

Builder Services (with Dependencies)

Builders that have dependencies (use DI) should have *BuilderService.php suffix:

// Good - has DI dependencies
class ChartBuilderService {
    public function __construct(private ChartFactory $factory) {}
}

class ReportQueryBuilderService {
    public function __construct(private DataSourceRegistry $registry) {}
}

Pure Builders (No Dependencies)

Pure utility builders without dependencies can use *Builder.php without the Service suffix:

// Good - pure utility, no DI
class CacheKeyBuilder {
    public static function build(string ...$parts): string {}
}

Registry Classes

Registry classes use *Registry.php suffix (no Service):

// Good
class ReportRegistry {}
class WidgetRegistry {}
class ExportFormatRegistry {}

DTOs (Data Transfer Objects)

DTOs should be placed in App\DataTransferObjects\ namespace:

// Good - in App\DataTransferObjects
namespace App\DataTransferObjects;

readonly class ParsedQuery {
    public function __construct(
        public string $textSearch,
        public array $filters = [],
    ) {}
}

Value Objects

Value objects with logic should be placed in App\Support\{Domain}\:

// Good - in App\Support\Search
namespace App\Support\Search;

final class SearchContext {
    public function __construct(
        public readonly ?User $user = null,
        public readonly int $limit = 10,
    ) {}
}

Directory Structure for Services

app/Services/
├── Analytics/
│   ├── TrendAnalysisService.php      # Analysis service
│   ├── KpiService.php                 # Domain service
│   └── DrillDown/
│       └── DrillDownQueryBuilder.php  # Pure builder
├── Reports/
│   ├── ReportService.php              # Domain service
│   ├── ChartBuilderService.php        # Builder with DI
│   ├── ReportRegistry.php             # Registry
│   └── Builder/
│       └── CustomReportBuilder.php    # Implementation
└── Cache/
    └── CacheKeyBuilder.php            # Pure utility

app/DataTransferObjects/
├── ParsedQuery.php                    # Search DTO
├── SearchResults.php                  # Results DTO
└── LeadScore.php                      # Scoring DTO

app/Support/
└── Search/
    └── SearchContext.php              # Value object

Other Classes

Methods and Functions

General Methods

// Good
public function getActiveClients() {}
public function isOverdue(): bool {}
public function hasUnpaidInvoices(): bool {}
public function canAccessProject(Project $project): bool {}

// Bad
public function GetActiveClients() {}  // Wrong case
public function active(): bool {}      // Missing 'is' prefix for boolean

Controller Methods

Follow Laravel resource conventions:

Variables

Local Variables

// Good
$activeClients = Client::where('is_active', true)->get();
$isOverdue = $invoice->due_date < now();
$totalAmount = $items->sum('amount');

// Bad
$active_clients = [];  // Use camelCase
$overdue = true;       // Add 'is' prefix for booleans
$client_list = [];     // Use plural without 'list'

Constants

// Good
class Invoice
{
    public const MAX_LINE_ITEMS = 100;
    public const DEFAULT_DUE_DAYS = 30;
}

enum InvoiceStatus: string
{
    case Draft = 'draft';
    case Sent = 'sent';
    case Paid = 'paid';
}

// Bad
class Invoice
{
    public const maxLineItems = 100;  // Wrong case
    public const Max_Items = 100;     // Wrong case
}

Database

Tables

// Good - Migration
Schema::create('project_files', function (Blueprint $table) {});
Schema::create('client_user', function (Blueprint $table) {});  // Pivot

// Bad
Schema::create('ProjectFiles', function (Blueprint $table) {});  // Wrong case
Schema::create('project_file', function (Blueprint $table) {});  // Should be plural

Columns

// Good
$table->string('company_name');
$table->foreignId('client_id')->constrained();
$table->boolean('is_active')->default(true);
$table->timestamp('paid_at')->nullable();

// Bad
$table->string('companyName');    // Use snake_case
$table->foreignId('clientID');    // Use snake_case
$table->boolean('active');        // Add 'is_' prefix

Indexes

Files and Directories

PHP Files

Directory Structure

app/
├── Actions/              # Single-purpose action classes
├── Enums/                # PHP enums
├── Events/               # Event classes
├── Exceptions/           # Custom exceptions
├── Http/
│   ├── Controllers/
│   │   ├── Admin/        # Admin controllers
│   │   └── Portal/       # Client portal controllers
│   ├── Middleware/
│   └── Requests/         # Form request classes
├── Listeners/            # Event listeners
├── Mail/                 # Mailable classes
├── Models/               # Eloquent models
├── Notifications/        # Notification classes
├── Policies/             # Authorization policies
├── Providers/            # Service providers
└── Services/             # Service classes

Migrations

Routes

Route Names

// Good
Route::resource('clients', ClientController::class);
// Generates: clients.index, clients.create, clients.store, etc.

Route::prefix('admin')->name('admin.')->group(function () {
    Route::resource('clients', Admin\ClientController::class);
});
// Generates: admin.clients.index, admin.clients.show, etc.

// Bad
Route::get('/clients', [ClientController::class, 'index'])->name('getClients');
Route::get('/clients', [ClientController::class, 'index'])->name('client-list');

Route URIs

// Good
Route::get('/project-files', [ProjectFileController::class, 'index']);
Route::post('/invoices/{invoice}/mark-paid', [InvoiceController::class, 'markPaid']);

// Bad
Route::get('/projectFiles', ...);  // Use kebab-case
Route::get('/project_files', ...); // Use kebab-case

Configuration

Config Keys

// config/client_portal.php
return [
    'max_file_size' => 10 * 1024 * 1024,  // 10MB
    'default_role' => 'client',
    'invoices' => [
        'due_days' => 30,
        'reminder_days' => [7, 3, 1],
    ],
];

// Usage
config('client_portal.max_file_size');
config('client_portal.invoices.due_days');

Environment Variables

# Good
APP_NAME="Client Portal"
CLIENT_PORTAL_MAX_FILE_SIZE=10485760
MAIL_FROM_ADDRESS="noreply@example.com"

# Bad
appName="Client Portal"     # Wrong case
maxFileSize=10485760        # Wrong case, needs prefix

Views

Blade Files

resources/views/
├── admin/
│   ├── dashboard.blade.php
│   └── clients/
│       ├── index.blade.php
│       └── show.blade.php
├── portal/
│   └── dashboard.blade.php
├── components/
│   ├── invoice-card.blade.php
│   └── file-upload.blade.php
└── layouts/
    ├── app.blade.php
    └── guest.blade.php

Component Classes

// Good - Component class
namespace App\View\Components;
class InvoiceCard extends Component {}

// Usage in Blade
<x-invoice-card :invoice="$invoice" />

Tests

Test Files

// Good
class ClientManagementTest extends TestCase
{
    public function test_admin_can_create_client(): void
    {
        // ...
    }

    public function test_client_cannot_access_admin_dashboard(): void
    {
        // ...
    }
}

// Alternative with attributes (Pest-style in PHPUnit)
#[Test]
public function admin_can_create_client(): void
{
    // ...
}

Test Directory Structure

tests/
├── Feature/
│   ├── Admin/
│   │   └── ClientManagementTest.php
│   ├── Auth/
│   │   ├── LoginTest.php
│   │   └── RegistrationTest.php
│   └── Portal/
│       └── DashboardTest.php
└── Unit/
    ├── Models/
    │   └── InvoiceTest.php
    └── Services/
        └── InvoiceServiceTest.php

Quick Reference

Do's

• Use PascalCase for classes, traits, interfaces, enums
• Use camelCase for methods, variables, parameters
• Use snake_case for database tables, columns, config keys
• Use kebab-case for URLs, view files, CSS classes
• Use SCREAMING_SNAKE_CASE for constants and env variables
• Be consistent within a file and across the codebase

Don'ts

• Avoid abbreviations that aren't universally understood
• Avoid mixing naming conventions within the same category
• Avoid single-letter variable names (except in loops)
• Avoid Hungarian notation ($strName, $intCount)

Related Documentation

• Laravel Naming Conventions
• PSR-12: Extended Coding Style
• DOCUMENTATION_STANDARDS.md