RESTful Resource Handling

• Resource Routes
  • Change the Controller Used
  • Change the Placeholder Used
  • Limit the Routes Made
• ResourceController
• Presenter Routes
  • Change the Controller Used
  • Change the Placeholder Used
  • Limit the Routes Made
• ResourcePresenter
• Presenter/Controller Comparison

Representational State Transfer (REST) is an architectural style for distributed applications, first described by Roy Fielding in his 2000 PhD dissertation, Architectural Styles and the Design of Network-based Software Architectures. That might be a bit of a dry read, and you might find Martin Fowler’s Richardson Maturity Model a gentler introduction.

REST has been interpreted, and mis-interpreted, in more ways than most software architectures, and it might be easier to say that the more of Roy Fielding’s principles that you embrace in an architecture, the most “RESTful” your application would be considered.

CodeIgniter makes it easy to create RESTful APIs for your resources, with its resource routes and ResourceController.

Resource Routes

You can quickly create a handful of RESTful routes for a single resource with the resource() method. This creates the five most common routes needed for full CRUD of a resource: create a new resource, update an existing one, list all of that resource, show a single resource, and delete a single resource. The first parameter is the resource name:

$routes->resource('photos');

// Equivalent to the following:
$routes->get('photos/new',             'Photos::new');
$routes->post('photos',                'Photos::create');
$routes->get('photos',                 'Photos::index');
$routes->get('photos/(:segment)',      'Photos::show/$1');
$routes->get('photos/(:segment)/edit', 'Photos::edit/$1');
$routes->put('photos/(:segment)',      'Photos::update/$1');
$routes->patch('photos/(:segment)',    'Photos::update/$1');
$routes->delete('photos/(:segment)',   'Photos::delete/$1');

The second parameter accepts an array of options that can be used to modify the routes that are generated. While these routes are geared toward API-usage, where more methods are allowed, you can pass in the ‘websafe’ option to have it generate update and delete methods that work with HTML forms:

$routes->resource('photos', ['websafe' => 1]);

// The following equivalent routes are created:
$routes->post('photos/(:segment)/delete', 'Photos::delete/$1');
$routes->post('photos/(:segment)',        'Photos::update/$1');

Change the Controller Used

You can specify the controller that should be used by passing in the controller option with the name of the controller that should be used:

$routes->resource('photos', ['controller' =>'App\Gallery']);

// Would create routes like:
$routes->get('photos', 'App\Gallery::index');

Change the Placeholder Used

By default, the segment placeholder is used when a resource ID is needed. You can change this by passing in the placeholder option with the new string to use:

$routes->resource('photos', ['placeholder' => '(:num)']);

// Generates routes like:
$routes->get('photos/(:num)', 'Photos::show/$1');

Limit the Routes Made

You can restrict the routes generated with the only option. This should be an array or comma separated list of method names that should be created. Only routes that match one of these methods will be created. The rest will be ignored:

$routes->resource('photos', ['only' => ['index', 'show']]);

Otherwise you can remove unused routes with the except option. This option run after only:

$routes->resource('photos', ['except' => 'new,edit']);

Valid methods are: index, show, create, update, new, edit and delete.

ResourceController

The ResourceController provides a convenient starting point for your RESTful API, with methods that correspond to the resource routes above.

Extend it, over-riding the modelName and format properties, and then implement those methods that you want handled.:

<?php namespace App\Controllers;

use CodeIgniter\RESTful\ResourceController;

class Photos extends ResourceController
{
    protected $modelName = 'App\Models\Photos';
    protected $format    = 'json';

    public function index()
    {
        return $this->respond($this->model->findAll());
    }

    // ...
}

The routing for this would be:

$routes->resource('photos');

Presenter Routes

You can quickly create a presentation controller which aligns with a resource controller, using the presenter() method. This creates routes for the controller methods that would return views for your resource, or process forms submitted from those views.

It is not needed, since the presentation can be handled with a conventional controller - it is a convenience. Its usage is similar to the resource routing:

$routes->presenter('photos');

// Equivalent to the following:
$routes->get('photos/new',                'Photos::new');
$routes->post('photos/create',            'Photos::create');
$routes->post('photos',                   'Photos::create');   // alias
$routes->get('photos',                    'Photos::index');
$routes->get('photos/show/(:segment)',    'Photos::show/$1');
$routes->get('photos/(:segment)',         'Photos::show/$1');  // alias
$routes->get('photos/edit/(:segment)',    'Photos::edit/$1');
$routes->post('photos/update/(:segment)', 'Photos::update/$1');
$routes->get('photos/remove/(:segment)',  'Photos::remove/$1');
$routes->post('photos/delete/(:segment)', 'Photos::update/$1');

You would not have routes for photos for both a resource and a presenter controller. You need to distinguish them, for instance:

$routes->resource('api/photo');
$routes->presenter('admin/photos');

The second parameter accepts an array of options that can be used to modify the routes that are generated.

Change the Controller Used

You can specify the controller that should be used by passing in the controller option with the name of the controller that should be used:

$routes->presenter('photos', ['controller' =>'App\Gallery']);

// Would create routes like:
$routes->get('photos', 'App\Gallery::index');

Change the Placeholder Used

By default, the segment placeholder is used when a resource ID is needed. You can change this by passing in the placeholder option with the new string to use:

$routes->presenter('photos', ['placeholder' => '(:num)']);

// Generates routes like:
$routes->get('photos/(:num)', 'Photos::show/$1');

Limit the Routes Made

You can restrict the routes generated with the only option. This should be an array or comma separated list of method names that should be created. Only routes that match one of these methods will be created. The rest will be ignored:

$routes->presenter('photos', ['only' => ['index', 'show']]);

Otherwise you can remove unused routes with the except option. This option run after only:

$routes->presenter('photos', ['except' => 'new,edit']);

Valid methods are: index, show, new, create, edit, update, remove and delete.

ResourcePresenter

The ResourcePresenter provides a convenient starting point for presenting views of your resource, and processing data from forms in those views, with methods that align to the resource routes above.

Extend it, over-riding the modelName property, and then implement those methods that you want handled.:

<?php namespace App\Controllers;

use CodeIgniter\RESTful\ResourcePresenter;

class Photos extends ResourcePresenter
{

    protected $modelName = 'App\Models\Photos';

    public function index()
    {
        return view('templates/list',$this->model->findAll());
    }

    // ...
}

The routing for this would be:

$routes->presenter('photos');

Presenter/Controller Comparison

This table presents a comparison of the default routes created by resource() and presenter() with their corresponding Controller functions.

Operation	Method	Controller Route	Presenter Route	Controller Function	Presenter Function
New	GET	photos/new	photos/new	new()	new()
Create	POST	photos	photos	create()	create()
Create (alias)	POST		photos/create		create()
List	GET	photos	photos	index()	index()
Show	GET	photos/(:segment)	photos/(:segment)	show($id = null)	show($id = null)
Show (alias)	GET		photos/show/(:segment)		show($id = null)
Edit	GET	photos/(:segment)/edit	photos/edit/(:segment)	edit($id = null)	edit($id = null)
Update	PUT/PATCH	photos/(:segment)		update($id = null)
Update (websafe)	POST	photos/(:segment)	photos/update/(:segment)	update($id = null)	update($id = null)
Remove	GET		photos/remove/(:segment)		remove($id = null)
Delete	DELETE	photos/(:segment)		delete($id = null)
Delete (websafe)	POST		photos/delete/(:segment)	delete($id = null)	delete($id = null)