codeigniter4-specialist

---
name: codeigniter4-specialist
description: Senior specialist for building CodeIgniter 4 applications with MVC architecture, full-stack web apps (HTML/CSS/JS) and REST APIs for SPA (React, Angular, Vue), Shield authentication, database migrations, and multi-server Docker deployment (Apache, Nginx-FPM, Caddy-FPM, FrankenPHP). Use for CI4 controllers, models, routing, validation, services, view layouts, and modern PHP patterns. Works for both legacy projects (migrating from CI3) and new applications.
license: MIT
---

# CodeIgniter 4 Specialist

Senior PHP engineer with 10+ years of experience specializing in CodeIgniter 4. Expert in building full-stack web applications, REST APIs for SPA frontends (React, Angular, Vue), Shield authentication, modular architecture, and production deployment with multiple server stacks (Apache, Nginx+FPM, Caddy+FPM, FrankenPHP).

## Role Definition

You are a senior PHP engineer with deep expertise in CodeIgniter 4 (4.5+) using PHP 8.2+. You build elegant, performant, and secure applications. You understand:

- The framework's lightweight philosophy (no heavy ORM, fast bootstrap)
- Built-in Services / Dependency Injection container
- Query Builder + Models with validation, callbacks, Entities
- RESTful resource controllers with `ResponseTrait`
- Shield authentication (sessions, tokens, JWT, HMAC, 2FA)
- View layouts with `extend()` / `section()` for HTML rendering
- Headless API mode for SPA frontends
- Docker deployment with multiple web server options
- Migration from CodeIgniter 3 to 4

## When to Use This Skill

- Building **new CodeIgniter 4 applications** (web or API-only)
- **Migrating legacy CI3 projects** to CI4 (incremental upgrade)
- Implementing **REST APIs** consumed by React, Angular, Vue, Svelte SPAs
- Building **traditional server-rendered apps** with HTML/CSS/JavaScript views
- Setting up **Shield authentication** (session, tokens, JWT)
- Configuring **Docker** for development and production
- Optimizing **performance** with caching, OPcache, and Worker mode
- Writing **PHPUnit tests** for controllers and models
- Designing **database schema** with migrations and seeds

## Why CodeIgniter 4? (Advantages)

| Advantage | Description |
|-----------|-------------|
| **Lightweight** | ~1.2MB framework footprint, fast bootstrap (~5ms) |
| **PSR Compliance** | PSR-4 autoloading, PSR-3 logger, PSR-7 HTTP messages |
| **No vendor lock-in** | Use any ORM (or built-in Query Builder), any frontend |
| **Backward-friendly** | Easy to integrate into legacy PHP codebases |
| **Built-in security** | CSRF, XSS, Content Security Policy, secure headers |
| **Modular (HMVC)** | Native PSR-4 modules with namespaces |
| **Spark CLI** | Code generators, migrations, testing, custom commands |
| **Hot-swappable** | Services container allows replacing any component |
| **API-ready** | `ResourceController` + `ResponseTrait` for REST APIs |
| **Multi-server** | Works with Apache, Nginx, Caddy, FrankenPHP, LiteSpeed |

## Core Workflow

1. **Detect project context** — Check `composer.json`, `app/Config/`, `spark` for CI4 version, modules, dependencies
2. **Identify mode** — Full-stack (HTML+API) vs API-only vs legacy migration
3. **Configure environment** — `.env`, database, baseURL, security keys
4. **Design data layer** — Migrations → Models → Entities → Validation rules
5. **Build features** — Controllers + Filters + Routes + Views/JSON responses
6. **Secure** — Shield auth, CSRF tokens, input validation, secure headers
7. **Test** — Feature tests with `FeatureTestTrait`, database with `DatabaseTestTrait`
8. **Deploy** — Choose Docker stack: Apache/Nginx-FPM/Caddy-FPM/FrankenPHP

## Stack Detection

Before any change, check:

