You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
A fully RESTful server implementation for CodeIgniter using one library, one
7
-
config file and one controller.
5
+
A fully RESTful server implementation for CodeIgniter using one library, one config file and one controller.
8
6
9
7
## Requirements
10
8
11
-
1. PHP 7.2 or greater
12
-
2. CodeIgniter 3.1.10+
13
-
14
-
_Note: for 1.7.x support download v2.2 from Downloads tab_
15
-
16
-
## Important Update on 4.0.0
9
+
- PHP 7.2 or greater
10
+
- CodeIgniter 3.1.11+
17
11
18
-
Please note that version 4.0.0 is in the works, and is considered a breaking change (per SemVer). As CI 3.1.0 now has native support for Composer, this library will be moving to be composer based.
12
+
## Installation
19
13
20
-
Take a look at the "development" branch to see what's up.
14
+
```sh
15
+
composer require chriskacerguis/ci-restserver
16
+
```
21
17
22
-
## Installation & loading
18
+
## Usage
23
19
24
20
CodeIgniter Rest Server is available on [Packagist](https://packagist.org/packages/chriskacerguis/codeigniter-restserver) (using semantic versioning), and installation via composer is the recommended way to install Codeigniter Rest Server. Just add this line to your `composer.json` file:
When your controller extends from `REST_Controller`, the method names will be appended with the HTTP method used to access the request. If you're making an HTTP `GET` call to `/books`, for instance, it would call a `Books#index_get()` method.
39
-
40
-
This allows you to implement a RESTful interface easily:
41
-
42
-
```php
43
-
use Restserver\Libraries\REST_Controller;
44
-
45
-
class Books extends CI_Controller
46
-
{
47
-
use REST_Controller {
48
-
REST_Controller::__construct as private __resTraitConstruct;
49
-
}
50
-
public function index_get()
51
-
{
52
-
// Display all books
53
-
}
54
-
55
-
public function index_post()
56
-
{
57
-
// Create a new book
58
-
}
59
-
}
60
-
```
61
-
62
-
`REST_Controller` also supports `PUT` and `DELETE` methods, allowing you to support a truly RESTful interface.
63
-
64
-
65
-
Accessing parameters is also easy. Simply use the name of the HTTP verb as a method:
66
-
67
-
```php
68
-
$this->get('blah'); // GET param
69
-
$this->post('blah'); // POST param
70
-
$this->put('blah'); // PUT param
71
-
```
72
-
73
-
The HTTP spec for DELETE requests precludes the use of parameters. For delete requests, you can add items to the URL
74
-
75
-
```php
76
-
public function index_delete($id)
77
-
{
78
-
$this->response([
79
-
'returned from delete:' => $id,
80
-
]);
81
-
}
82
-
```
83
-
84
-
If query parameters are passed via the URL, regardless of whether it's a GET request, can be obtained by the query method:
85
-
86
-
```php
87
-
$this->query('blah'); // Query param
88
-
```
89
-
90
-
## Content Types
91
-
92
-
`REST_Controller` supports a bunch of different request/response formats, including XML, JSON and serialised PHP. By default, the class will check the URL and look for a format either as an extension or as a separate segment.
93
-
94
-
This means your URLs can look like this:
95
-
```
96
-
http://example.com/books.json
97
-
http://example.com/books?format=json
98
-
```
99
-
100
-
This can be flaky with URI segments, so the recommend approach is using the HTTP `Accept` header:
This will automatically return an `HTTP 200 OK` response. You can specify the status code in the second parameter:
32
+
Step 1: Add this to your controller (should be before any of your code)
122
33
123
34
```php
124
-
public function index_post()
125
-
{
126
-
// ...create new book
127
-
$this->response($book, 201); // Send an HTTP 201 Created
128
-
}
35
+
use chriskacerguis\RestServer\RestController;
129
36
```
130
37
131
-
If you don't specify a response code, and the data you respond with `== FALSE` (an empty array or string, for instance), the response code will automatically be set to `404 Not Found`:
38
+
Step 2: Extend your controller
132
39
133
40
```php
134
-
$this->response([]); // HTTP 404 Not Found
41
+
class Example extends RestController
135
42
```
136
43
137
-
## Configuration
138
-
139
-
You can overwrite all default configurations by creating a rest.php file in your config folder with your configs.
140
-
All given configurations will overwrite the default ones.
141
-
142
-
## Language
143
-
144
-
You can overwrite all default language files. Just add a rest_controller_lang.php to your language and overwrite the what you want.
145
-
146
-
147
-
## Multilingual Support
44
+
## Basic GET example
148
45
149
-
If your application uses language files to support multiple locales, `REST_Controller` will automatically parse the HTTP `Accept-Language` header and provide the language(s) in your actions. This information can be found in the `$this->response->lang` object:
This class also provides rudimentary support for HTTP basic authentication and/or the securer HTTP digest access authentication.
171
-
172
-
You can enable basic authentication by setting the `$config['rest_auth']` to `'basic'`. The `$config['rest_valid_logins']` directive can then be used to set the usernames and passwords able to log in to your system. The class will automatically send all the correct headers to trigger the authentication dialogue:
Enabling digest auth is similarly easy. Configure your desired logins in the config file like above, and set `$config['rest_auth']` to `'digest'`. The class will automatically send out the headers to enable digest auth.
179
-
180
-
If you're tying this library into an AJAX endpoint where clients authenticate using PHP sessions then you may not like either of the digest nor basic authentication methods. In that case, you can tell the REST Library what PHP session variable to check for. If the variable exists, then the user is authorized. It will be up to your application to set that variable. You can define the variable in ``$config['auth_source']``. Then tell the library to use a php session variable by setting ``$config['rest_auth']`` to ``session``.
181
-
182
-
All three methods of authentication can be secured further by using an IP white-list. If you enable `$config['rest_ip_whitelist_enabled']` in your config file, you can then set a list of allowed IPs.
183
-
184
-
Any client connecting to your API will be checked against the white-listed IP array. If they're on the list, they'll be allowed access. If not, sorry, no can do hombre. The whitelist is a comma-separated string:
Your localhost IPs (`127.0.0.1` and `0.0.0.0`) are allowed by default.
191
-
192
-
## API Keys
193
-
194
-
In addition to the authentication methods above, the `REST_Controller` class also supports the use of API keys. Enabling API keys is easy. Turn it on in your **config/rest.php** file:
195
-
196
-
```php
197
-
$config['rest_enable_keys'] = TRUE;
198
-
```
199
-
200
-
You'll need to create a new database table to store and access the keys. `REST_Controller` will automatically assume you have a table that looks like this:
201
-
202
-
```sql
203
-
CREATETABLE `keys` (
204
-
`id`INT(11) NOT NULL AUTO_INCREMENT,
205
-
`key`VARCHAR(40) NOT NULL,
206
-
`level`INT(2) NOT NULL,
207
-
`ignore_limits`TINYINT(1) NOT NULL DEFAULT '0',
208
-
`date_created`INT(11) NOT NULL,
209
-
PRIMARY KEY (`id`)
210
-
) ENGINE=InnoDB DEFAULT CHARSET=utf8;
211
-
```
212
-
213
-
The class will look for an HTTP header with the API key on each request. An invalid or missing API key will result in an `HTTP 403 Forbidden`.
214
-
215
-
By default, the HTTP will be `X-API-KEY`. This can be configured in **config/rest.php**.
216
-
217
-
```bash
218
-
$ curl -X POST -H "X-API-KEY: some_key_here" http://example.com/books
219
-
```
220
-
## Profiling
221
-
Codeigniter Profiler feature has been added to the library, so that you can use the power of CI profiler in your project just by setting config parameter to enable profile through out your application
222
-
Turn it on in your **config/config.php** file:
223
-
224
-
```php
225
-
TRUE to turn profile ON, FALSE to turn it off
226
-
$config['enable_profiling'] = FALSE;
227
-
```
228
-
Also you need to enable `hooks` in your config.php that looks like this
229
-
```php
230
-
$config['enable_hooks'] = TRUE;
231
-
```
232
-
Also you can refer to **config/config.php.sample**
233
-
234
-
## Other Documentation / Tutorials
235
-
236
-
*[NetTuts: Working with RESTful Services in CodeIgniter](http://net.tutsplus.com/tutorials/php/working-with-restful-services-in-codeigniter-2/)
237
-
238
-
## Contributions
239
-
240
-
This project was originally written by Phil Sturgeon, however his involvement has shifted
241
-
as he is no longer using it. As of 2013/11/20 further development and support will be done by Chris Kacerguis.
242
-
243
-
Pull Requests are the best way to fix bugs or add features. I know loads of you use this, so please
244
-
contribute if you have improvements to be made and I'll keep releasing versions over time.
0 commit comments