Download .zip |
Info | Example | View files (13) | Download .zip | Reputation | Support forum | Blog | Links |
Last Updated | Ratings | Unique User Downloads | Download Rankings | |||||
2016-02-20 (1 year ago) | Not enough user ratings | Total: 210 | All time: 7,943 This week: 644 |
Version | License | PHP version | Categories | |||
api-layer 1.0 | BSD License | 5.5 | PHP 5, Libraries, Web services |
Description | Author | |
This package can send requests to APILayer REST APIs. Recommendations Decode PDF, ODT, Word, DOC, DOCX, RTF |
This class package encapsulates the access to various APIs from apilayers (https://www.apilayer.com/#products).
ApiLayers currently provides the following apis :
ApiLayers products provide a REST api for using their services ; you usually have to issue GET queries to retrieve the information you need, then interpret the results provided in JSON format. However, some queries may return binary data (for example, requesting a screenshot of a web page whose url has been provided will return the generated PNG, JPEG or GIF image contents ; and converting html contents to PDF will return the PDF data, unless an error occurred). Note however that some query parameters require POST queries to be used.
This is why I chosed to encapsulate access to the ApiLayers apis, to provide some kind of uniform information retrieval.
Registering to apilayers is easy ; just go to the product page and chose the Sign up free option. Once registered, you will have the choice between up to four subscription plans. The first one is free, and allows you to test the corresponding API.
Note that you will have to register yourself for every product you want to test (ie, you will have to sign-up with your own email address and password for every product you want to use).
With the free subscription plan, some features may be disabled, and you will be authorized to issue a limited amount of queries per month, but it's generally enough for testing.
The following apilayers products are currently implemented by this class package :
You can have a look at the Examples directory for getting some samples on how to use each of these classes.
More will be coming soon...
The Examples directory in this package contains sample scripts to demonstrate the features implemented by the various classes implemented here. Feel free to have a look at them, I have designed them to be as simplest as possible.
I suggest that you have a look at some of the README files listed in the above paragraph before showing some interest in the ApiLayer package implementation.
Since ApiLayer provides many services, the apilayer package has been designed so that encapsulating new apis would be easy.
There is actually one base class, ApiLayer, that gathers all the behaviors needed to issue http queries and interpret results to/from the Apilayer website.
All the API encapsulation classes (ScreenshotLayer, MailboxLayer, etc.) inherit from this class. Their constructors provides a formal description of the parameters they expect, along with specific methods to perform the desired query (for example, the ScreenshotLayer class has a CapturePage method that returns the contents of a PNG, JPEG or GIF file representing a web page).
Using this design, derived classes that implement an ApiLayer encapsulation need only to focus on two aspects :
The following paragraphs describe how to define a new derived encapsulating class through its constructor, and which methods are made available to the caller and to the derived classes.
The constructor of the ApiLayer class has the following syntax :
parent::__construct ( $api_url, $access_key, $use_https = false, $parameters = [] ) ;
Note that, since the ApiLayer class is abstract, its constructor can only be called from within a derived class constructor.
The $api_url parameter must be specified by the derived class as the preferred entry point to the encapsulated ApiLayer api. This will be api.screenshotlayer.com/api/capture for the screenshotlayer api, apilayer.net/api/check for the mailboxlayer api, and so on (see the documentation on https://www.apilayer.com/#products for more information on the adequate url).
Note that the http:// or https:// scheme needs not to be specified, since its conditioned by the $use_https parameter.
Every ApiLayer api requires you to register first by giving a valid email address and a password. Once the registration process is over, an access key is generated for you (you can later change it by going to your dashboard).
This access key must be specified each time you need to instantiate an object derived from the ApiLayer class.
Set this parameter to true if you want to use secure http requests.
Note that no provision is made for verifying SSL certificates (the curl CURLOPT\_SSL\_VERIFYPEER option is set to false).
The $parameters array elements are associative arrays that allow a derived class to specify the definitions of the parameters used for building an ApiLayer query.
Each array item defines a parameter attribute and can contain the following entries :
Query parameter name, as it will appear on the query url.
This entry can be omitted if the 'url-parameter' is set to false.
The query parameters have a name (usually given by the ApiLayers api) but can also have aliases.
These name and aliases can differ from the real url parameter name specified in the name entry. For example, the access_key parameter has one alias, AccessKey. Thus, its value can be accessed either through :
$api -> access_key
or :
$api -> AccessKey
Look at the different documentations for a list of authorized property names for each ApiLayer encapsulation class.
The value of the 'property' entry can either be a string or an array of strings, if you want to specify more than one property name.
Specifies the property initial value. This entry is optional and will default to null.
When the 'url-parameter' entry is set to true (the default), the parameter will be included in the url query if its value is not null.
When true, the parameter value will be included in the final url. The default is true.
When true, the corresponding parameter is required. An exception will be thrown during the construction of the url query if its value has not been specified.
When true, the value cannot be set. This is used for already initialized entries, or for computed entries having a callback function.
Callback function to be used for getting/setting the parameter value.
The 'get' function must have the following signature :
string get_function ( $parameter ) ;
The 'set' function must have the following signature :
void set_function ( &$parameter, $value ) ;
The $parameter parameter is a reference to the parameter entry, as defined by the derived class constructor. $value is the value to be assigned to the property.
Specifies a callback function used to retrieve the parameter value when building the final query url. This may be regarded as some kind of computed value.
This is the case for example of the secret_key parameter, which is used in the screenshot and pdflayer apis ; you can set it like this :
$screenshot -> secret_key = 'my secret key' ;
where 'my secret key' is a secret key defined in your apilayers dashboard ; however, the value that will be specified to build the final url is the md5 hash of the url to be captured catenated with your secret key. This is why both the ScreenshotLayer and PdfLayer classes specify a queryget entry to dynamically build this value.
The type parameter specifies how the property value will be handled. This is a byte mask whose low-order bits specify a type value which can be any of the following constants :
The following additional flags can be specified :
The following bit flags may be specified for string parameter types :
When the parameter type is APILAYER\_PARAMETER\_KEYWORD, a 'keywords' entry must be specified in the parameter definition, as an array of associative or non-associative entries. Each entry indicates a possible authorized value on the query url.
Note that (input) parameter values are case-insensitive ; however, the output value (the one supplied in the http query) will always reflect the initial input case. For example :
'keywords' => [ 'jpg', 'png', 'gif' ]
will always yield to a final url value of 'png', 'gif' or 'jpg', even if you set the property value to 'JPG', 'PNG' or 'GIF'.
You can also specify aliases ; for example, if you want the input values 'jpeg', 'jpg' or 'jpe' to yield to the same output value 'jpg', simply specify :
'keywords' => [ 'jpg', 'jpeg' => 'jpg', 'jpe' => jpg' ]
The following properties are common to all derived classes :
Specifies the access key defined in your ApiLayer dashboard ; this property is set by the class constructor, but can also be redefined later.
Specifies whether secure http request should be used for accessing the api ; this property is set by the class constructor, but can also be redefined later.
After an http query execution, this property is set to the results of the executed query. This is an object having the following properties :
Status of the last executed query.
Error status of the last executed query. This property is null if the query successfully executed, otherwise it will contain the following properties, which are set by the result of the ApiLayer query and are documented on the Apilayers web site :
The Data property may handle the JSON result of an http query to ApiLayers. There are two exceptions to that : the ScreenshotLayer and PdfLayer classes, which will set the Data property to null (normally, it should be set to hold the image/pdf contents, but this has been abandoned to limit memory usage).
Contains the last execute http query, together with its parameters.
Note that the parameters requiring a POST request will not be listed here.
Contains the raw contents of the last http query issued. Note that you will not be able to see POST parameters here, only the http headers sent.
Contains the key http address for the corresponding ApiLayer api. This value must be set by derived classes when invoking their parent's constructor.
Contains the parameter definitions for the corresponding ApiLayer api. This value must be set by derived classes when invoking their parent's constructor.
The following methods are implemented by the ApiLayer abstract class :
Executes an ApiLayer query. If the $query parameter is not specified, the resulting query will be built using the chosen scheme (http or https), the api url and all the query parameters that have been set by assigning the corresponding property in the object.
The return value of this method depends on the query : it can be json data but could contain anything else. For example, capturing a screenshot will return the generated image contents ; converting html contents to PDF will return the pdf file contents.
This method is used internally by derived classes and has been made public for debugging purposes only.
Similarly, the $query parameter, which allows to specify a custom query, is available for debugging purposes only.
Derived classes can implement two methods (which are some kind of event handlers) :
Event handlers can call the SetError() protected method if an error condition is encountered.
Returns the http GET query that will execute the desired ApiLayer query. The returned value contains the http or https scheme, the layer api url and all the url parameters that have been set so far. The returned value will not return properties that have the APILAYER\_PARAMETER\_FLAG\_POST flag set.
This method is used internally by the Execute() method, and has been made public for debugging purposes only.
Casting the object to a string will also return the query ; thus, the following code :
$query = $screenshot -> GetQuery ( ) ;
is equivalent to :
$query = ( string ) $screenshot ;
Returns the url part of the apilayer query, including the http or https scheme.
This method is used internally by the Execute() method, and has been made public for debugging purposes only.
Returns the query parameters. Since some parameters need to be posted (such as the document_html parameter of the PdfLayer api), this method allows the caller to retrieve either the url GET parameters ($post = false) or the parameters to be submitted through a POST request ($post = true).
This method is used internally by the Execute() method, and has been made public for debugging purposes only.
The following protected methods are implemented by the ApiLayer abstract class and can be safely called by derived classes :
This method is called by the Execute() method to check the returned contents of the ApiLayer http query.
It will throw an exception in two cases :
Derived classes can implement further checkings.
Retrieves the value of a property defined by the $entry array, which specifies the property characteristics (as defined by the derived class when calling the ApiLayer constructor). It applies the following transformations :
Checks that parameters defined as needing a post request (ie, having the APILAYER\_PARAMETER\_FLAG\_POST parameter set) are present. The result will be true only if at least one non-empty property having this flag set has been found.
Allows derived classes to set an error condition in a way that mimics the errors returned by the ApiLayers various apis. The meaning of the parameters is the following :
Note that when an exception is thrown, the catching code can always rely on the value of the QueryResult and LastQuery properties.
Sets a property value (ie the 'value' entry of the specified $entry parameter) to $value, after applying the following transformations and checkings :
Sets the QueryResult property to an ApiLayerResult object, according to the information provided by the $result parameter, which can be one of the following :
Files |
File | Role | Description | ||
---|---|---|---|---|
Examples (3 files) | ||||
Sources (4 files) | ||||
LICENSE | Lic. | License file | ||
NOTICE | Data | A little disclaimer | ||
README.MAILBOXLAYER.md | Doc. | MailboxLayer class documentation | ||
README.md | Doc. | Main documentation | ||
README.PDFLAYER.md | Doc. | PdfLayer class documentation | ||
README.SCREENSHOTLAYER.md | Doc. | ScreenshotLayer class documentation |
Files | / | Examples |
File | Role | Description |
---|---|---|
get_mail.php | Example | Example script to demonstrate the use of the MailboxLayer api |
get_pdf.php | Example | Example to demonstrate the PdfLayer api |
get_screenshot.php | Example | Example to demonstrate the use of the ScreenshotLayer api |
Files | / | Sources |
File | Role | Description |
---|---|---|
ApiLayer.php | Class | Base class for all Apilayer services |
MailboxLayer.php | Class | Encapsulation of the MailboxLayer api |
PdfLayer.php | Class | Encapsulation of the PdfLayer api |
ScreenshotLayer.php | Class | Encapsulation of the ScreenshotLayer api |
Version Control | Unique User Downloads | Download Rankings | |||||||||||||||
0% |
|
|
Applications that use this package |
If you know an application of this package, send a message to the author to add a link here.