From 597ad5e65b00ce9eafffe98a60f7c67aa07de9af Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Iv=C3=A1n=20Melgrati?= Date: Wed, 5 Oct 2016 15:02:19 -0300 Subject: [PATCH 1/6] Update example-all-parameters.php --- examples/example-all-parameters.php | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/examples/example-all-parameters.php b/examples/example-all-parameters.php index 8e4c9cb..e076a66 100644 --- a/examples/example-all-parameters.php +++ b/examples/example-all-parameters.php @@ -10,7 +10,7 @@ * @version v1.0.0 stable */ - require_once ('../src/GoogleTimeZone.php'); + require_once ('../src/GoogleMapsTimeZone.php'); /** * All queries require an API key from Google @@ -60,4 +60,4 @@ echo '
';
 	var_dump($timezone_data);
 	echo '
'; -?> \ No newline at end of file +?> From e152f4510b4dc4fb0624d4140f5659e1e00985f1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Iv=C3=A1n=20Melgrati?= Date: Wed, 5 Oct 2016 15:02:43 -0300 Subject: [PATCH 2/6] Update example-basic.php --- examples/example-basic.php | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/examples/example-basic.php b/examples/example-basic.php index f8c5e82..cfc5a83 100644 --- a/examples/example-basic.php +++ b/examples/example-basic.php @@ -10,7 +10,7 @@ * @version v1.0.0 stable */ - require_once ('../src/GoogleTimeZone.php'); + require_once ('../src/GoogleMapsTimeZone.php'); /** * All queries require an API key from Google @@ -30,4 +30,4 @@ echo '
';
 	print_r($timezone_data);
 	echo '
'; -?> \ No newline at end of file +?> From 9df68e04085060436455eb7c165dbb7467b2c178 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fran=C3=A7ois=20B?= Date: Mon, 13 Feb 2017 16:43:05 +0100 Subject: [PATCH 3/6] Consistently use 4 spaces instead of tabs Improve comments --- README.md | 8 +- composer.json | 2 +- examples/example-all-parameters.php | 123 ++- examples/example-basic.php | 58 +- phpdoc.dist.xml | 2 +- src/GoogleMapsTimeZone.php | 1126 +++++++++++++-------------- 6 files changed, 658 insertions(+), 661 deletions(-) diff --git a/README.md b/README.md index b3fbfa1..53e261a 100644 --- a/README.md +++ b/README.md @@ -5,9 +5,9 @@ google-time-zone [![Latest Stable Version](https://poser.pugx.org/imelgrat/google-time-zone/v/stable)](https://packagist.org/packages/imelgrat/google-time-zone) [![Total Downloads](https://poser.pugx.org/imelgrat/google-time-zone/downloads)](https://packagist.org/packages/imelgrat/google-time-zone) -A PHP wrapper for the Google Maps TimeZone API. +A PHP wrapper for the Google Maps Time Zone API. -Developed by [Ivan Melgrati](https://twitter.com/imelgrat) +Developed by [Ivan Melgrati](https://twitter.com/imelgrat) Requirements ------------ @@ -36,9 +36,9 @@ be found over at [Packagist](http://packagist.org). ### Manually -1. Copy `src/google-time-zone.php` to your codebase, perhaps to the `vendor` +1. Copy `src/GoogleMapsTimeZone.php` to your codebase, perhaps to the `vendor` directory. -2. Add the `google-time-zone` class to your autoloader or `require` the file +2. Add the `GoogleMapsTimeZone` class to your autoloader or `require` the file directly. Feedback diff --git a/composer.json b/composer.json index 9e44427..c2aa923 100644 --- a/composer.json +++ b/composer.json @@ -2,7 +2,7 @@ "name": "imelgrat/google-time-zone", "type": "library", "version" : "1.2.0", - "description": "A PHP wrapper for the Google Maps TimeZone API.", + "description": "A PHP wrapper for the Google Maps Time Zone API.", "keywords": ["google", "map", "maps", "gmap", "gmaps", "timezone", "time zone", "location"], "homepage": "https://github.com/imelgrat/google-time-zone", "license": "MIT", diff --git a/examples/example-all-parameters.php b/examples/example-all-parameters.php index e076a66..c2780d2 100644 --- a/examples/example-all-parameters.php +++ b/examples/example-all-parameters.php @@ -1,63 +1,62 @@ setApiKey(API_KEY); - - // Set XML as query return format - $timezone_object->setFormat($timezone_object::FORMAT_XML); - - // Set Spanish as query return language - // Check https://developers.google.com/maps/faq#languagesupport for a list of supported languages - $timezone_object->setLanguage('es'); - - // Set latitude (Mexico City International Airport) - $timezone_object->setLatitude(19.4360812); - - // Set longitude (Mexico City International Airport) - $timezone_object->setLongitude(-99.074097); - - // Set Timestamp (server-side current time) - $timezone_object->setTimestamp(time()); - - // Perform query - $timezone_data = $timezone_object->queryTimeZone(); - - echo '
';
-	print_r($timezone_data);
-	echo '
'; - - - // Set XML as query return format - $timezone_object->setFormat($timezone_object::FORMAT_JSON); - // Set Arabic as query return language - // Check https://developers.google.com/maps/faq#languagesupport for a list of supported languages - $timezone_object->setLanguage('ar'); - - // Perform query - $timezone_data = $timezone_object->queryTimeZone(); - - echo '
';
-	var_dump($timezone_data);
-	echo '
'; -?> + +/** + * This section includes a sample query that demonstrate features of the API. + * The code below query performs a time zone request for Github's server (San Francisco, California, United States). The timestamp is set to March 8th, 2012. + * + * @author Ivan Melgrati + * @copyright 2016 + * @package GoogleMapsTimeZone + * @author Ivan Melgrati + * @version v1.2.0 stable + */ + +require_once('../src/GoogleMapsTimeZone.php'); + +/** + * All queries require an API key from Google. + * @link https://developers.google.com/maps/documentation/timezone/get-api-key + */ +define('API_KEY', 'YOUR API KEY HERE'); + +// Create GoogleMapsTimeZone object with default properties. +$timezone_object = new GoogleMapsTimeZone(); + +// Set Google API key. +$timezone_object->setApiKey(API_KEY); + +// Set XML as query return format. +$timezone_object->setFormat($timezone_object::FORMAT_XML); + +// Set Spanish as query return language. +// Check https://developers.google.com/maps/faq#languagesupport for a list of supported languages +$timezone_object->setLanguage('es'); + +// Set latitude (Mexico City International Airport). +$timezone_object->setLatitude(19.4360812); + +// Set longitude (Mexico City International Airport). +$timezone_object->setLongitude(-99.074097); + +// Set Timestamp (server-side current time). +$timezone_object->setTimestamp(time()); + +// Perform query +$timezone_data = $timezone_object->queryTimeZone(); + +echo '
';
+print_r($timezone_data);
+echo '
'; + +// Set XML as query return format. +$timezone_object->setFormat($timezone_object::FORMAT_JSON); +// Set Arabic as query return language. +// Checkhttps://developers.google.com/maps/faq#languagesupport for a list of supported languages +$timezone_object->setLanguage('ar'); + +// Perform query. +$timezone_data = $timezone_object->queryTimeZone(); + +echo '
';
+var_dump($timezone_data);
+echo '
'; diff --git a/examples/example-basic.php b/examples/example-basic.php index cfc5a83..6fe5390 100644 --- a/examples/example-basic.php +++ b/examples/example-basic.php @@ -1,33 +1,33 @@ setApiKey(API_KEY); - - // Perform query - $timezone_data = $timezone_object->queryTimeZone(); +require_once('../src/GoogleMapsTimeZone.php'); - echo '
';
-	print_r($timezone_data);
-	echo '
'; -?> +/** + * All queries require an API key from Google. + * @link https://developers.google.com/maps/documentation/timezone/get-api-key + */ +define('API_KEY', 'YOUR API KEY HERE'); + +// Initialize GoogleMapsTimeZone object. +$timezone_object = new GoogleMapsTimeZone(37.7697, -122.3933, 1331161200, GoogleMapsTimeZone::FORMAT_JSON); + +// Set Google API key. +$timezone_object->setApiKey(API_KEY); + +// Perform query. +$timezone_data = $timezone_object->queryTimeZone(); + +echo '
';
+print_r($timezone_data);
+echo '
'; diff --git a/phpdoc.dist.xml b/phpdoc.dist.xml index 4271676..6b09cdd 100644 --- a/phpdoc.dist.xml +++ b/phpdoc.dist.xml @@ -1,6 +1,6 @@ - GoogleTimeZone - A PHP wrapper for the Google Maps TimeZone API. + GoogleTimeZone - A PHP wrapper for the Google Maps Time Zone API. docs diff --git a/src/GoogleMapsTimeZone.php b/src/GoogleMapsTimeZone.php index 875e78e..548d3a3 100644 --- a/src/GoogleMapsTimeZone.php +++ b/src/GoogleMapsTimeZone.php @@ -1,565 +1,563 @@ setLatitudeLongitude($latitude, $longitude)->setTimestamp($timestamp)->setFormat($format); - } - - /** - * Set the response format. - * - * @link https://developers.google.com/maps/documentation/timezone/intro#Responses - * @param string $format response format - * @return GoogleMapsTimeZone - */ - public function setFormat($format) - { - $this->format = $format; - - return $this; - } - - /** - * Get the response format. - * - * @link https://developers.google.com/maps/documentation/timezone/intro#Responses - * @return string response format - */ - public function getFormat() - { - return $this->format; - } - - /** - * Whether the response format is JSON. - * - * @link https://developers.google.com/maps/documentation/timezone/intro#Requests - * @return bool whether JSON - */ - public function isFormatJson() - { - return $this->getFormat() == self::FORMAT_JSON; - } - - /** - * Whether the response format is XML. - * - * @link https://developers.google.com/maps/documentation/timezone/intro#Requests - * @return bool whether XML - */ - public function isFormatXml() - { - return $this->getFormat() == self::FORMAT_XML; - } - - /** - * Set the latitude/longitude of the location to get timezone information from - * - * @link https://developers.google.com/maps/documentation/timezone/intro#Usage - * @param float|string $latitude latitude - * @param float|string $longitude longitude of the location of the location to get timezone information from - * @return GoogleMapsTimeZone - */ - public function setLatitudeLongitude($latitude, $longitude) - { - $this->setLatitude($latitude)->setLongitude($longitude); - - return $this; - } - - /** - * Get the latitude/longitude of the location of the location to get timezone information from - * in comma-separated format. - * - * @link https://developers.google.com/maps/documentation/timezone/intro#Usage - * @return string|false comma-separated coordinates, or false if not set - */ - public function getLatitudeLongitude() - { - $latitude = $this->getLatitude(); - $longitude = $this->getLongitude(); - - if ($latitude && $longitude) - { - return $latitude . "," . $longitude; - } - else - { - return false; - } - } - - /** - * Set the latitude of the location of the location to get timezone information from - * - * @link https://developers.google.com/maps/documentation/timezone/intro#Usage - * @param float|string $latitude latitude of the location of the location to get timezone information from - * @return GoogleMapsTimeZone - */ - public function setLatitude($latitude) - { - $this->latitude = $latitude; - - return $this; - } - - /** - * Get the latitude of the location to get timezone information from - * - * @link https://developers.google.com/maps/documentation/timezone/intro#Usage - * @return float|string latitude of the location of the location to get timezone information from - */ - public function getLatitude() - { - return $this->latitude; - } - - /** - * Set the longitude of the location to get timezone information from - * - * @link https://developers.google.com/maps/documentation/timezone/intro#Usage - * @param float|string $longitude longitude of the location of the location to get timezone information from - * @return GoogleMapsTimeZone - */ - public function setLongitude($longitude) - { - $this->longitude = $longitude; - - return $this; - } - - /** - * Get the longitude of the location to get timezone information from - * - * @link https://developers.google.com/maps/documentation/timezone/intro#Usage - * @return float|string longitude of the location of the location to get timezone information from - */ - public function getLongitude() - { - return $this->longitude; - } - - /** - * Set the point in time to get timezone information from (used to determine whether or not DST is active). - * - * @link https://developers.google.com/maps/documentation/timezone/intro#Usage - * @param integer|string $timestamp point in time to get timezone information from. Default: 0 (current time) - * @return GoogleMapsTimeZone - */ - public function setTimestamp($timestamp = 0) - { - $this->timestamp = intval($timestamp); - - return $this; - } - - /** - * Get the point in time to get timezone information from (used to determine whether or not DST is active). - * - * @link https://developers.google.com/maps/documentation/timezone/intro#Usage - * @return integer|string point in time to get timezone information from. - */ - public function getTimestamp() - { - return $this->timestamp; - } - - /** - * Set the language code in which to return results. - * - * @link https://developers.google.com/maps/faq#languagesupport - * @param string $language language code - * @return GoogleMapsTimeZone - */ - public function setLanguage($language) - { - $this->language = $language; - - return $this; - } - - /** - * Get the language code in which to return results. - * - * @link https://developers.google.com/maps/faq#languagesupport - * @return string language code - */ - public function getLanguage() - { - return $this->language; - } - - /** - * Set the API key to authenticate with. - * - * @link https://developers.google.com/console/help/new/#UsingKeys - * @param string $apiKey API key - * @return GoogleMapsTimeZone - */ - public function setApiKey($apiKey) - { - $this->apiKey = $apiKey; - - return $this; - } - - /** - * Get the API key to authenticate with. - * - * @link https://developers.google.com/console/help/new/#UsingKeys - * @return string API key - */ - public function getApiKey() - { - return $this->apiKey; - } - - /** - * Set the client ID for Business clients. - * - * @link https://developers.google.com/maps/documentation/business/webservices/#client_id - * @param string $clientId client ID - * @return GoogleMapsTimeZone - */ - public function setClientId($clientId) - { - $this->clientId = $clientId; - - return $this; - } - - /** - * Get the client ID for Business clients. - * - * @link https://developers.google.com/maps/documentation/business/webservices/#client_id - * @return string client ID - */ - public function getClientId() - { - return $this->clientId; - } - - /** - * Set the cryptographic signing key for Business clients. - * - * @link https://developers.google.com/maps/documentation/business/webservices/#cryptographic_signing_key - * @param string $signingKey cryptographic signing key - * @return GoogleMapsTimeZone - */ - public function setSigningKey($signingKey) - { - $this->signingKey = $signingKey; - - return $this; - } - - /** - * Get the cryptographic signing key for Business clients. - * - * @link https://developers.google.com/maps/documentation/business/webservices/#cryptographic_signing_key - * @return string cryptographic signing key - */ - public function getSigningKey() - { - return $this->signingKey; - } - - /** - * Whether the request is for a Business client. - * - * @return bool whether the request is for a Business client - */ - public function isBusinessClient() - { - return $this->getClientId() && $this->getSigningKey(); - } - - /** - * Generate the signature for a Business client timezone request. - * - * @link https://developers.google.com/maps/documentation/business/webservices/auth#digital_signatures - * @param string $pathQueryString path and query string of the request - * @return string Base64 encoded signature that's URL safe - */ - protected function generateSignature($pathQueryString) - { - $decodedSigningKey = self::base64DecodeUrlSafe($this->getSigningKey()); - - $signature = hash_hmac('sha1', $pathQueryString, $decodedSigningKey, true); - $signature = self::base64EncodeUrlSafe($signature); - - return $signature; - } - - /** - * Build the query string with all set parameters of the timezone request. - * - * @link https://developers.google.com/maps/documentation/timezone/intro#Requests - * @return string encoded query string of the timezone request - */ - protected function timezoneQueryString() - { - $queryString = array(); - - // Get Latitude and Longitude of the location to get timezone information from. - $latitudeLongitude = $this->getLatitudeLongitude(); - - // Get timestamp as seconds since midnight, January 1, 1970 UTC - $timestamp = intval($this->getTimestamp()); - - // Get language of the query results - $language = trim($this->getLanguage()); - - $queryString['location'] = $latitudeLongitude; - - // Optional language parameter. - $queryString['language'] = $language; - - // Remove any unset parameters. - $queryString = array_filter($queryString); - - // Optional language parameter (specified after array_filter to prevent deletion when timestamp = 0). - $queryString['timestamp'] = $timestamp; - - // Get point in time to get timezone information from. - - // The signature is added later using the path + query string. - if ($this->isBusinessClient()) - { - $queryString['client'] = $this->getClientId(); - } - elseif ($this->getApiKey()) - { - $queryString['key'] = $this->getApiKey(); - } - - // Convert array to proper query string. - return http_build_query($queryString); - } - - /** - * Build the URL (with query string) of the timezone request. - * - * @link https://developers.google.com/maps/documentation/timezone/intro#Requests - * @return string URL of the timezone request - */ - protected function timezoneUrl() - { - // HTTPS is always required - $scheme = "https"; - - $pathQueryString = self::URL_PATH . $this->getFormat() . "?" . $this->timezoneQueryString(); - - if ($this->isBusinessClient()) - { - $pathQueryString .= "&signature=" . $this->generateSignature($pathQueryString); - } - - return $scheme . "://" . self::URL_DOMAIN . $pathQueryString; - } - - /** - * Execute the timezone request. The return type is based on the requested - * format: associative array if JSON, SimpleXMLElement object if XML. - * - * @link https://developers.google.com/maps/documentation/timezone/intro#Responses - * @param bool $raw whether to return the raw (string) response - * @param resource $context stream context from `stream_context_create()` - * @return string|array|SimpleXMLElement response in requested format - */ - public function queryTimeZone($raw = false, $context = null) - { - $response = file_get_contents($this->timezoneUrl(), false, $context); - - if ($raw) - { - return $response; - } - elseif ($this->isFormatJson()) - { - return json_decode($response, true); - } - elseif ($this->isFormatXml()) - { - return new SimpleXMLElement($response); - } - else - { - return $response; - } - } - - /** - * Encode a string with Base64 using only URL safe characters. - * - * @param string $value value to encode - * @return string encoded value - */ - protected static function base64EncodeUrlSafe($value) - { - return strtr(base64_encode($value), '+/', '-_'); - } - - /** - * Decode a Base64 string that uses only URL safe characters. - * - * @param string $value value to decode - * @return string decoded value - */ - protected static function base64DecodeUrlSafe($value) - { - return base64_decode(strtr($value, '-_', '+/')); - } - - } - } -?> \ No newline at end of file + +/** + * A PHP wrapper for the Google Maps Time Zone API. + * + * @package GoogleMapsTimeZone + * @author Ivan Melgrati + * @version v1.2.0 stable + */ + +if (!class_exists('GoogleMapsTimeZone')) +{ + /** + * A PHP wrapper for the Google Maps Time Zone API. + * + * @author Ivan Melgrati + * @copyright Copyright 2016 by Ivan Melgrati + * @license https://github.com/imelgrat/google-time-zone/blob/master/LICENSE + * @link https://developers.google.com/maps/documentation/timezone/intro + * @version v1.2.0 stable + */ + class GoogleMapsTimeZone + { + /** + * URL_DOMAIN Domain portion of the Google Maps Time Zone API URL. + */ + const URL_DOMAIN = "maps.googleapis.com"; + + /** + * URL_PATH Path portion of the Google Maps Time Zone API URL. + */ + const URL_PATH = "/maps/api/timezone/"; + + /** + * HTTPS URL of the Google Maps Time Zone API. + */ + const URL_HTTPS = "https://maps.googleapis.com/maps/api/timezone/"; + + /** + * FORMAT_JSON JSON response format. + */ + const FORMAT_JSON = "json"; + + /** + * FORMAT_XML XML response format. + */ + const FORMAT_XML = "xml"; + + /** + * STATUS_SUCCESS No errors occurred, the coordinates were successfully parsed and at least one time zone was returned. + */ + const STATUS_SUCCESS = "OK"; + + /** + * STATUS_NO_RESULTS Coordinates parsing was successful, but returned no results. Indicates that no time zone data could be found for the specified position or time. Confirm that the request is for a location on land, and not over water. + */ + const STATUS_NO_RESULTS = "ZERO_RESULTS"; + + /** + * STATUS_OVER_LIMIT Over limit of 2,500 (100,000 if premier) requests per day. + */ + const STATUS_OVER_LIMIT = "OVER_QUERY_LIMIT"; + + /** + * STATUS_INVALID_REQUEST Invalid request, indicates that the request was malformed or a mandatory parameter was missing. + */ + const STATUS_INVALID_REQUEST = "INVALID_REQUEST"; + + /** + * Request denied. Indicates that the API did not complete the request. Confirm that the request was sent over HTTPS instead of HTTP. + */ + const STATUS_REQUEST_DENIED = "REQUEST_DENIED"; + + /** + * STATUS_UNKNOWN_ERROR Unknown server error. May succeed if tried again. + */ + const STATUS_UNKNOWN_ERROR = "UNKNOWN_ERROR"; + + /** + * Response format. + * + * @access protected + * @var string $format + */ + protected $format; + + /** + * Latitude to obtain the Time Zone from. + * + * @access protected + * @var float|string $latitude + */ + protected $latitude; + + /** + * Longitude to obtain the Time Zone from. + * + * @access protected + * @var float|string $longitude + */ + protected $longitude; + + /** + * Desired time as seconds since midnight, January 1, 1970 UTC. The Google Maps Time Zone API uses the timestamp to determine whether or not Daylight Savings should be applied. Times before 1970 can be expressed as negative values. + * + * @access protected + * @var integer $timestamp + * + */ + protected $timestamp; + + /** + * Language code in which to return results. + * + * @access protected + * @var string $language + */ + protected $language; + + /** + * Google Maps API key to authenticate with. + * + * @access protected + * @var string $apiKey + */ + protected $apiKey; + + /** + * Google Maps API Client ID for Business clients. + * + * @access protected + * @var string $clientId + */ + protected $clientId; + + /** + * Google Maps API Cryptographic signing key for Business clients. + * + * @access protected + * @var string $signingKey + */ + protected $signingKey; + + /** + * Constructor. The request is not executed until `queryTimeZone()` is called. + * + * @param float $latitude Latitude of the location to get time zone information from. + * @param float $longitude Longitude of the location to get time zone information from. + * @param integer|string $timestamp Point in time to get time zone information from. Default: 0 (current time). + * @param string $format Optional response format. Default: JSON. + * @return GoogleMapsTimeZone + */ + public function __construct($latitude = 0, $longitude = 0, $timestamp = 0, $format = self::FORMAT_JSON) + { + $this->setLatitudeLongitude($latitude, $longitude)->setTimestamp($timestamp)->setFormat($format); + } + + /** + * Set the response format. + * + * @link https://developers.google.com/maps/documentation/timezone/intro#Responses + * @param string $format Response format. + * @return GoogleMapsTimeZone + */ + public function setFormat($format) + { + $this->format = $format; + + return $this; + } + + /** + * Get the response format. + * + * @link https://developers.google.com/maps/documentation/timezone/intro#Responses + * @return string Response format. + */ + public function getFormat() + { + return $this->format; + } + + /** + * Whether the response format is JSON. + * + * @link https://developers.google.com/maps/documentation/timezone/intro#Requests + * @return bool Ehether JSON. + */ + public function isFormatJson() + { + return $this->getFormat() == self::FORMAT_JSON; + } + + /** + * Whether the response format is XML. + * + * @link https://developers.google.com/maps/documentation/timezone/intro#Requests + * @return bool whether XML + */ + public function isFormatXml() + { + return $this->getFormat() == self::FORMAT_XML; + } + + /** + * Set the latitude/longitude of the location to get time zone information from. + * + * @link https://developers.google.com/maps/documentation/timezone/intro#Usage + * @param float|string $latitude Latitude of the location to get time zone information from. + * @param float|string $longitude Longitude of the location to get time zone information from. + * @return GoogleMapsTimeZone + */ + public function setLatitudeLongitude($latitude, $longitude) + { + $this->setLatitude($latitude)->setLongitude($longitude); + + return $this; + } + + /** + * Get the latitude/longitude of the location to get time zone information from in comma-separated format. + * + * @link https://developers.google.com/maps/documentation/timezone/intro#Usage + * @return string|false Comma-separated coordinates, or false if not set. + */ + public function getLatitudeLongitude() + { + $latitude = $this->getLatitude(); + $longitude = $this->getLongitude(); + + if ($latitude && $longitude) + { + return $latitude . "," . $longitude; + } + else + { + return false; + } + } + + /** + * Set the latitude of the location to get time zone information from. + * + * @link https://developers.google.com/maps/documentation/timezone/intro#Usage + * @param float|string $latitude Latitude of the location to get time zone information from. + * @return GoogleMapsTimeZone + */ + public function setLatitude($latitude) + { + $this->latitude = $latitude; + + return $this; + } + + /** + * Get the latitude of the location to get time zone information from. + * + * @link https://developers.google.com/maps/documentation/timezone/intro#Usage + * @return float|string Latitude of the location to get time zone information from. + */ + public function getLatitude() + { + return $this->latitude; + } + + /** + * Set the longitude of the location to get time zone information from. + * + * @link https://developers.google.com/maps/documentation/timezone/intro#Usage + * @param float|string $longitude Longitude of the location to get time zone information from. + * @return GoogleMapsTimeZone + */ + public function setLongitude($longitude) + { + $this->longitude = $longitude; + + return $this; + } + + /** + * Get the longitude of the location to get time zone information from. + * + * @link https://developers.google.com/maps/documentation/timezone/intro#Usage + * @return float|string Longitude of the location to get time zone information from. + */ + public function getLongitude() + { + return $this->longitude; + } + + /** + * Set the point in time to get time zone information from (used to determine whether or not DST is active). + * + * @link https://developers.google.com/maps/documentation/timezone/intro#Usage + * @param integer|string $timestamp Point in time to get time zone information from. Default: 0 (current time). + * @return GoogleMapsTimeZone + */ + public function setTimestamp($timestamp = 0) + { + $this->timestamp = intval($timestamp); + + return $this; + } + + /** + * Get the point in time to get time zone information from (used to determine whether or not DST is active). + * + * @link https://developers.google.com/maps/documentation/timezone/intro#Usage + * @return integer|string Point in time to get time zone information from. + */ + public function getTimestamp() + { + return $this->timestamp; + } + + /** + * Set the language code in which to return results. + * + * @link https://developers.google.com/maps/faq#languagesupport + * @param string $language Language code. + * @return GoogleMapsTimeZone + */ + public function setLanguage($language) + { + $this->language = $language; + + return $this; + } + + /** + * Get the language code in which to return results. + * + * @link https://developers.google.com/maps/faq#languagesupport + * @return string Language code. + */ + public function getLanguage() + { + return $this->language; + } + + /** + * Set the API key to authenticate with. + * + * @link https://developers.google.com/console/help/new/#UsingKeys + * @param string $apiKey API key. + * @return GoogleMapsTimeZone + */ + public function setApiKey($apiKey) + { + $this->apiKey = $apiKey; + + return $this; + } + + /** + * Get the API key to authenticate with. + * + * @link https://developers.google.com/console/help/new/#UsingKeys + * @return string API key. + */ + public function getApiKey() + { + return $this->apiKey; + } + + /** + * Set the client ID for Business clients. + * + * @link https://developers.google.com/maps/documentation/business/webservices/#client_id + * @param string $clientId Client ID. + * @return GoogleMapsTimeZone + */ + public function setClientId($clientId) + { + $this->clientId = $clientId; + + return $this; + } + + /** + * Get the client ID for Business clients. + * + * @link https://developers.google.com/maps/documentation/business/webservices/#client_id + * @return string Client ID. + */ + public function getClientId() + { + return $this->clientId; + } + + /** + * Set the cryptographic signing key for Business clients. + * + * @link https://developers.google.com/maps/documentation/business/webservices/#cryptographic_signing_key + * @param string $signingKey Cryptographic signing key. + * @return GoogleMapsTimeZone + */ + public function setSigningKey($signingKey) + { + $this->signingKey = $signingKey; + + return $this; + } + + /** + * Get the cryptographic signing key for Business clients. + * + * @link https://developers.google.com/maps/documentation/business/webservices/#cryptographic_signing_key + * @return string Cryptographic signing key. + */ + public function getSigningKey() + { + return $this->signingKey; + } + + /** + * Whether the request is for a Business client. + * + * @return bool Whether the request is for a Business client. + */ + public function isBusinessClient() + { + return $this->getClientId() && $this->getSigningKey(); + } + + /** + * Generate the signature for a Business client time zone request. + * + * @link https://developers.google.com/maps/documentation/business/webservices/auth#digital_signatures + * @param string $pathQueryString Path and query string of the request. + * @return string Base64 encoded Signature that's URL safe. + */ + protected function generateSignature($pathQueryString) + { + $decodedSigningKey = self::base64DecodeUrlSafe($this->getSigningKey()); + + $signature = hash_hmac('sha1', $pathQueryString, $decodedSigningKey, true); + $signature = self::base64EncodeUrlSafe($signature); + + return $signature; + } + + /** + * Build the query string with all set parameters of the time zone request. + * + * @link https://developers.google.com/maps/documentation/timezone/intro#Requests + * @return string Encoded query string of the time zone request. + */ + protected function timezoneQueryString() + { + $queryString = array(); + + // Get Latitude and Longitude of the location to get time zone information from. + $latitudeLongitude = $this->getLatitudeLongitude(); + + // Get timestamp as seconds since midnight, January 1, 1970 UTC + $timestamp = intval($this->getTimestamp()); + + // Get language of the query results. + $language = trim($this->getLanguage()); + + $queryString['location'] = $latitudeLongitude; + + // Optional language parameter. + $queryString['language'] = $language; + + // Remove any unset parameters. + $queryString = array_filter($queryString); + + // Optional language parameter (specified after array_filter to prevent deletion when timestamp = 0). + $queryString['timestamp'] = $timestamp; + + // Get point in time to get time zone information from. + + // The signature is added later using the path + query string. + if ($this->isBusinessClient()) + { + $queryString['client'] = $this->getClientId(); + } + elseif ($this->getApiKey()) + { + $queryString['key'] = $this->getApiKey(); + } + + // Convert array to proper query string. + return http_build_query($queryString); + } + + /** + * Build the URL (with query string) of the time zone request. + * + * @link https://developers.google.com/maps/documentation/timezone/intro#Requests + * @return string URL of the time zone request. + */ + protected function timezoneUrl() + { + // HTTPS is always required. + $scheme = "https"; + + $pathQueryString = self::URL_PATH . $this->getFormat() . "?" . $this->timezoneQueryString(); + + if ($this->isBusinessClient()) + { + $pathQueryString .= "&signature=" . $this->generateSignature($pathQueryString); + } + + return $scheme . "://" . self::URL_DOMAIN . $pathQueryString; + } + + /** + * Execute the time zone request. The return type is based on the requested + * format: associative array if JSON, SimpleXMLElement object if XML. + * + * @link https://developers.google.com/maps/documentation/timezone/intro#Responses + * @param bool $raw Whether to return the raw (string) response. + * @param resource $context Stream context from `stream_context_create()`. + * @return string|array|SimpleXMLElement Response in requested format. + */ + public function queryTimeZone($raw = false, $context = null) + { + $response = file_get_contents($this->timezoneUrl(), false, $context); + + if ($raw) + { + return $response; + } + elseif ($this->isFormatJson()) + { + return json_decode($response, true); + } + elseif ($this->isFormatXml()) + { + return new SimpleXMLElement($response); + } + else + { + return $response; + } + } + + /** + * Encode a string with Base64 using only URL safe characters. + * + * @param string $value Value to encode. + * @return string encoded Value. + */ + protected static function base64EncodeUrlSafe($value) + { + return strtr(base64_encode($value), '+/', '-_'); + } + + /** + * Decode a Base64 string that uses only URL safe characters. + * + * @param string $value Value to decode. + * @return string decoded Value. + */ + protected static function base64DecodeUrlSafe($value) + { + return base64_decode(strtr($value, '-_', '+/')); + } + } +} From 96d4166194995e5baddf329a691b6d8b6049979d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Iv=C3=A1n=20Melgrati?= Date: Thu, 16 Feb 2017 19:38:59 -0300 Subject: [PATCH 4/6] Update composer.json --- composer.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/composer.json b/composer.json index c2aa923..37dff4c 100644 --- a/composer.json +++ b/composer.json @@ -1,7 +1,7 @@ { "name": "imelgrat/google-time-zone", "type": "library", - "version" : "1.2.0", + "version" : "1.3.0", "description": "A PHP wrapper for the Google Maps Time Zone API.", "keywords": ["google", "map", "maps", "gmap", "gmaps", "timezone", "time zone", "location"], "homepage": "https://github.com/imelgrat/google-time-zone", From 9e2070f02f8159d0415df775914fd615e7510391 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Iv=C3=A1n=20Melgrati?= Date: Thu, 16 Feb 2017 19:41:05 -0300 Subject: [PATCH 5/6] Update composer.json --- composer.json | 1 - 1 file changed, 1 deletion(-) diff --git a/composer.json b/composer.json index 37dff4c..8321ba3 100644 --- a/composer.json +++ b/composer.json @@ -1,7 +1,6 @@ { "name": "imelgrat/google-time-zone", "type": "library", - "version" : "1.3.0", "description": "A PHP wrapper for the Google Maps Time Zone API.", "keywords": ["google", "map", "maps", "gmap", "gmaps", "timezone", "time zone", "location"], "homepage": "https://github.com/imelgrat/google-time-zone", From f6628572c0b78314f39e7c9d605468bda05f0f09 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Iv=C3=A1n=20Melgrati?= Date: Wed, 27 Dec 2017 18:10:49 -0300 Subject: [PATCH 6/6] Update README.md --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 53e261a..2cf08af 100644 --- a/README.md +++ b/README.md @@ -7,7 +7,7 @@ google-time-zone A PHP wrapper for the Google Maps Time Zone API. -Developed by [Ivan Melgrati](https://twitter.com/imelgrat) +Developed by [Ivan Melgrati](https://imelgrat.me) [![Twitter](https://img.shields.io/twitter/url/https/github.com/imelgrat/tab-collapse.svg?style=social)](https://twitter.com/imelgrat) Requirements ------------