Manejo de recursos RESTful

La transferencia de estado representacional (REST) es un estilo arquitectónico para aplicaciones distribuidas, descritas por primera vez por Roy Fielding en su 2000 Tesis doctoral, «Estilos arquitectónicos y el diseño de arquitecturas de software basadas en red <https://www.ics.uci.edu/~fielding/pubs/dissertation/top.htm>`_. Puede que sea una lectura un poco seca, y es posible que encuentres el libro de Martin Fowler Modelo de madurez de Richardson<https://martinfowler.com/articles/richardsonMaturityModel.html> _ una introducción más suave.

REST ha sido interpretado, y malinterpretado, en más formas que la mayoría arquitecturas de software, y podría ser más fácil decir que cuanto más de los principios de Roy Fielding que se adoptan en una arquitectura, el La aplicación más «RESTful» sería considerada.

Higgs facilita la creación de API RESTful para sus recursos, con sus rutas de recursos y ResourceController.

Rutas de recursos 

Puede crear rápidamente un puñado de rutas RESTful para un único recurso con el método resource(). Este crea las cinco rutas más comunes necesarias para el CRUD completo de un recurso: crear un nuevo recurso, actualizar uno existente, enumere todo ese recurso, muestre un solo recurso y elimine un solo recurso. El primer parámetro es el recurso. nombre:

<?php

$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');

Nota

The ordering above is for clarity, whereas the actual order the routes are created in, in RouteCollection, ensures proper route resolution

Importante

The routes are matched in the order they are specified, so if you have a resource photos above a get “photos/poll” the show action’s route for the resource line will be matched before the get line. To fix this, move the get line above the resource line so that it is matched first.

El segundo parámetro acepta una serie de opciones que se pueden utilizar para modificar las rutas que se generan. Mientras estos las rutas están orientadas al uso de API, donde se permiten más métodos, puede pasar la opción websafe para tenerla generar métodos de actualización y eliminación que funcionen con formularios HTML:

<?php

$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');

Cambiar el controlador utilizado 

Puede especificar el controlador que debe usarse pasando la opción controller con el nombre de El controlador que se debe utilizar:

<?php

$routes->resource('photos', ['controller' => 'Gallery']);
// Would create routes like:
$routes->get('photos', '\App\Controllers\Gallery::index');

<?php

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

<?php

use App\Controllers\Gallery;

$routes->resource('photos', ['namespace' => '', 'controller' => Gallery::class]);
// Would create routes like:
$routes->get('photos', '\App\Controllers\Gallery::index');

Véase también controladores-espacio de nombres.

Cambiar el marcador de posición utilizado 

De forma predeterminada, el marcador de posición (:segmento) se utiliza cuando se necesita un ID de recurso. Puedes cambiar esto pasando en la opción placeholder con la nueva cadena a usar:

<?php

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

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

Limitar las rutas realizadas 

Puedes restringir las rutas generadas con la opción solo. Esto debería ser una matriz o una lista separada por comas de nombres de métodos que deberían ser creado. Sólo se crearán rutas que coincidan con uno de estos métodos. El resto será ignorado:

<?php

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

De lo contrario, puede eliminar rutas no utilizadas con la opción excepto. Esto también debería ser una matriz o una lista separada por comas de nombres de métodos. Esta opción se ejecuta después de solo:

<?php

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

Los métodos válidos son: index, show, create, update, new, edit y delete.

Controlador de recursos 

El ResourceController proporciona un punto de partida conveniente para su API RESTful, con métodos que corresponden a las rutas de recursos anteriores.

Extiéndalo, anulando las propiedades modelName y format, y luego implemente los métodos que desea manejar:

<?php

namespace App\Controllers;

use Higgs\RESTful\ResourceController;

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

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

    // ...
}

La ruta para esto sería:

<?php

$routes->resource('photos');

Rutas del presentador 

Puede crear rápidamente un controlador de presentación que alinee con un controlador de recursos, usando el método presenter(). Este crea rutas para los métodos del controlador que devolverían vistas para su recurso o procesar formularios enviados desde esas vistas.

No es necesario, ya que la presentación se puede manejar con un controlador convencional: es una comodidad. Su uso es similar al enrutamiento de recursos:

<?php

$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::delete/$1');

Nota

The ordering above is for clarity, whereas the actual order the routes are created in, in RouteCollection, ensures proper route resolution

No tendría rutas para «fotos» tanto para un recurso como para un presentador controlador. Es necesario distinguirlos, por ejemplo:

<?php

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

El segundo parámetro acepta una serie de opciones que se pueden utilizar para modificar las rutas que se generan.

Cambiar el controlador utilizado 

Puede especificar el controlador que debe usarse pasando la opción controller con el nombre de El controlador que se debe utilizar:

<?php

$routes->presenter('photos', ['controller' => 'Gallery']);
// Would create routes like:
$routes->get('photos', '\App\Controllers\Gallery::index');

<?php

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

<?php

use App\Controllers\Gallery;

$routes->presenter('photos', ['namespace' => '', 'controller' => Gallery::class]);
// Would create routes like:
$routes->get('photos', '\App\Controllers\Gallery::index');

Véase también controladores-espacio de nombres.

Cambiar el marcador de posición utilizado 

De forma predeterminada, el marcador de posición (:segmento) se utiliza cuando se necesita un ID de recurso. Puedes cambiar esto pasando en la opción placeholder con la nueva cadena a usar:

<?php

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

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

Limitar las rutas realizadas 

Puedes restringir las rutas generadas con la opción solo. Esto debería ser una matriz o una lista separada por comas de nombres de métodos que deberían ser creado. Sólo se crearán rutas que coincidan con uno de estos métodos. El resto será ignorado:

<?php

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

De lo contrario, puede eliminar rutas no utilizadas con la opción excepto. Esto también debería ser una matriz o una lista separada por comas de nombres de métodos. Esta opción se ejecuta después de solo:

<?php

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

Los métodos válidos son: index, show, new, create, edit, update, remove y ``delete`. `.

Presentador de recursos 

ResourcePresenter proporciona un punto de partida conveniente para presentar vistas de su recurso y procesar datos de formularios en esas vistas, con métodos que se alinean con las rutas de recursos anteriores.

Extiéndalo, anulando la propiedad modelName y luego implemente los métodos que desea manejar:

<?php

namespace App\Controllers;

use Higgs\RESTful\ResourcePresenter;

class Photos extends ResourcePresenter
{
    protected $modelName = 'App\Models\Photos';

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

    // ...
}

La ruta para esto sería:

<?php

$routes->presenter('photos');

Comparación presentador/controlador 

Esta tabla presenta una comparación de las rutas predeterminadas creadas por resource() y presentador() con sus correspondientes funciones de Controlador.