CodeIgniter 4 Routing

When to use

• The user wants to attach a before/after filter such as auth or CSRF to specific CodeIgniter routes or groups.
• The user wants to map URLs to controller actions in CodeIgniter 4 by declaring routes in Config/Routes.php.
• The user needs to group CodeIgniter routes under a shared URL prefix, namespace, or filter set.

When NOT to use

• Do not apply this skill to CodeIgniter 3 $route[] array config; CI4 uses a fluent RouteCollection API.
• Do not use this skill to write the controller action body itself; routing only maps a URL to a handler.

Core guidance

• Prefer explicit routes over auto-routing — Define routes explicitly with $routes->get('/users/(:num)', 'Users::show/$1') and keep auto-routing disabled unless a throwaway prototype needs it.
• Bind routes to the specific HTTP verb — Use the verb-specific method ($routes->post(...), ->put(...), ->delete(...)) rather than $routes->add(...), so each URL only matches its intended method.

Quick recipe

1. Add the filter to Config\Filters::$aliases, e.g. 'auth' => \App\Filters\AuthFilter::class, so routes can reference it by name. (verify: The alias resolves without a "filter not found" error)
2. Wrap the admin routes in $routes->group('admin', ['filter' => 'auth'], function ($r) { ... }) so every route in the group runs the filter. (verify: An unauthenticated request to any admin route is rejected by the filter)
3. Inside the group, declare $r->get('users/(:num)', 'Users::show/$1') and $r->post('users', 'Users::create') and name them with the as option. (verify: A GET to a numeric id reaches Users::show and route_to() builds the URL)

Best practices

• Wrap related routes in `$routes->group('admin', ['filter' => 'auth'], function ($r) { ..
• Give routes a name via the as option and build URLs with route_to('name', $id) instead of hardcoding path strings across views and controllers
• Constrain dynamic segments with placeholders like (:num), (:alpha), or (:segment) and pass them to the action with $1, $2 in order

Anti-patterns

See references/anti-patterns.md.

Common mistakes

1. Auto-routing exposes every public method — With auto-routing enabled, every public controller method is reachable at a guessable URL. Fix: Disable auto-routing (setAutoRoute(false)) and declare only the routes you intend to expose.
2. Filter alias must be registered in Filters config — Referencing a filter by alias in a route fails silently if the alias is not registered in Config\Filters. Fix: Register the alias in Config\Filters::$aliases before using it in a route or group.
3. A broad route shadows more specific ones — Routes are matched top-down, so a greedy (:any) route declared first swallows later specific routes. Fix: Declare specific routes before catch-all patterns and keep (:any) last.

Version notes

• CI4 replaced the CI3 route array with RouteCollection — CodeIgniter 4 replaced the CI3 $route[] config array with a fluent $routes RouteCollection API and route groups.

Security

• Not applicable — no I/O, auth, or untrusted input.

Testing

• Activation and decision behavior are verified in eval/scenarios/codeigniter/routing.yaml.

Additional resources

• references/anti-patterns.md
• references/core.md
• references/examples.md
• references/pitfalls.md
• references/recipes.md
• references/version-differences.md

Knowledge graph

Related: codeigniter/controllers