FIrst commit

Author: Nek-

LICENSE

@@ -0,0 +1,16 @@
+Copyright (c) 2013-2013 Maxime Veber
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is furnished
+to do so, subject to the following conditions:
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

README.md

@@ -0,0 +1,33 @@
+Places API
+==========
+
+This library helps you to ask for Google Places API.
+
+Installation
+------------
+
+It's simple ! Just use the following composer command line.
+
+```bash
+composer require 'nekland/places-api:~1.0'
+```
+
+Usage
+-----
+
+```php
+<?php
+
+use Nekland\PlacesApi\Places;
+
+$api = new Places();
+
+$api->useAuthentication('PublicApiAccess', ['key' => 'MY KEY']);
+
+$result = $api->getSearchApi()->search('49.8445057,3.2912589', 1000);
+```
+
+
+Who needs a documentation ? NeklandPlacesApi supports provide auto-completion for compatibles IDEs.
+
+If yours don't, no problem: the documentation is available [here](docs/index.md).

composer.json

@@ -0,0 +1,32 @@
+{
+    "name": "nekland/places-api",
+    "type": "library",
+    "description": "Google Places API made easy !",
+    "autoload": {
+        "psr-0": { "": "src/" }
+    },
+    "keywords": ["nekland", "api", "places"],
+    "license": "MIT",
+    "authors": [
+        {
+            "name": "Maxime Veber",
+            "email": "[email protected]",
+            "homepage": "http://nekland.fr"
+        }
+    ],
+    "require": {
+        "php": ">=5.4",
+        "guzzlehttp/guzzle": "~5.0",
+        "nekland/base-api": "~1.0"
+    },
+    "require-dev": {
+        "phpspec/phpspec": "~2.0"
+    },
+    "minimum-stability": "dev",
+    "extra": {
+        "branch-alias": {
+            "dev-master": "1.x-dev"
+        }
+    }
+}
+

docs/api_autocomplete.md

@@ -0,0 +1,27 @@
+Autocomplete API reference
+====================
+
+Retrieving API
+--------------
+
+```php
+<?php
+
+$api = new Autocomplete();
+
+$autocomplete = $api->getAutocompleteApi();
+```
+
+Available methods
+-----------------
+
+### Get autocomplete from input
+
+```php
+<?php
+
+array Autocomplete::autocomplete($input [, array $other = []])
+```
+
+* `input`: the input of your user
+* `other`: see documentation here https://developers.google.com/places/documentation/autocomplete

docs/api_places.md

@@ -0,0 +1,30 @@
+Places API Reference
+====================
+
+Retrieving API
+--------------
+
+```php
+<?php
+
+$api = new Places();
+
+$places = $api->getPlacesApi();
+```
+
+
+Available methods
+-----------------
+
+### Retrieve details for a place using id
+
+```php
+<?php
+
+array public Places::getPlaceById($id, [, array $extensions = [], [ $language = null ]])
+
+```
+
+* `id`: a string representing a place (notice that this is **not** the `reference` of the place)
+* `extensions`: an array of data you want to retrieve in addition of default data send by google
+* `language`: one of the languages listed here: https://developers.google.com/maps/faq#languagesupport

docs/api_search.md

@@ -0,0 +1,41 @@
+Search API reference
+====================
+
+Retrieving API
+--------------
+
+```php
+<?php
+
+$api = new Places();
+
+$search = $api->getSearchApi();
+```
+
+Available methods
+-----------------
+
+### Search by location and radius
+
+```php
+<?php
+
+array Search::search($location, $radius [, array $other = []])
+```
+
+* `location`: a location (latitude,longitude), i.e. `48.8588589,2.3470599,13`
+* `radius`: distance in meters around the location, i.e. `1000` (meaning 1 kilometer)
+* `other`: see all possible parameters here: https://developers.google.com/places/documentation/search
+
+### Search by text query
+
+```php
+<?php
+
+array Search::textSearch($text [, array $others = []])
+```
+
+* `text`: some text defining a place
+* `other`: see https://developers.google.com/places/documentation/search
+
+> Notice: if you specify location, you need to specify also radius

docs/authentication.md

@@ -0,0 +1,26 @@
+Authentication
+==============
+
+Public API access
+-----------------
+
+To make this authentication work, you just have to generate an APIKEY from the google developer console. You can do it like that:
+
+1. Go to https://console.developers.google.com/project;
+2. Create your project if it's not already in the project list (we do not care about the project id);
+3. Click on the name of your project in the list;
+4. Click on APIS & AUTH > API and on "Places API" in the API list and click on "OFF" button to make it becoming "ON";
+5. Click on APIS & AUTH > Credentials;
+6. In the section Public API access, create a new key of type Server Key and specify your IP address.
+
+> Be careful, Google take care of IPv6.
+
+```php
+<?php
+
+$api = new Places();
+$api->authentication([
+    'PublicApiAccess',
+    ['key' => 'MY_PLACES_APIKEY']
+]);
+```

