Merge pull request #4 from Nekland/1.0

1.0

.travis.yml

@@ -0,0 +1,12 @@
+language: php
+
+php:
+  - 5.4
+  - 5.5
+  - 5.6
+  - hhvm
+
+before_script:
+  - composer install --dev --prefer-source
+
+script: ./vendor/bin/phpspec run

CHANGELOG.md

@@ -0,0 +1,17 @@
+1.0.0 (2014-09-XX)
+==================
+
+New awesome features
+--------------------
+
+* Drop Guzzle dependency
+* Added dependency on Symfony Event Dispatcher Component
+* Added specificity tests with phpspec
+* Added cache strategy support
+* Added transformer strategies
+* Made the ApiFactory "IDE friendly"
+
+Compatibility breaks:
+---------------------
+
+Almost everything, sorry guys this is a new, very very major version :-).

Readme.md

@@ -1,16 +1,25 @@
 Nekland Base API
 ================
 
+[![Build Status](https://travis-ci.org/Nekland/BaseApi.svg)](https://travis-ci.org/Nekland/BaseApi)
+
 Why
 ---
 
 I made this project because I created a lib for Youtube API and another for Souncloud API.
 
 Both libs have the same needs. To avoid duplicated code, I made this little project that can be used as a base for the API lib you want to create.
 
-Inspiration
------------
+How
+---
+
+[x] [Semver](http://semver.org) compliant
+[x] [HHVM](http://hhvm.com/) compatible
+[x] [Composer](http://packagist) installable
+
+Documentation
+-------------
 
-This project look like php-github-api, and it's not innocent. I used it as model.
+This project does not need so much documentation but I wrote some for interested people. Checkout the [doc](doc) folder.
 
-Thanks to KnpLabs & Contributors on this project.
+> This project is inspirated by KNPLabs api libs.

composer.json

@@ -7,20 +7,35 @@
     "authors": [
         {
             "name":     "Maxime Veber",
-            "email":    "nekland@gmail.com",
+            "email":    "nek.dev@gmail.com",
             "homepage": "http://nekland.fr"
+        },
+        {
+            "name":     "Nekland Team",
+            "email":    "[email protected]",
+            "homepage": "http://team.nekland.fr"
         }
     ],
+    "require": {
+        "php": ">=5.4",
+        "symfony/event-dispatcher": "~2.3"
+    },
+    "require-dev": {
+        "phpspec/phpspec":   "dev-master",
+        "guzzlehttp/guzzle": "~4.2"
+    },
     "suggest": {
         "nekland/youtube-api":    "Youtube API made easy !",
         "nekland/soundcloud-api": "Soundcloud API made easy !",
-        "guzzle/guzzle":                  "The default HttpClient will not work without this library."
+        "guzzlehttp/guzzle":      "The only http adapter available for now is for this library."
     },
     "autoload": {
         "psr-0": { "Nekland\\": "lib/" }
     },
-    "require-dev": {
-        "php":             ">=5.4",
-        "phpunit/phpunit": ">=3.7"
+    "minimum-stability": "dev",
+    "extra": {
+        "branch-alias": {
+            "dev-master": "1.0-dev"
+        }
     }
-}
+}

doc/api_classes.md

@@ -0,0 +1,13 @@
+Api classes
+===========
+
+
+They should simply extends the `AbstractApi` class.
+
+She provide you useful methods (get/put/post/delete rest methods) and as the class do some job, you just have to create methods like:
+
+* getResourceById
+* deleteResource
+
+
+> You have to register a namespace to your api objects in the api factory

doc/api_factory.md

@@ -0,0 +1,18 @@
+The ApiFactory
+==============
+
+This class instantiate "[Api classes](api_classes.md)" when you use it like that thanks to the magic method `call`:
+
+```php
+<?php
+
+$apiFactory->getMyAwesomeApi();
+```
+
+So the first thing you have to do when building your API is to extend it and implement the only needed method.
+
+You can also:
+
+* Redefine the `getTransformer` method to change the default one.
+
+Now, build your [API classes](api_classes.md).

doc/auth_and_cache.md

@@ -0,0 +1,21 @@
+Auth & Cache strategies
+=======================
+
+In order to help you manage authentication or cache systems, this lib provides you useful strategies managements.
+
+> Since theses classes are register as event listener (it use the event dispatcher of Symfony), you can add multiple strategies of each feature.
+
+The cache strategy
+==================
+
+This are classes that implements the `CacheStrategyInterface`.
+
+You register them using the method `useCache` of the ApiFactory.
+
+
+The authentication strategy
+===========================
+
+This are classes implementing the `AuthenticationStrategyInterface`.
+
+You register them using the method `useAuthentication` of the ApiFactory

doc/index.md

@@ -0,0 +1,11 @@
+Nekland base api
+================
+
+The idea is to made easy build of new PHP api libs. So this lib provide you some abstract class that will work together with other classes.
+
+You will learn more about things in the dedicated pages of doc:
+
+* [ApiFactory](api_factory.md)
+* [Api classes](api_classes.md)
+* [Auth and Cache strategies](auth_and_cache.md)
+* [Transformers](transformers.md)

doc/transformers.md

@@ -0,0 +1,8 @@
+Transformers
+============
+
+Transformers are classes implementing the `TransformerInterface` interface.
+
+You can set them by using the `setTransformer` of the `ApiFactory` class.
+
+> You can only set one transformer because you can't retrieve the same data in many forms in the same request.

lib/Nekland/BaseApi/Api/AbstractApi.php

@@ -11,20 +11,118 @@
 
 namespace Nekland\BaseApi\Api;
 
-
 use Nekland\BaseApi\Api;
+use Nekland\BaseApi\Http\AbstractHttpClient;
+use Nekland\BaseApi\Transformer\JsonTransformer;
+use Nekland\BaseApi\Transformer\TransformerInterface;
 
 abstract class AbstractApi
 {
-    protected $api;
+    /**
+     * @var AbstractHttpClient
+     */
+    private $client;
+
+    /**
+     * @var TransformerInterface
+     */
+    private $transformer;
+
+    public function __construct(AbstractHttpClient $client, TransformerInterface $transformer = null) {
+        $this->client      = $client;
+        $this->transformer = $transformer ?: new JsonTransformer();
+    }
+
+    /**
+     * Set the transformer that will be used to return data
+     *
+     * @param  TransformerInterface $transformer
+     * @return self
+     */
+    public function setTransformer(TransformerInterface $transformer)
+    {
+        $this->transformer = $transformer;
+
+        return $this;
+    }
+
+    /**
+     * Execute a http get query
+     *
+     * @param  string $path
+     * @param  array  $body
+     * @param  array  $headers
+     * @return array|mixed
+     */
+    protected function get($path, array $body = [], array $headers = [])
+    {
+        $client  = $this->getClient();
+        $request = $client::createRequest('GET', $path, $body, $headers);
+
+        return $this->transformer->transform($client->send($request));
+    }
+
+    /**
+     * Execute a http put query
+     *
+     * @param  string $path
+     * @param  array  $body
+     * @param  array  $headers
+     * @return array|mixed
+     */
+    protected function put($path, array $body = [], array $headers = [])
+    {
+        $client  = $this->getClient();
+        $request = $client::createRequest('PUT', $path, $body, $headers);
+
+        return $this->transformer->transform($client->send($request));
+    }
+
+    /**
+     * Execute a http post query
+     *
+     * @param  string $path
+     * @param  array  $body
+     * @param  array  $headers
+     * @return array|mixed
+     */
+    protected function post($path, array $body = [], array $headers = [])
+    {
+        $client  = $this->getClient();
+        $request = $client::createRequest('POST', $path, $body, $headers);
+
+        return $this->transformer->transform($client->send($request));
+    }
+
+    /**
+     * Execute a http delete query
+     *
+     * @param  string $path
+     * @param  array  $body
+     * @param  array  $headers
+     * @return array|mixed
+     */
+    protected function delete($path, array $body = [], array $headers = [])
+    {
+        $client  = $this->getClient();
+        $request = $client::createRequest('DELETE', $path, $body, $headers);
+
+        return $this->transformer->transform($client->send($request));
+    }
 
-    public function __construct(Api $api)
+    /**
+     * @return AbstractHttpClient
+     */
+    protected function getClient()
     {
-        $this->api = $api;
+        return $this->client;
     }
 
-    protected function get($path, array $parameters = [], array $requestHeaders = [])
+    /**
+     * @return TransformerInterface
+     */
+    protected function getTransformer()
     {
-        return json_decode((string) $this->api->getClient()->get($path, $parameters, $requestHeaders), true);
+        return $this->transformer;
     }
 }