yidas / codeigniter-rest
CodeIgniter 3 RESTful API Resource Base Controller
Installs: 11 948
Dependents: 2
Suggesters: 0
Security: 0
Stars: 81
Watchers: 10
Forks: 33
Open Issues: 1
Requires
- php: >=5.4.0
README
CodeIgniter RESTful API
CodeIgniter 3 RESTful API Resource Base Controller
This RESTful API extension is collected into yidas/codeigniter-pack which is a complete solution for Codeigniter framework.
Features
-
PSR-7 standardization
-
RESTful API implementation
-
Laravel Resource Controllers pattern like
OUTLINE
- Demonstration
- Requirements
- Installation
- Configuration
- Resource Controllers
- HTTP Request
- HTTP Response
- Reference
DEMONSTRATION
class ApiController extends yidas\rest\Controller { public function index() { return $this->response->json(['bar'=>'foo']); } }
Output with status 200 OK
:
{"bar":"foo"}
RESTful Create Callback
public function store($requestData=null) { $this->db->insert('mytable', $requestData); $id = $this->db->insert_id(); return $this->response->json(['id'=>$id], 201); }
Output with status 201 Created
:
{"id":1}
Packed Standard Format
try { throw new Exception("API forbidden", 403); } catch (\Exception $e) { // Pack data into a standard format $data = $this->pack(['bar'=>'foo'], $e->getCode(), $e->getMessage()); return $this->response->json($data, $e->getCode()); }
Output with status 403 Forbidden
:
{"code":403,"message":"API forbidden","data":{"bar":"foo"}}
REQUIREMENTS
This library requires the following:
- PHP 5.4.0+
- CodeIgniter 3.0.0+
INSTALLATION
Run Composer in your Codeigniter project under the folder \application
:
composer require yidas/codeigniter-rest
Check Codeigniter application/config/config.php
:
$config['composer_autoload'] = TRUE;
You could customize the vendor path into
$config['composer_autoload']
CONFIGURATION
- Create a controller to extend
yidas\rest\Controller
,
class Resource extends yidas\rest\Controller {}
- Add and implement action methods referring by Build Methods.
Then you could access RESTful API:
https://yourname.com/resource/api
https://yourname.com/resource/api/123
You could also use /ajax
instead of /api
if you like:
https://yourname.com/resource/ajax
https://yourname.com/resource/ajax/123
resource
is Controller name, if you don't want to have/api
or/ajax
in URI you could set Routes Setting as below.
Routes Setting
If you want to have a standard RESTful URI pattern that controller defines as a URI resource, for example:
https://yourname.com/resource
https://yourname.com/resource/123
You could add a pair of routes for this controller into \application\config\routes.php
to enable RESTful API url:
$route['resource_name'] = '[Controller]/route'; $route['resource_name/(:any)'] = '[Controller]/route/$1';
RESOURCE CONTROLLERS
The base RESTful API controller is yidas\rest\Controller
, the following table is the actions handled by resource controller, the action
refers to CI_Controller
's action name which you could override:
Without Routes Setting, the URI is like
/photos/api
&/photos/api/{photo}
.
Build Methods:
You could make a resource controller by referring the Template of Resource Controller.
The following RESTful controller methods could be add by your need. which each method refers to the action of Resource Controller table by default, and injects required arguments:
public function index() {} protected function store($requestData=null) {} protected function show($resourceID) {} protected function update($resourceID=null, $requestData=null) {} protected function delete($resourceID=null, $requestData=null) {}
$resourceID
(string) is the addressed identity of the resource from request
$requestData
(array) is the array input data parsed from request raw body, which supports data format of common content types. (Alternatively, usethis->request->getRawBody()
to get raw data)
Custom Routes & Methods
The default routes for mapping the same action methods of Resource Controller are below:
protected $routes = [ 'index' => 'index', 'store' => 'store', 'show' => 'show', 'update' => 'update', 'delete' => 'delete', ];
You could override it to define your own routes while creating a resource controller:
class ApiController extends yidas\rest\Controller { protected $routes = [ 'index' => 'find', 'store' => 'save', 'show' => 'display', 'update' => 'edit', 'delete' => 'destory', ]; }
After reseting routes, each RESTful method (key) would enter into specified controller action (value). For above example, while access /resources/api/
url with GET
method would enter into find()
action. However, the default route would enter into index()
action.
The keys refer to the actions of Resource Controller table, you must define all methods you need.
Behaviors
Resource Controller supports behaviors setting for each action, you could implement such as authentication for different permissions.
_setBehavior()
Set behavior to a action before route
protected boolean _setBehavior(string $action, callable $function)
Example:
class BaseRestController extends \yidas\rest\Controller { function __construct() { parent::__construct(); // Load your Auth library for verification $this->load->library('Auth'); $this->auth->verify('read'); // Set each action for own permission verification $this->_setBehavior('store', function() { $this->auth->verify('create'); }); $this->_setBehavior('update', function() { $this->auth->verify('update'); }); $this->_setBehavior('delete', function() { $this->auth->verify('delete'); }); } // ...
Usage
pack()
Pack array data into body format
You could override this method for your application standard.
protected array pack(array|mixed $data, integer $statusCode=200, string $message=null)
Example:
$data = $this->pack(['bar'=>'foo'], 403, 'Forbidden'); return $this->response->json($data, 403);
JSON Result:
{
"code": 403,
"message": "Forbidden",
"data": {
"bar": "foo"
}
}
HTTP REQUEST
The PSR-7 request component yidas\http\request
is preloaded into yidas\rest\Controller
, which provides input handler and HTTP Authentication. You could call it by $this->request
in controller class.
Usage
getRawBody()
Returns the raw HTTP request body
public string getRawBody()
Example:
// Request with `application/json` raw $data = json_decode($this->request->getRawBody);
getAuthCredentialsWithBasic()
Get Credentials with HTTP Basic Authentication
public array getAuthCredentialsWithBasic()
Example:
list($username, $password) = $this->request->getAuthCredentialsWithBasic();
getAuthCredentialsWithBearer()
Get Credentials with OAuth 2.0 Authorization Framework: Bearer Token Usage
public string getAuthCredentialsWithBearer()
Example:
$b64token = $this->request->getAuthCredentialsWithBearer();
HTTP RESPONSE
The PSR-7 response component yidas\http\response
is preloaded into yidas\rest\Controller
, which provides output handler and formatter. You could call it by $this->response
in controller class.
Usage
json()
JSON output shortcut
public void json(array|mixed $data, integer $statusCode=null)
Example:
$this->response->json(['bar'=>'foo'], 201);
setFormat()
Set Response Format into CI_Output
public self setFormat(string $format)
Example:
$this->response->setFormat(\yidas\http\Response::FORMAT_JSON);
setData()
Set Response Data into CI_Output
public self setData(mixed $data)
Example:
$this->response->setData(['foo'=>'bar']);
send()
Sends the response to the client.
public void send()
Example:
$this->response->send();
withAddedHeader()
Return an instance with the specified header appended with the given value.
public self withAddedHeader(string $name, string $value)
Example:
return $this->response ->withAddedHeader('Access-Control-Allow-Origin', '*') ->withAddedHeader('X-Frame-Options', 'deny') ->json(['bar'=>'foo']);