This packages provides platform for writing RESTFul APIs in PHP
RESTful APIs are modern way of designing an web application , this approach provides the UI Dresigners complete freedom of their design and improvement
RESTFul APIs also give a way to secure the web resources in more elegant way
This package provides a platform for creating such RESTFul APIs in PHP
- Annotated APIs
- can be used with any frameworks
- copy
resources/.htaccess
andresources/index.php
to the root of the composer package - enable apache
rewrite
module - add
AllowOveride All
to composer root directory in apache's configuration - Service Class must implement
PhpPlatform\RESTFul\RESTService
- annotate service classes and methods with
@Path
to specify the path to which the the perticular class::method provides the service - configure routes as mentioned in the Configuration section below
- All service methods must return
PhpPlatform\RESTFul\HTTPResponse
Can be applied on service class or method , this denotes url path to reach that service-method
Can be applied only on service method , denotes what http verb this method is capable of serving.
A service method can have more than on of these Annotations
If a service method has @Path
annotation and has no HTTP methods , @GET
is applied by default
Cab be applied only on service method, specifies the data type of the request body
deserializers use this annnotation to deserialize the http request body into a php data. refer deserilizers section to configure multiple deserializers
Enables service method to have recaptcha authenticated.
Considered when recaptcha.enable
configuration is set to true
NOTE :
service request should send the recaptcha response as http header Php-Platform-Recaptcha-Response
Can be applied on service class or method
Forces Origin Header to be present in Request
This Annotation forces CORS on a service, see CORS
section of this document for more information
This section explains the configuration for this package which can be configured using config.xml
Differrent type of data needs to be serialized in differrent formats based on the Accept Header in the request
So differrent serializing implementations can be configured as follows
"serializers":{
"array":{
"application/json":"PhpPlatform\\RESTFul\\Serialization\\JsonToArraySerialization"
},
"SimpleXMLElement":{
"application/xml":"PhpPlatform\\RESTFul\\Serialization\\XmlToSimpleXMLElementSerialization"
}
},
Serializer class must implement PhpPlatform\RESTFul\Serialization\Serialize
interface
The data in the http request must be converted into a php represenation So differrent deserializing implementations can be configured as follows
"deserializers":{
"application/json":{
"array":"PhpPlatform\\RESTFul\\Serialization\\JsonToArraySerialization"
},
"application/xml":{
"SimpleXMLElement":"PhpPlatform\\RESTFul\\Serialization\\XmlToSimpleXMLElementSerialization"
}
},
Deserializer class must implement PhpPlatform\RESTFul\Serialization\Deserialize
interface
The PHP type to which the data should be converted needs to be specified at an annotation for the service as follows
/**
* @Consumes array
* @Path my-service
*/
function myService(){}
routes is the static map of url pattern to service class and methods.
routes can be updated manually or generated based on the annotations by running
$ ./vendor/bin/build-restful
routes is organized as a tree , where each node contains the class and method name of the service available for that url path
web services for these url patterns will be configured as follows
GET /user/all :- MyService\User::getAllUsers
POST /user/create :- MyService\User::createUser
GET /user/{id} :- MyService\User::getUser
"routes" : {
"children" : {
"user" : {
"children" : {
"all" : {
"methods" : {
"GET" : {
"class" : "MyService\\User",
"method" : "getAllUsers"
}
}
},
"create" : {
"methods" : {
"POST" : {
"class" : "MyService\\User",
"method" : "createUser"
}
}
},
"*" : {
"methods" : {
"GET" : {
"class" : "MyService\\User",
"method" : "getUser"
}
}
}
}
}
}
}
NOTE :
The parameters in the path are represented as * in the config , in the above example {id} is represented as *
Name of the params does not map to the name of the service method arguments , but they map to the position
recaptcha configurations enable services to require reCaptcha authentication
"recaptcha":{
"enable":true,
"secret":""
}
set enable
to true
to enable services to have recaptcha
set the value of secret
provided from google recaptcha
CORS configurations enables CORS (Cross Origin Resource Sharing) authentication
"CORS":{
"AllowOrigins":[
],
"AllowMethods":[
],
"AllowHeaders":[
],
"AllowCredentials":false,
"MaxAge":1000
}
Details of these can be found in https://developer.mozilla.org/en-US/docs/Web/HTTP/Access_control_CORS
CORS configurations can be set specific for a Service using Annotations.
For example to allow a https://specific.example.com
to a specific service
/**
* ...
* @CORS.AllowOrigins https://specific.example.com
*/
function mySpecificService(){}
-
Access-Control-Allow-Origin This header is set to
origin
header in the request only if thatorigin
is listed inCORS.AllowOrigins
configuration -
Access-Control-Allow-Methods Comma seperated Methods configured in
CORS.AllowMethods
-
Access-Control-Allow-Headers Comma seperated Headers configured in
CORS.AllowHeaders
-
Access-Control-Allow-Credentials True/False configured in
CORS.AllowCredentials
-
Access-Control-Max-Age number of seconds configured in
CORS.MaxAge
-
Access-Control-Exposed-Headers Comma separated names of headers explicitely set in HTTPResponse object from the service