The engine is designed as a sort of "MVC" application to handle new requests by developing
your Controllers easily. All requests are handled by an interface, www/index.php by default,
in which you can define some options values to fit your needs or environment.
The default arguments used by the front controller (GET or POST) are:
ws: the chosen web-service ; this must be a classname of a controller,action: the action to execute from the web-service ; this must be a method of the controller called[action]Action(); default action isindex.
The response is a JSON table containing at least a status and a message entry:
{"status":0, "message":"Hello World !"}
$ curl -i 'http://mydomain.com/webservices/?action=helloworld'
HTTP/1.1 200 OK
Date: Thu, 11 Jul 2013 09:57:40 GMT
Connection: keep-alive
Cache-Control: max-age=0, private, must-revalidate
Content-Length: 40
Content-Type: application/json; charset=UTF-8
{"status":0,"message":"Hello World ;)"}
$ curl -i -d "name=Pierre" 'http://mydomain.com/webservices/?action=testPost'
HTTP/1.1 200 OK
Date: Thu, 11 Jul 2013 09:57:40 GMT
Connection: keep-alive
Cache-Control: max-age=0, private, must-revalidate
Content-Length: 41
Content-Type: application/json; charset=UTF-8
{"status":0,"message":"Hello Pierre ;)"}
The FrontController is designed to return a status code as an integer following these rules:
0: the default "no error at all" status,1: the "unexpected result" status, which means that no error happened but the result is not totally the one expected,2: the "request error" status, used for not found webservice or method, for bad arguments values etc,3: the "treatment error" status, which must be used when the treament has to stop for any reason,-1: the "internal server error" status, that is used by PHP errors and exceptions.
The WebServices\FrontController::create() method accepts a third argument to define a set
of customized options:
array(
// the HTTP accessible temporary files
'tmp_directory' => __DIR__.'/tmp',
// the HTTP NON-accessible temporary files, must be out of your document root
'var_directory' => __DIR__.'/../var',
// the log files, must be out of your document root (here in 'var/')
'log_directory' => __DIR__.'/../var/logs',
// enable full logging
'enable_logging' => true,
// enable the URL rewriting : "http://.../var/val" = "http://.../?var=val"
'enable_url_rewrite' => true,
// write your custom controllers here like "route => classname" pairs
// then you can call "http://.../?ws=route" to access them
'controllers_mapping' => array(
),
)The engine is designed to handle requests written with GET arguments like key=>value pairs
or full URL written as a list of key/value pairs.
For instance, these followings are equivalent:
$ curl -i 'http://mydomain.com/webservices/?ws=MyController&action=custom'
$ curl -i 'http://mydomain.com/webservices/ws/MyController/action/custom'
This URL rewriting feature can be disabled setting the enable_url_rewrite option on false.
By default, the engine will log any request received and some of the PHP work done from it.
The default path for log files is var/logs/ from the package root directory. This path can
be defined with option log_directory.
The logging feature can be disabled setting the enable_logging option on false.
To prepare a package based on the WebServices, you will need Composer installed on your machine, and then you just need to run:
~$ php path/to/composer.phar create-project atelierspierrot/webservices YOURDIR dev-master --no-dev
...
~$ vim YOURDIR/composer.json
// add an entry in the 'autoload' of composer.json to reference your namespace, i.e.
"autoload": { "psr-0": { "WebServices":"src", "MyNamespace":"src" } }
~$ php path/to/composer.phar dump-autoload YOURDIR
...
~$ vim YOURDIR/www/index.php
// adapt the interface options to fit your needs
// reference your controllers to have a shortcut access to them
Then, you just have to create your src/MyNamespace/ directory and put your controllers
in it.
That's it!
The only thing to do to write a new webservice is to create a new
PHP class extending the \WebServices\Controller\AbstractController abstract class. As
explained in previous section, you have to declare the actions of your controller by naming
them like dosomethingAction().
For instance, consider a custom "MyController" controller with methods "indexAction()" and "customAction()". You will call each of these actions with requests:
$ curl -i 'http://mydomain.com/webservices/?ws=MyController'
$ curl -i 'http://mydomain.com/webservices/?ws=MyController&action=custom'
Each controller can propose a "usage" string information defining the $usage_filepath property
on the absolute accessible path of a usage file. The content can be parsed by the
Markdown Extended parser if it is
named with a .md extension.
You can write your usage contents in PHP as in this case, the current configuration settings
are loaded as environment variables. The special variable $webservice_url is defined on the
current interface URL. To do so, you MUST use a final extension .php
(.md.php to use the Markdown parser).
The "usage" string is displayed fo each controller calling the usage action.
You can develop as many new controllers you want and build a shortcut to access them by
defining the controllers_mapping option table, which is constructed like shortcut => classname.
For instance, to access a controller defined in class MyNamespace\MyController, you can
write 'myctrl' => 'MyNamespace\MyController' and access it by URL http://.../?ws=myctrl.
As they are mandatory, you can use one of the temporary directories of the package in your developments (they must be accessible for Apache user as they may be created by it):
var/: the temporary config and logs directory, NOT HTTP accessible,www/tmp/: the temporary HTTP accessible files.
As the "WebServices" depends on them (they must be installed), you can use in your scripts all classes from the following third-party packages:
- the PHP Library of Les Ateliers Pierrot, see http://docs.ateliers-pierrot.fr/library/ for an inline documentation
- the PHP Patterns package of Les Ateliers Pierrot, see http://docs.ateliers-pierrot.fr/patterns/ for an inline documentation.
To install all PHP packages for development, just run:
~$ composer install --dev
A documentation can be generated with Sami running:
~$ php vendor/sami/sami/sami.php render sami.config.php
The latest version of this documentation is available online at http://docs.ateliers-pierrot.fr/webservices/.
WebServices Engine
Copyright (c) 2013-2016 Pierre Cassat and contributors
Licensed under the Apache 2.0 license.
Les Ateliers Pierrot - Paris, France