CodeIgniter

CodeIgniter 4.x rules and best practices for Cursor

# CodeIgniter 4 — Clean Code Skill

> Expert guidance for writing readable, maintainable, and testable CodeIgniter 4 / PHP 8.1+ code.

---

## Core Philosophy

- **Readable first**: Code is read far more than it is written. Optimize for the next developer.
- **Small, focused units**: Every class, method, and function does one thing only (SRP).
- **Explicit over implicit**: Avoid magic. Make intent visible through naming and structure.
- **No premature optimization**: Write clear code first; optimize only when profiling justifies it.
- **Fail loudly**: Prefer exceptions over silent failures. Never swallow errors.

---

## PHP Standards

- Always declare `declare(strict_types=1);` at the top of every file.
- Use PHP 8.1+ features: `readonly` properties, enums, named arguments, fibers, intersection types.
- Follow PSR-12 for code style.
- Use typed properties, typed parameters, and explicit return types on **every** method — including `void`.
- Never use `mixed` unless absolutely unavoidable; document why when you do.
- Prefer `readonly` classes and properties for value objects and DTOs.
- Use named arguments when calling functions with multiple parameters to improve clarity.

```php
// Bad
$user = new User('John', 28, true);

// Good
$user = new User(name: 'John', age: 28, isActive: true);
```

---

## Naming Rules

> The most important clean code rule.

- **Classes**: PascalCase, noun or noun phrase — `UserRepository`, `CreateOrderService`, `PaymentGatewayInterface`.
- **Methods**: camelCase, verb or verb phrase — `findById()`, `createOrder()`, `isEmailTaken()`.
- **Variables**: camelCase, meaningful nouns — `$activeUsers`, `$orderTotal`. Never `$data`, `$arr`, `$temp`, `$x`.
- **Booleans**: prefix with `is`, `has`, `can`, `should` — `$isActive`, `$hasPermission`, `$canRefund`.
- **Constants / Enums**: UPPER_SNAKE for constants, PascalCase for enum cases.
- **No abbreviations**: write `$userIdentifier`, not `$uid`. Write `getUserByEmail()`, not `getUsrByEml()`.
- **Length rule**: if a name needs a comment to explain it, rename it instead.

```php
// Bad
$d = $u->getData(); // get user data

// Good
$userProfile = $user->getProfile();
```

---

## Clean Code Rules

### Functions and Methods

- **Maximum 20 lines** per method. If it's longer, extract.
- **Maximum 3 parameters**. If you need more, introduce a DTO or value object.
- **One level of abstraction per method**: don't mix high-level logic with low-level implementation.
- **No boolean flag parameters** — they indicate a method does two things.
- **No output arguments** — functions should return values, not modify passed references.
- **Command Query Separation (CQS)**: a method either changes state (command) or returns data (query), never both.

```php
// Bad — boolean flag, does two things
public function getUsers(bool $includeInactive): array { ... }

// Good — two explicit, clear methods
public function getActiveUsers(): array { ... }
public function getAllUsers(): array { ... }
```

### Classes

- **Single Responsibility**: one reason to change per class.
- Mark all classes `final` unless designed for extension.
- Use `readonly` for value objects and DTOs.
- Keep classes under **200 lines**. Longer classes are doing too much.
- Declare properties explicitly with types; never rely on dynamic property assignment.
- No public mutable properties — expose state through methods.

### Comments

- **Never comment what the code does** — write code that explains itself.
- Use comments only to explain **why**, not **what**.
- Prefer descriptive method extraction over inline comments.
- PHPDoc blocks for public API methods; skip them for obvious private methods.

```php
// Bad
// Loop through users and send email
foreach ($users as $user) { ... }

// Good — the method name IS the comment
$this->notifyUsersOfUpcomingExpiry($users);
```

---

## Architecture

### Directory Structure

```
app/
├── Controllers/
│   └── Api/V1/
├── DTO/               ← Input/output data shapes
├── Enums/             ← PHP 8.1 enums
├── Exceptions/        ← Domain-specific exceptions
├── Filters/           ← Middleware equivalents
├── Interfaces/        ← Contracts for services and repos
├── Models/            ← CI4 Models (DB layer only)
├── Repositories/      ← Data access abstraction
├── Services/          ← Business logic
└── ValueObjects/      ← Immutable domain primitives
```

### Layers and Responsibilities

#### Controllers — HTTP only. No business logic.

- Validate the HTTP request.
- Call one service method.
- Return the HTTP response.
- Must be `final`.

```php
final class UsersController extends ResourceController
{
    public function __construct(
        private readonly UserService $userService
    ) {}

    public function show(int $id): ResponseInterface
    {
        $user = $this->userService->findById($id);
        return $this->respond($user->toArray());
    }
}
```

#### Services — Business logic only. No HTTP, no SQL.

- Orchestrate domain operations.
- Call repositories, not models directly.
- Must be `final` and `readonly`.
- Throw domain exceptions on failure.