docs/index.md

@@ -0,0 +1,43 @@
+Places API
+==========
+
+Installation
+------------
+
+```bash
+composer require 'nekland/places-api:~1.0'
+```
+
+This will add `nekland/youtube-api` to your composer.json file and automatically download it to your `vendor` folder.
+
+
+Usage
+-----
+
+
+1. Declare a new instance of Places object
+2. Configure an authentication strategy
+3. Get an API class and ask data from it
+
+Example:
+
+```php
+<?php
+
+use Nekland\PlacesApi\Places;
+
+$api = new Places();
+
+$api->useAuthentication('PublicApiAccess', ['key' => 'SOME KEY']);
+
+$result = $api->getSearchApi()->search('49.8445057,3.2912589', 1000);
+
+```
+
+More
+----
+
+1. Learn more about [authentication](authentication.md)
+2. [Api Search reference](api_search.md)
+3. [Api Places reference](api_places.md)
+4. [Api Autocomplete reference](api_autocomplete.md)

src/Nekland/PlacesApi/Api/Autocomplete.php

@@ -0,0 +1,52 @@
+<?php
+
+/**
+ * This file is a part of nekland places api package
+ *
+ * (c) Nekland <[email protected]>
+ *
+ * For the full license, take a look to the LICENSE file
+ * on the root directory of this project
+ */
+
+namespace Nekland\PlacesApi\Api;
+
+
+use Nekland\BaseApi\Api\AbstractApi;
+use Nekland\BaseApi\Exception\AuthenticationException;
+use Nekland\BaseApi\Exception\QuotaLimitException;
+
+class Autocomplete extends AbstractApi
+{
+    const URL = 'autocomplete/json';
+
+    public function autocomplete($input, array $other = [])
+    {
+        $body = array_merge(['input' => $input], $other);
+
+        $result = $this->get(self::URL, $body);
+
+        switch($result['status']) {
+            case 'OK':
+                return $result['predictions'];
+
+            case 'ZERO_RESULTS':
+                return [];
+
+            case 'OVER_QUERY_LIMIT':
+                throw new QuotaLimitException();
+                break;
+
+            case 'REQUEST_DENIED':
+                throw new AuthenticationException();
+                break;
+
+            case 'INVALID_REQUEST':
+                throw new \InvalidArgumentException('The input is not correct for autocomplete.');
+                break;
+
+            default:
+                throw new \RuntimeException('This case is not supported, please report these to NeklandPlacesApi.');
+        }
+    }
+}

src/Nekland/PlacesApi/Api/Places.php

@@ -0,0 +1,61 @@
+<?php
+
+/**
+ * This file is a part of nekland places api package
+ *
+ * (c) Nekland <[email protected]>
+ *
+ * For the full license, take a look to the LICENSE file
+ * on the root directory of this project
+ */
+
+namespace Nekland\PlacesApi\Api;
+
+
+use Doctrine\Instantiator\Exception\InvalidArgumentException;
+use Nekland\BaseApi\Api\AbstractApi;
+
+/**
+ * Class Places
+ *
+ * Return a place resource
+ */
+class Places extends AbstractApi
+{
+    const URL = 'details/json';
+    private $validExtensions = ['review_summary'];
+
+    /**
+     * To see a list of supported languages, please checkout https://developers.google.com/maps/faq#languagesupport
+     *
+     * @param string $id
+     * @param array  $extensions
+     * @param string  $language
+     * @return array
+     */
+    public function getPlaceById($id, array $extensions = [], $language = null)
+    {
+        $this->validateExtension($extensions);
+        $extensions = implode(',', $extensions);
+
+        $body = array_merge(
+            ['placeid' => $id],
+            !empty($extensions) ? ['extensions' => $extensions] : [],
+            null !== $language ? ['language' => $language] : []
+        );
+
+        return $this->get(self::URL, $body);
+    }
+
+    /**
+     * @param array $extensions
+     */
+    private function validateExtension(array $extensions)
+    {
+        foreach ($extensions as $extension) {
+            if (!in_array($extension, $this->validExtensions)) {
+                throw new \InvalidArgumentException(sprintf('The extensions can only be one of "%s"', implode(',', $this->validExtensions)));
+            }
+        }
+    }
+}