README

Easy to use library which takes advantage of the PHP7 annotations library.

Installation

Using composer is quite simple, just run the following command:

$ composer require thomas-squall/php-easy-api

Before starting

Please remember that in order to work you should make sure that every endpoint you call the resolver snippet should be called too. I've attached an htaccess-example that could help. If you got any doubt please open an issue here.

Usage Example

Client

Let's assume we've got the following class:

<?php

/**
 * Class Mailchimp.
 * [\PHPEasyAPI\Client]
 */
class Mailchimp
{
    /**
     * [\PHPEasyAPI\Enrichment\Endpoint(method = "GET", url = "https://{$dataCenter}.api.mailchimp.com/3.0/lists/")]
     * [\PHPEasyAPI\Enrichment\User(username = "{$username}", password = "{$apiKey}")]
     */
    public $getLists;

    public $dataCenter;
    public $username;
    public $apiKey;
}

This is a basic implementation to call the lists/ mailchimp endpoint.

PS: Note that {$dataCenter}, {$username} and {$password} special strings are used. This special strings will evaluate with the class corresponding field value.

Now if we want to proceed and make the call we just need to do:

$mailchimp = new Mailchimp();
$mailchimp->dataCenter = '<YourDatacenter>';
$mailchimp->username = '<YourUsername>';
$mailchimp->apiKey = '<YourAPIKey>';

$resolver = new \PHPEasyAPI\Resolver();
$resolver->makeRequest($mailchimp, 'getLists');

print_r($mailchimp->getLists);

Let's analyze:

1. We instantiated a Mailchimp object.
2. We filled the needed values for the call.
3. We instantiated a \PHPEasyAPI\Resolver object.
4. We called the makeRequest method of the resolver passing the Mailchimp object (which is a API Client as per annotations) and the name of the field containing the Endpoint annotation.
5. We printed the value of the field containing the endpoint of the annotation.

PS: Note that the result will be put inside the field itself.

Server

Let's assume we've got the following class:

<?php

/**
 * Class Listener.
 * [\PHPEasyAPI\Server("user")] // 'user' is the endpoint
 */
class Listener
{
    /**
     * @param \PHPEasyAPI\Request $request
     * @return string
     * [\PHPEasyAPI\Enrichment\Endpoint(method = "GET", url = ":userId/getList/:listId")]
     */
    public function getList($request)
    {
        $userId = $request["userId"];
        $listId = $request["listId"];
        $request->send200("List $listId of user $userId");
    }
}

And we want to listen for incoming calls at the getList method of the user. To do that we need to bind the listener to an endpoint in that way:

$resolver->setBaseUrl('http://localhost/MyTest'); // Assuming this is your local test url.
$resolver->bindListener(new Listener()); // 'user' is the endpoint.

NB: The base url is needed to make the resolver understand which part of the request url do not compute. Not setting it will throw an Exception as it is crucial for the system to work.

Now what remains to do is to resolve incoming requests:

$resolver->resolve(); // Example call: GET http://localhost/MyTest/user/10/getList/15

Let's analyze:

1. We created a Listener class.
2. We annotated the class with the \PHPEasyAPI\Server annotation.
3. We created a method to handle calls and annotated with the \PHPEasyAPI\Enrichment\Endpoint annotation.
4. In the Endpoint annotation we passed the method (GET in this case) we wanted to handle and the url structure (Note that :userId ans :listId are placeholder and they will be substituted with the corresponding part of the url and passed to the function as parameters on the given order).
5. We bound the 'user' endpoint to an instance of the Listener.
6. We resolved the requested url.