APIx, RESTful services for PHP 
, (*1)
APIx is a (micro-)framework to build RESTful Web services. It will run alognside your existing framework/application with minimum fuss., (*2)
Some of its features:, (*3)
- Supports many data inputs such as GET/POST parameters, XML, JSON, CSV, ...
- Provides various output representation such as XML, JSONP, HTML, PHP, ...
- Provides on-demand resources documention, using GET /help or 'OPTIONS'.
- Uses annotations to document and set service behaviours.
- Handles most HTTP methods, including PUT, DELETE, HEAD, OPTIONS and PATCH (TRACE to some extend).
- Bundle with many plugins and adapters for Authentification and ACL, caching...
-
Follows the standards such as rfc2616, rfc2617,
rfc2388, rfc2854, rfc4627, rfc4329,
rfc2046, rfc3676, rfc3023, etc...
- Provides method-override usign X-HTTP-Method-Override (Google recommendation) and/or using a query-param (customisable).
- Supports content negotiation (which can also be overriden).
- Take advantages of network caches -- supports HEAD test.
- Available as a standalone PHAR file, or via Composer or as a PEAR package.
- Continuous integration against PHP 5.x, and 7.x.
- Read the documentation!
Todo:
* Self-generated API resources testing.
* Add support for WSDL 2.0 / WADL.
* Eventually SOAP (and XML_RPC) bridging., (*4)
Feel free to comment, send pull requests and patches..., (*5)
Basic usage
<?php
require 'apix.phar';
// Instantiate the server (using the default config)
$api = new Apix\Server;
// Create a GET handler $name is required
$api->onRead('/hello/:name', function($name) {
return array('Hello ' . $name);
});
$api->run();
Another example using annotations., (*6)
// $type and $stuff are required parameters.
// $optional is not mandatory.
$api->onRead('/search/:type/with/:stuff/:optional',
/**
* Search for things by type that have stuff.
*
* @param string $type A type of thing to search upon
* @param string $stuff One or many stuff to filter against
* @param string $optional An optional field
* @return array
* @api_auth groups=clients,employes,admins users=franck,jon
* @api_cache ttl=12mins tags=searches,indexes
*/
function($type, $stuff, $optional = null) {
// some logic
return $results;
}
);
$api->run();
Advanced usage
Routing
A route defines the path to a resource, once matched the corresponding resource's controller and dedicated handlers are invoked., (*7)
Any returned value emanating from a resource's controller, generally an associative array, will become the main subject of the response., (*8)
Essentially, a route is made of:, (*9)
- A route controller that corresponds to a HTTP header method:
onCreate() -> POST | onModify() -> PATCH
onRead() -> GET | onHelp() -> OPTIONS
onUpdate() -> PUT | onTest() -> HEAD
onDelete() -> DELETE | onTrace() -> TRACE
- A route path corresponding to a Request-URI.
- It may represent a specific and static resource entity, such as:
/search/france/paris
* It may also be _dynamic_, and may include one or many variables indicated by a colon `:`, such as:
<pre>/search/:country/:city</pre>
Controller definitions
A resource controller may be declared as either:, (*10)
- a public method from some user defined classes,
- a closure/lambda function, defined at runtime (Sinatra style).
It will use:, (*11)
-
variable name to inherit values from the route's path,
e.g. $name inherited from /category/:name., (*12)
-
type hinting to inject any of the current scope Apix's objects,
e.g. Request, Response, etc..., (*13)
See Apix's own Documentation for what's available., (*14)
Here is an example showing these in context:, (*15)
$api->onRead('/category/:name', function(Request $request, $name) {
// retrieve a named param
$page = (int) $request->getParam('page');
// retrieve the body params, parsed from XML, JSON, ...
$params = $request->getBodyParams();
...
return $list_defs;
});
Configuration
Check the inline comments in the config.dist.php file shipped with the distribution., (*16)
Bootstrap
To boostrap an Apix server, add the required file and create an instance of the
Apix\Server., (*17)
A dedicated configuration file can be injected to an Apix server:, (*18)
<?php
require 'apix.phar';
$api = new Apix\Server(require 'my_config.php');
$api->run();
PHAR Console
Apix PHAR distribution contains a built-in console. Try invoking the api.phar file on the command line as follow:, (*19)
$ php apix.phar --help
Web server configuration
Use one of the vhost file provided within the distribution and follow the
relevant instructions provided in the comments to set your web server environement., (*20)
TODO: Add ngynx and lighttpd files to the distrib., (*21)
Annotations
Annotations can be used to define many aspects of a resource entity., (*22)
Here is a self explanatory example:, (*23)
<?php
$api->onRead('/download/:app/version/:version',
/**
* Retrieve the named sotfware
* Anyone can use this resource entity to download apps. If no
* version is specified the latest revision will be returned.
*
* @param string $app The name of the app
* @param string $version The version number.
* @return array A response array.
*
* @api_auth groups=public
* @api_cache ttl=1week tags=downloads
*/
function($app, $version=null) {
// ...
return array(
$app => 'the version string of software.'
);
}
);
$api->onCreate('/upload/:software',
/**
* Upload a new software
* Admin users use this resource entity to upload new software.
*
* @param Request $request The Server Request object.
* @param string $software
* @return array A response array.
*
* @api_auth groups=admin users=franck
* @api_cache purge=downloads
*/
function(Request $request, $software) {
// ...
}
);
$api->run();
Installation
Apix requires PHP 5.3 or later., (*24)
-
Phar file (recommended), (*25)
-
If you are creating a component that relies on Apix locally:, (*26)
- either update your
composer.json file:
{
"require": {
"apix/apix": "0.3.*"
}
}
- or update your
package.xml file as follow:
<dependencies>
<required>
<package>
<name>apix_server</name>
<channel>pear.ouarz.net</channel>
<min>1.0.0</min>
<max>1.999.9999</max>
</package>
</required>
</dependencies>
- For a system-wide installation using PEAR:
sudo pear channel-discover pear.ouarz.net
sudo pear install --alldeps ouarz/apix
For more details see pear.ouarz.net., (*27)
Testing
To run the unit test suite simply run phpunit from within the main dir., (*28)
Integration and functional tests are also available in the src/tests., (*29)
License
APIx is licensed under the New BSD license -- see the LICENSE.txt for the full license details., (*30)
_|_| _|_| _| _| _|
_| _| _| _| _| _|
_| _| _| _| _| _|_|
_|_|_|_| _|_|_| _| _|_| _|_|
_| _| _| _| _| _|
_| _| _| _| _| _|
Wallogit.com