```php
final class UserService
{
    public function __construct(
        private readonly UserRepositoryInterface $userRepository,
        private readonly MailerInterface $mailer
    ) {}

    public function register(RegisterUserDTO $dto): User
    {
        if ($this->userRepository->existsByEmail($dto->email)) {
            throw new EmailAlreadyTakenException($dto->email);
        }

        $user = $this->userRepository->save(User::fromDTO($dto));
        $this->mailer->sendWelcome($user);

        return $user;
    }
}
```

#### Repositories — Data access only. No business logic.

- Always program to an interface.
- Return domain objects or collections, never raw arrays from DB.
- Encapsulate all query logic; no Query Builder outside the repository.

```php
interface UserRepositoryInterface
{
    public function findById(int $id): User;
    public function existsByEmail(string $email): bool;
    public function save(User $user): User;
}
```

#### DTOs — Data transfer only. Immutable.

```php
readonly class RegisterUserDTO
{
    public function __construct(
        public string $name,
        public string $email,
        public string $password,
    ) {}

    public static function fromRequest(IncomingRequest $request): self
    {
        return new self(
            name: $request->getVar('name'),
            email: $request->getVar('email'),
            password: $request->getVar('password'),
        );
    }
}
```

#### Value Objects — Immutable domain primitives with self-validation.

```php
readonly class Email
{
    public function __construct(public readonly string $value)
    {
        if (!filter_var($value, FILTER_VALIDATE_EMAIL)) {
            throw new InvalidEmailException($value);
        }
    }

    public function equals(Email $other): bool
    {
        return $this->value === $other->value;
    }
}
```

#### Enums — Replace magic strings and integers.

```php
enum OrderStatus: string
{
    case Pending   = 'pending';
    case Confirmed = 'confirmed';
    case Shipped   = 'shipped';
    case Cancelled = 'cancelled';

    public function canTransitionTo(self $next): bool
    {
        return match($this) {
            self::Pending   => $next === self::Confirmed || $next === self::Cancelled,
            self::Confirmed => $next === self::Shipped   || $next === self::Cancelled,
            default         => false,
        };
    }
}
```

---

## Error Handling

- **Never return null to signal failure** — throw a named exception.
- Create domain-specific exceptions under `app/Exceptions/`.
- Name exceptions after what happened: `UserNotFoundException`, `InsufficientStockException`.
- Never catch `\Exception` generically unless at the top-level handler.
- Log at the boundary (controller / exception handler), not deep in services.

```php
// Bad
public function findById(int $id): ?User
{
    return $this->db->find($id); // null means "not found" — ambiguous
}

// Good
public function findById(int $id): User
{
    $record = $this->db->find($id);

    if ($record === null) {
        throw new UserNotFoundException($id);
    }

    return User::fromRecord($record);
}
```

---

## Validation

- Always validate at the HTTP boundary — never deep inside services.
- Use CodeIgniter's Validation service or a dedicated `FormRequest`-style class.
- Keep validation rules on the DTO or a dedicated `*Rules` class, not inline in the controller.

```php
final class RegisterUserRules
{
    public static function rules(): array
    {
        return [
            'name'     => 'required|min_length[2]|max_length[100]',
            'email'    => 'required|valid_email|is_unique[users.email]',
            'password' => 'required|min_length[8]',
        ];
    }

    public static function messages(): array
    {
        return [
            'email' => ['is_unique' => 'This email is already registered.'],
        ];
    }
}
```

---

## CodeIgniter 4 Specifics

- Register services in `app/Config/Services.php` with explicit type hints.
- Use Filters (`app/Filters/`) for auth, rate limiting, CORS — never put this logic in controllers.
- Use `$db->transStart()` / `$db->transComplete()` wrapped in try-catch for all multi-step writes.
- Use CodeIgniter Shield for authentication; never hand-roll auth.
- Use `cache()` helper with explicit TTL and tagged cache keys for invalidation.
- Prefix all CLI commands with `spark`; keep them in `app/Commands/`.
- Never call `model()` global helper inside services — inject the repository.

---

## Testing Rules

- Every service class must have a unit test.
- Every controller endpoint must have a feature test.
- Test method names: `test_it_throws_when_email_is_already_taken()`.
- Prefer fakes and stubs over mocks when possible.
- No test should touch the real database — use transactions or an in-memory SQLite DB.
- Keep tests under 30 lines; extract helpers to `setUp()` or factory methods.

---

## What to Always Avoid

| Avoid | Use instead |
|---|---|
| `$data`, `$result`, `$arr` | Descriptive names |
| `mixed` return types | Explicit types or generics |
| Raw SQL in controllers | Repository methods |
| `null` as error signal | Named exceptions |
| God classes (500+ lines) | Split by responsibility |
| Boolean flag parameters | Two separate methods |
| Comments explaining *what* | Self-documenting method names |
| Magic numbers/strings | Enums or named constants |
| `model()` global in services | Constructor injection |
| Silent `catch` blocks | Log and rethrow or handle explicitly |

---

## Dependencies

- PHP 8.1+
- CodeIgniter 4.x
- Composer for dependency management
- `codeigniter4/shield` for authentication
- PHPUnit for testing