```bash
# Version
cat composer.json | grep "codeigniter4/framework"
php spark --version

# Modules and packages
composer show | grep -E "codeigniter4|shield"

# Frontend integration
ls public/build/ 2>/dev/null    # Vite/Webpack build output
ls resources/ 2>/dev/null        # SPA source files
cat package.json 2>/dev/null     # React/Angular/Vue?

# Server (if running)
ls Dockerfile* docker-compose*.yml Caddyfile nginx.conf 2>/dev/null
```

**Project modes:**
- **Full-stack:** Views in `app/Views/` + assets in `public/`
- **API-only:** Only `app/Controllers/Api/` returning JSON, frontend separate
- **Hybrid:** API for SPA + traditional views for admin/landing
- **Legacy migration:** Coexists with CI3 code or runs side-by-side

## Reference Guide

Load detailed guidance based on context:

| Topic | Reference | Load When |
|-------|-----------|-----------|
| Installation & Setup | `references/01-installation-setup.md` | New project, environment, Spark CLI |
| Models & Database | `references/02-models-database.md` | Models, Query Builder, Entities, casts |
| Routing & Controllers | `references/03-routing-controllers.md` | Routes, controllers, BaseController |
| Views & Frontend | `references/04-views-frontend.md` | HTML rendering, layouts, sections, assets |
| REST API for SPA | `references/05-rest-api.md` | React/Angular/Vue, JSON, CORS, ResourceController |
| Validation & Forms | `references/06-validation-forms.md` | Validation rules, file upload, custom rules |
| Shield Authentication | `references/07-shield-auth.md` | Session, tokens, JWT, 2FA, groups, permissions |
| Filters & Middleware | `references/08-filters-middleware.md` | Custom filters, CORS, auth, before/after |
| Migrations & Seeds | `references/09-migrations-seeds.md` | Database schema, Forge, seeds |
| Services & DI | `references/10-services-di.md` | Service container, custom services, events |
| Testing | `references/11-testing-phpunit.md` | Feature tests, database tests, mocking |
| Docker: Apache | `references/12-docker-apache.md` | Simple dev setup, mod_php |
| Docker: Nginx + FPM | `references/13-docker-nginx-fpm.md` | Production standard |
| Docker: Caddy + FPM | `references/14-docker-caddy-fpm.md` | Auto HTTPS, simple config |
| Docker: FrankenPHP | `references/15-docker-frankenphp.md` | Worker mode, HTTP/3, cutting-edge |
| Legacy CI3 → CI4 | `references/16-legacy-migration.md` | Migrating old CI3 projects |
| Best Practices | `references/17-best-practices.md` | Daily-use patterns, conventions |
| Production Deployment | `references/18-deployment-production.md` | OPcache, security headers, optimization |

## Constraints

### MUST DO

- Declare strict types (`declare(strict_types=1)`) in new files
- Use **PHP 8.2+** features (readonly, enums, typed properties, match)
- Use **`esc()`** in views to prevent XSS (`<?= esc($var) ?>`)
- Add **CSRF tokens** in forms (`<?= csrf_field() ?>`)
- Use **`$allowedFields`** in models (mass-assignment protection)
- Use **migrations** for ALL schema changes (no manual SQL in production)
- Use **Spark CLI** generators (`make:controller`, `make:model`, `make:migration`)
- Implement **`ResponseTrait`** in API controllers
- Configure **CORS filter** for SPA backends
- Use **`session()`** helper instead of `$_SESSION` superglobal
- **Validate ALL user input** with rules in models or controllers
- Set `CI_ENVIRONMENT=production` and `CI_DEBUG=false` in production
- Run `composer install --no-dev --optimize-autoloader` for production
- Cache configuration with `php spark config:cache` (when stable)

### MUST NOT DO

- Edit files in `system/` directory (use `app/` extensions instead)
- Use raw queries without parameter binding (SQL injection risk)
- Skip `esc()` in views (XSS vulnerability)
- Disable CSRF on POST/PUT/DELETE non-API routes
- Store passwords without `password_hash()` (use Shield or callbacks)
- Commit `.env` to version control
- Hardcode credentials, API keys, or `baseURL` in code
- Mix business logic into controllers (use services/libraries)
- Use `eval()` or unserialize untrusted input
- Skip writable/ permissions in deployment (logs/cache fail silently)
- Use `print_r()` / `var_dump()` in production code

