Restler
1.0.0
upgraded from version 3 RC6 for latest PHP support
Restler is a simple and effective multi-format Web API Server written in PHP.
Just deal with your business logic in php, restler will take care of the REST!
@url GET my/custom/url/{param} PHPDoc commentsMost stable and recent version is at the master branch, previous versions are in the version branches such
as v4, v3, v2, and v1.
Version branch with the current version such as v5 is used for building up the next release. It's documentation may
not be updated frequently and thus reserved for the daring ones.
Feature branches such as features/html and features/router are purely for experimentation purpose to try out a
feature. They may be merged when ready.
Install this repository to try out the examples.
Make sure PHP 5.4 or above is available on your server. We recommended using the latest version for better performance.
Restler uses Composer to manage its dependencies. First, download a copy of composer.phar.
It can be kept in your project folder or ideally in usr/local/bin to use it globally for all your projects. If you are
on Windows, you can use the composer
windows installer instead.
You may install Restler by running the create project command in your terminal. Replace {projectName} with your actual project name. It will create a folder with that name and install Restler.
php composer.phar create-project luracast/restler {projectName}Note:-
If you do not want the additional formats and BDD tools you can include >
--no-devto enforce exclusion of dev packages.If you want to try the bleading edge v3 branch or any of the feature > branches include
3.x-devordev-features/htmlin the above command
After installing Composer, download the latest version of the Restler framework and extract its contents into a
directory on your server. Next, in the root of your Restler project, run the php composer.phar install
(or composer install) command to install all the framework's dependencies. This process requires Git to be installed
on the server to successfully complete the installation.
If you want to update the Restler framework, you may issue the
php composer.phar update command.
Note:- If you are not allowed to install composer and git on your server, you can install and run them on your development machine. The resulting files and folders can be uploaded and used on the server.
Ideally public folder should be mapped as your web root, It is optional, but recommended avoiding exposing unneeded files and folders.
Try the live examples in your localhost.
You may launch the PHP's built-in server with
composer servecommand.
Update the base_url specified in behat.yml and then try the following command
vendor/bin/behat
alternatively you can run
composer test
This will test the examples against the behaviors expected, for example
Feature: Testing CRUD Example
Scenario: Creating new Author with JSON
Given that I want to make a new "Author"
And his "name" is "Chris"
And his "email" is "[email protected]"
And the request is sent as JSON
When I request "/examples/_007_crud/authors"
Then the response status code should be 200
And the response should be JSON
And the response has a "id" property
All set, Happy RESTling! :)
We have two options to create your own restler api server
Most convenient option is using application templates such as Restler Application which has integrations with many packages to help us with the business logic as well. If you choose this option, select a branch in that repository and proceed with the instructions available there.
Create a project from scratch so that you have full control over every aspect of your application. If you choose this option, follow along with the steps below.
composer init and follow along to create composer.jsonrestler/framework and ^5 for the version constraint.composer require restler/framework:^5we are using
restler/frameworkinstead ofluracast/restlerto reduce the space required for the package. It is coming from https://github.com/Luracast/Restler-Framework it contains only the contents of src folder here.
Even when you are building from scratch, checking out the application templates will help with folder structure decisions and finding other useful packages.
Create your API classes with all needed public and protected methods
Create the gateway (public/index.php) as follows
<?php
require_once __DIR__.'/../vendor/autoload.php';
use LuracastRestlerRestler;
$r = new Restler();
$r->addAPIClass('YourApiClassNameHere'); // repeat for more
$r->handle(); //serve the responseEnable URL Rewriting
Make sure all the requests go to index.php by enabling URL Rewriting for your website
For example:-
If you are on Apache, you can use an .htaccess file such as
DirectoryIndex index.php
<IfModule mod_rewrite.c>
RewriteEngine On
RewriteRule ^$ index.php [QSA,L]
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-d
RewriteRule ^(.*)$ index.php [QSA,L]
</IfModule>
<IfModule mod_php5.c>
php_flag display_errors On
</IfModule>Note:- This requires
AllowOverrideto be set toAllinstead ofNonein thehttpd.conffile, and might require some tweaking on some server configurations. Refer to mod_rewrite documentation for more info.
If you are on Nginx, you have to make sure you set the server_name and pass the PHP scripts to fast cgi (PHP-FPM)
listening on 127.0.0.1:9000
server {
listen 80;
server_name api.luracast.com; //change it to match your server name
//... other stuff
location ~ .php$ {
root /var/www/html;
fastcgi_pass 127.0.0.1:9000;
fastcgi_index index.php;
fastcgi_param SCRIPT_FILENAME /var/www/html/$fastcgi_script_name;
include fastcgi_params;
}
//... other stuff
}
Note:- This requires PHP, PHP-FPM to be properly installed and configured. Refer to PHP FastCGI example for more info.
Fine tune to suit your needs
<?php
require_once __DIR__.'/../vendor/autoload.php';
use LuracastRestlerRestler;
use LuracastRestlerDefaults;
//set the defaults to match your requirements
Defaults::$throttle = 20; //time in milliseconds for bandwidth throttling
//setup restler
$r = new Restler();
$r->addAPIClass('YourApiClassNameHere'); // repeat for more
$r->addAPIClass('Explorer'); //from restler framework for API Explorer
$r->addFilterClass('RateLimit'); //Add Filters as needed
$r->handle(); //serve the responseExplore the api and try it out by openings explorer/index.html from the web root on your browser
Happy Exploring! :)
Note:- Using eAccelerator can make restler to fail as it removes the comments. More info can be found here
Restler supports annotations in the form of PHPDoc comments for API fine tuning
They are documented in detail under Annotations
In order to protect your api, authenticate and allow valid users
<?php
require_once '../restler.php';
use LuracastRestlerRestler;
$r = new Restler();
$r->addAPIClass('YourApiClassNameHere'); // repeat for more
$r->addAuthenticationClass('CustomAuth'); //Add Authentication classes as needed
$r->handle(); //serve the responseBy default Restler runs in debug mode more fine tuned for API developer, by showing detailed error messages and prettifying the api result to human readbale form
By turning on production mode you will gain some performance boost as it will cache the routes (comment parsing happens only once instead of every api call), few other files and avoid giving out debug information
<?php
require_once '../restler.php';
use LuracastRestlerRestler;
//setup restler
$r = new Restler(true); //turn on production mode by passing true.
//If you are using file based cache (the default) make sure cache folder is
//writable. when you make changes to your code make sure you delete the
// routes.php inside the cache folder
//...Note:- When production mode is set to
trueit always uses the cache and does not detect changes and new routes if any. Your continuous integration pipeline or your git hook should delete this file during the deployment process. Alternatively you can pass second parameter to restler constructor to refresh the cache when changes need to be applied.
composer serve command.composer test command after running the server
with composer serve in another window.$restler->addAPIClass("Luracast/Restler/Explorer", 'swagger') maps it to /swagger.Routes class improved to provide a findAll method to list all the routes for a specific version of the API excluding the specified paths and http methods.
The magic properties utilized by routes when found, ignoring actual properties. This is useful for Dynamic Model classes such as Eloquent.
Routes now allow @required and @properties to be arrays when the parameter is an object.
This helps us to pick and choose the properties for each api method differently.
Example {@properties property1,property2,property3} {@required property1,property2} makes an api to only look for
3 properties and 2 of them are required.
Optimized the Nav class. It now makes use of Routes::findAll(), along with Explorer class
Restler class has setBaseUrls method to set acceptable base urls that can be set using $_SERVER['HTTP_HOST'].
Read this article to understand why. This is useful
in the following cases when
Restler class now allows overriding the status code by setting $this->restler->responseCode from the api method.
Improved Forms class to send the embedded properties to emmet template. For example
/**
* {@id form1}
*
* @param string $name
* @param int $age
*/
Generates the following form
<form role="form" id="form1" method="POST" ...
because the emmet template has id in it (see below)
form[role=form id=$id# name=$name# method=$method# action=$action# enctype=$enctype#]
@param comments to set html attributes (for example id, accept etc) easily@class comment. Example:
- @class Validator {@holdException} makes the validator to hold the exceptions instead of throwing@property, @property-read, @property-write to support documenting the dynamic
properties.string[], DateTime[]Scope::$resolver property.String class to Text for PHP 7 support (String is a reserved keyword in php7)
