Download the PHP package triquanta/libizi without Composer
On this page you can find all versions of the php package triquanta/libizi. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.
Informations about the package libizi
About
This is a PHP library for communicating with the izi.TRAVEL API.
Requirements
All requirements are resolved through Composer. After
installing composer, go to the project root and run composer install
to
install all dependencies.
Usage & features
Client
The library provides a client to communicate with the API. It handles all requests, errors, and converts all API output to classes PHP objects. Three preparatory steps must be taken before API calls can be made:
- Create a
\GuzzleHttp\Client
instance. - Create a
\Triquanta\IziTravel\Client\*RequestHandler
instance and inject the Guzzle client from step 1 and an API key. - Create a
Triquanta\IziTravel\Client\Client
instance and inject the request handler from step 2.
Now you can call any of the methods on the client from step 3 and get the API's output as (arrays of) classed PHP objects.
Data types
Because working with raw, untyped data in PHP is bad developer experience (DX),
every data type in the API has corresponding interfaces and classes in this
library. All classes come with factory methods
(\Triquanta\IziTravel\DataType\FactoryInterface
)
to instantiate an object based on the API's raw JSON response.
Events
Symfony EventDispatcher
is used for dispatching system events. Event names and classes are documented in
\Triquanta\IziTravel\Event\IziTravelEvents
.
Development
Versioning
All development takes places on the master
branch. Versions are released based
on Semantic Versioning.
Supporting a new API endpoint
Each API endpoint is represented by a request class in
\Triquanta\IziTravel\Request
and it must implement
\Triquanta\IziTravel\Request\RequestInterface
.
It can optionally implement any of the other
interfaces in the same
namespace and use any of the
traits to quickly build a
configurable request. Any object data returned by an endpoint must be converted
to classed objects before being returned by
\Triquanta\IziTravel\Request\RequestInterface::execute()
implementations.
The existing data types in Triquanta\IziTravel\DataType
can
be re-used.
\Triquanta\IziTravel\ClientInterface
is a
convenience layer for easily requesting data from different endpoints in the
same code. When adding a new request class, a method for it must be added to
this interface as well.
Example
A new endpoint foo
was added for retrieving Foo content by UUID.
Additionally the content can be returned in a specific language and format
(full/compact). The first step is to create a class that implements the correct
interface (which is inherited from
RequestBase
):
Now we have the basis for any request. Because this endpoint supports forms and is multilingual, we can easily add support for this by implementing two interfaces and using two traits:
The class will now feature additional methods and properties for setting and storing the form, language, and UUID of the content that should be returned by the API.
Now we are able to configure instances of this class, we need to use this configuration to execute the actual request and get the JSON from the response:
The request is made to the endpoint, and we pass along the values of the three endpoint parameters (form, language, UUID). As you can see, we use the traits' properties for this.
What remains is the conversion of this JSON to a classed object. We don't have to worry about NULL values, because the API returns HTTP error response in case the requested content is not available. That means by the time this code is executed, we can be sure the response is positive.
All data object classes implement
FactoryInterface
and must be
instantiated by using the interface's methods. By calling ::createFromJson()
,
we also validate the JSON against the available schemas.
The request class in its entirety now looks like this:
For convenience we also add a factory method to
ClientInterface
. Because the language and
UUID are the only required request parameters, they are also the only parameters
to the factory method. Any remaining optional parameters can be configured using
the setters on the returned request object.
The method's implementation in Client
would look
like this:
The newly supported endpoint can then be used:
PSR-2
All code must be written according the PSR-2 guidelines.
PSR-4
Class and interface autoloading is done using PSR-4 using the following namespace mappings:
\Triquanta\IziTravel
maps to ./src\Triquanta\IziTravel\Tests
maps to ./tests
Testing
The library comes with PHPUnit-based tests that can be
run using ./phpunit.xml.dist. All tests are located in
\Triquanta\IziTravel\Tests
.
Some tests require configuration. Copy
./test_configuration.example.yml to
./test_configuration.local.yml
and fill out the values.
All versions of libizi with dependencies
iziteq/izi-api-schemes Version dev-master#081a82788a81df5749da40bfc0e80e8c7e5dd9e8
justinrainbow/json-schema Version ~1.4
php Version ~5.4
symfony/event-dispatcher Version ~2.7