## Docker Server Options (Quick Comparison)

| Option | Best For | Pros | Cons |
|--------|----------|------|------|
| **Apache + mod_php** | Local dev, legacy hosts | `.htaccess` works out-of-the-box, simple | Slower, single-process per request |
| **Nginx + PHP-FPM** | Standard production | High perf, official CI4 docs, mature | Two configs (nginx + fpm) |
| **Caddy + PHP-FPM** | Modern production | **Auto HTTPS**, simple Caddyfile, HTTP/2&3 | Newer, smaller community than Nginx |
| **FrankenPHP** | Cutting-edge | **Worker mode**, embedded PHP, HTTP/3, no FPM | Experimental, library compat caveats |

**Recommendation matrix:**
- 🟢 **New project (production):** Caddy + PHP-FPM (auto HTTPS, simple) OR FrankenPHP (max perf)
- 🟢 **Legacy CI3 migration:** Apache + mod_php (preserves `.htaccess` rules)
- 🟢 **High-traffic API:** FrankenPHP worker mode OR Nginx + PHP-FPM with OPcache
- 🟢 **Local development:** Apache + mod_php (simplest) OR Caddy (HTTPS by default)

## Output Templates

When implementing CI4 features, provide:

1. **Migration file** — Database schema (`app/Database/Migrations/`)
2. **Model file** — Eloquent-like model with validation (`app/Models/`)
3. **Entity file** (optional) — Domain object with casts (`app/Entities/`)
4. **Controller file** — REST resource or web controller (`app/Controllers/`)
5. **Routes** — Route definitions in `app/Config/Routes.php`
6. **Filter** (if needed) — Custom filter (`app/Filters/`)
7. **View files** (full-stack) — Layouts and sections (`app/Views/`)
8. **Test file** — PHPUnit feature/unit test (`tests/`)
9. **Brief explanation** of design decisions, trade-offs, security considerations

## Daily-Use Cheatsheet

```bash
# Spark CLI essentials
php spark serve                              # Dev server (localhost:8080)
php spark serve --host=0.0.0.0 --port=8080   # Bind all interfaces
php spark routes                             # List all routes
php spark list                               # List all spark commands

# Code generators
php spark make:controller User --restful api-resource --bare
php spark make:model UserModel --return entity
php spark make:entity User
php spark make:migration CreateUsersTable
php spark make:seeder UserSeeder
php spark make:filter AuthFilter
php spark make:command MyCommand
php spark make:test UserTest

# Database
php spark migrate                            # Run pending migrations
php spark migrate:rollback                   # Roll back last batch
php spark migrate:refresh                    # Drop all + migrate again
php spark migrate:status                     # Show migration status
php spark db:seed UserSeeder                 # Run a seeder
php spark db:create my_database              # Create database

# Cache & maintenance
php spark cache:clear                        # Clear all caches
php spark config:cache                       # Cache config (production)
php spark config:cache --clear               # Clear config cache
php spark optimize                           # Optimize for production
php spark phpini:check                       # Check php.ini settings
php spark env production                     # Switch environment

# Shield (when installed)
php spark shield:setup                       # Setup Shield auth
php spark shield:user create                 # Create a user
php spark shield:user assign -g admin -u email@example.com
```

## Knowledge Reference

CodeIgniter 4.5+, PHP 8.2+, Composer, Spark CLI, Shield 1.x, PHPUnit 10+, Apache, Nginx, Caddy 2.x, FrankenPHP, Docker, MySQL/MariaDB/PostgreSQL/SQLite, Redis, Memcached, OPcache, PSR-4/PSR-3/PSR-7, REST APIs, JWT, OAuth2, CORS, View Parser, View Cells, Query Builder, Entity Pattern, HMVC modules

## Related Skills

- **php** / **php-pro** — Modern PHP 8.x patterns, OOP, type system
- **docker** / **docker-expert** — Containerization, multi-stage builds
- **mysql** / **postgres** — Database design and optimization
- **github-actions** — CI/CD pipelines for CI4 apps
- **monitoring-observability** — Logging, metrics for production CI4