Merge pull request #2 from Rich2k/p8-support

Refactor return types and documentation

.gitignore

@@ -2,3 +2,5 @@
 /.idea
 /.vscode
 .env
+composer.lock
+.DS_Store

README.md

@@ -1,32 +1,50 @@
-## Laravel WeatherKit
+# Laravel WeatherKit
 
 This provides a Laravel style wrapper for Apple's WeatherKit api, which replaced the DarkSky API.
 
 For more information see https://developer.apple.com/weatherkit/get-started/
 
 Please note, Apple requires attribution to use this API in your code https://developer.apple.com/weatherkit/get-started/#attribution-requirements and up to 500,000 calls/month are included with your apple developer account membership.
 
-### Install
+## Install
 
 Require this package with composer using the following command:
 
 ``` bash
 $ composer require rich2k/laravel-weatherkit
 ```
 
-After updating composer, add the service provider to the `providers` array in `config/app.php`
+### Providers
+
+This library works out-of-the-box with Laravel's Service Providers and will be loaded automatically in Laravel `>= 5.5`.
+
+You can, of course, add it manually to your `providers` array in `config/app.php` if you'd prefer
 
 ```php
-Rich2k\LaravelWeatherKit\LaravelWeatherKitServiceProvider::class,
+'providers' => [
+    Rich2k\LaravelWeatherKit\Providers\LaravelServiceProvider::class,
+]
 ```
 
+### Facade
+
 To register a facade accessor, add the following to `config/app.php` `aliases` array
 
 ```php
-'WeatherKit' => \Rich2k\LaravelWeatherKit\Facades\WeatherKit::class,
+'aliases' => [
+    'WeatherKit' => \Rich2k\LaravelWeatherKit\Facades\WeatherKit::class,
+]
+```
+
+### Configuration 
+
+If you wish to change the default configuration, you can publish the configuration file to your project.
+
+```bash
+$ php artisan vendor:publish --provider=\Rich2k\LaravelWeatherKit\Providers\LaravelServiceProvider
 ```
 
-### Auth Keys
+## Auth Keys
 
 You'll need to first generate a JWT token to access WeatherKit APIs.
 
@@ -89,7 +107,7 @@ E.g.
 
 Copy and paste your private and public key into the signature verification, and the output is what you need to add to your configuration.
 
-### Configuration
+## Configuration
 
 Add the following line to the .env file:
 
@@ -98,86 +116,90 @@ WEATHERKIT_JWT_TOKEN=<your_weatherkit_jwt_token>
 ```
 
 
-### Usage
+## Usage
 For full details of response formats, visit: https://developer.apple.com/documentation/weatherkitrestapi/get_api_v1_weather_language_latitude_longitude
 
 There are two endpoints available at present, availability and weather.
 
 Availability allows you to retrieve which data sets are available for a given location. If you call the availability function before the weather one, we will automatically set the requested datasets to this available.
 
-#### Required
-##### location(lat, lon)
+`availability()` and `weather()` functions will return their results as a Laravel `Collection`
+
+### Required
+#### location(lat, lon)
 Pass in latitude and longitude coordinates for a basic response
 ``` php
-WeatherKit::location(lat, lon)->get();
+WeatherKit::location(lat, lon)->weather();
 ```
 
-#### Optional Parameters
+### Optional Parameters
 
-##### language(lang)
+#### language(lang)
 Pass in a language code to return text based responses in the requested language. By default this is `en_US`
 
 ``` php
-WeatherKit::lang('en_GB')->location(lat, lon)->get();
+WeatherKit::lang('en_GB')->location(lat, lon)->weather();
 ```
 
-##### dataSets([])
+#### dataSets([])
 Specify which data sets to use to reduce data transfer.
 
-By default we will try to call `'currentWeather', 'forecastDaily', 'forecastHourly', 'forecastNextHour'`, however you can set these manually with `dataSets()` function. You can also dynamically set this by calling `availability()` before `get()`
+By default we will try to call `'currentWeather', 'forecastDaily', 'forecastHourly', 'forecastNextHour'`, however you can set these manually with `dataSets()` function. You can also dynamically set this by calling `availability()` before `weather()` when not using through a facade.
 
 ```php
-WeatherKit::location(lat, lon)->dataSets(['currentWeather', 'forecastDaily'])->get();
+WeatherKit::location(lat, lon)->dataSets(['currentWeather', 'forecastDaily'])->weather();
 
 // OR
 
-WeatherKit::location(lat, lon)->availability();
-WeatherKit::location(lat, lon)->get();
+$weather = new \Rich2k\LaravelWeatherKit\WeatherKit();
+$weather->location(lat, lon)->availability();
+$weather->location(lat, lon)->weather();
 ```
 
-##### currentAsOf(t)
+#### currentAsOf(t)
 Pass in a Carbon object of time to obtain current conditions. Defaults to now.
 
 ``` php
-WeatherKit::location(lat, lon)->currentAsOf(now())->get();
+WeatherKit::location(lat, lon)->currentAsOf(now())->weather();
 ```
 
-##### dailyStart(t)/dailyEnd(t)
+#### dailyStart(t)/dailyEnd(t)
 `dailyStart()`: The time to start the daily forecast. If this parameter is absent, daily forecasts start on the current day.
 `dailyEnd()`: The time to end the daily forecast. If this parameter is absent, daily forecasts run for 10 days.
 
 ``` php
-WeatherKit::location(lat, lon)->dailyStart(now()->subDays(7))->dailyEnd(now())->get();
+WeatherKit::location(lat, lon)->dailyStart(now()->subDays(7))->dailyEnd(now())->weather();
 ```
 
-##### hourlyStart(t)/hourlyEnd(t)
+#### hourlyStart(t)/hourlyEnd(t)
 `hourlyStart()`: The time to start the hourly forecast. If this parameter is absent, hourly forecasts start on the current hour.
 `hourlyEnd()`: The time to end the hourly forecast. If this parameter is absent, hourly forecasts run 24 hours or the length of the daily forecast, whichever is longer.
 
 ``` php
-WeatherKit::location(lat, lon)->hourlyStart(now()->subHours(24))->hourlyEnd(now())->get();
+WeatherKit::location(lat, lon)->hourlyStart(now()->subHours(24))->hourlyEnd(now())->weather();
 ```
 
-##### timezone(timezone)
+#### timezone(timezone)
 The name of the timezone to use for rolling up weather forecasts into daily forecasts. Defaults to unset, as this is not required unless calling daily forecasts
 
 ``` php
-WeatherKit::location(lat, lon)->timezone('Americas/Los_Angeles')->get();
+WeatherKit::location(lat, lon)->timezone('Americas/Los_Angeles')->weather();
 ```
 
-#### Helpers
+### Helpers
 The following are shorthand helpers to add readability equivalent to using `dataSets` set to a single object.
 ```php
 ->currently()
 ->hourly()
 ->daily()
+->nextHour()
 ```
 For example, these two statements are the same
 ```php
 WeatherKit::location(lat, lon)->hourly()
-WeatherKit::location(lat, lon)->dataSets(['hourly'])->get()->hourly
+WeatherKit::location(lat, lon)->dataSets(['forecastHourly'])->weather()->get('forecastHourly')
 ```
 
-### License
+## License
 
 The MIT License (MIT). Please see [License File](LICENSE.md) for more information.

composer.json

@@ -4,23 +4,35 @@
     "description": "Provides a Wrapper for the Apple WeatherKit API",
     "keywords": [
         "rich2k",
-        "laravel-weatherkit"
+        "laravel-weatherkit",
+        "weatherkit",
+        "apple weatherkit",
+        "weatherkit api",
+        "apple weatherkit api",
+        "weather",
+        "forecast",
+        "weather forecast"
     ],
     "homepage": "https://github.com/rich2k/laravel-weatherkit",
+    "support": {
+        "issues": "https://github.com/rich2k/laravel-weatherkit/issues",
+        "source": "https://github.com/rich2k/laravel-weatherkit"
+    },
     "license": "MIT",
     "authors": [
         {
             "name": "Richard Hyland",
             "email": "rhyland@gmail.com",
-            "homepage": "https://richardhyland.com",
+            "homepage": "https://github.com/rich2k/laravel-weatherkit",
             "role": "Developer"
         }
     ],
     "require": {
         "php": ">=7.4.0",
         "guzzlehttp/guzzle": "~7.0",
         "illuminate/support": "~7.0|~8.0|~9.0",
-        "nesbot/carbon": "~1.0|~2.0"
+        "nesbot/carbon": "~1.0|~2.0",
+        "ext-json": "*"
     },
     "require-dev": {
         "phpunit/phpunit" : "4.*"
@@ -41,19 +53,20 @@
         "fix-style": "phpcbf -p --standard=PSR2 --runtime-set ignore_errors_on_exit 1 --runtime-set ignore_warnings_on_exit 1 src tests"
     },
     "extra": {
-        "branch-alias": {
-            "dev-master": "1.0-dev"
-        },
         "laravel": {
             "providers": [
-                "Rich2k\\LaravelWeatherKit\\LaravelWeatherKitServiceProvider"
+                "Rich2k\\LaravelWeatherKit\\Providers\\LaravelServiceProvider",
+                "Rich2k\\LaravelWeatherKit\\Providers\\CollectionsServiceProvider"
             ],
             "aliases": {
                 "WeatherKit": "Rich2k\\LaravelWeatherKit\\Facades\\WeatherKit"
             }
         }
     },
+    "prefer-stable": true,
     "config": {
+        "optimize-autoloader": true,
+        "preferred-install": "dist",
         "sort-packages": true
     }
 }

config/weatherkit.php

@@ -1,4 +1,14 @@
 <?php
 return [
-    'jwttoken' => env('WEATHERKIT_JWT_TOKEN', ''),
+    'auth' => [
+        'config' => [
+            'jwt' => env('WEATHERKIT_JWT_TOKEN', ''),
+        ],
+
+        'type' => 'jwt',
+    ],
+
+    'languageCode' => env('WEATHERKIT_LANGUAGE_CODE', config('app.locale', 'en')),
+
+    'timezone' => env('WEATHERKIT_TIMEZONE', config('app.timezone', 'UTC')),
 ];

src/Exceptions/DataSetNotFoundException.php

@@ -0,0 +1,11 @@
+<?php
+namespace Rich2k\LaravelWeatherKit\Exceptions;
+
+/**
+ * Class DataSetNotFoundException
+ *
+ * @package Rich2k\LaravelWeatherKit\Exceptions
+ */
+class DataSetNotFoundException extends LaravelWeatherKitException
+{
+}

src/Exceptions/LaravelWeatherKitException.php

@@ -0,0 +1,13 @@
+<?php
+namespace Rich2k\LaravelWeatherKit\Exceptions;
+
+use Exception;
+
+/**
+ * Class LaravelWeatherKitException
+ *
+ * @package Rich2k\LaravelWeatherKit\Exceptions
+ */
+class LaravelWeatherKitException extends Exception
+{
+}

src/Exceptions/MissingCoordinatesException.php

@@ -0,0 +1,11 @@
+<?php
+namespace Rich2k\LaravelWeatherKit\Exceptions;
+
+/**
+ * Class MissingCoordinatesException
+ *
+ * @package Rich2k\LaravelWeatherKit\Exceptions
+ */
+class MissingCoordinatesException extends LaravelWeatherKitException
+{
+}

src/Providers/CollectionsServiceProvider.php

@@ -0,0 +1,36 @@
+<?php
+
+namespace Rich2k\LaravelWeatherKit\Providers;
+
+use Illuminate\Support\Collection;
+use Illuminate\Support\ServiceProvider;
+
+class CollectionsServiceProvider extends ServiceProvider
+{
+    /**
+     * Register the service provider.
+     *
+     * @return void
+     */
+    public function register()
+    {
+        $this->recursive();
+    }
+
+    /**
+     * Recursively collect arrays within a collection
+     *
+     * @return void
+     */
+    private function recursive()
+    {
+        Collection::macro('recursive', function () {
+            return $this->map(function ($value) {
+                if (is_array($value) || is_object($value)) {
+                    return collect($value)->recursive();
+                }
+                return $value;
+            });
+        });
+    }
+}

src/LaravelWeatherKitServiceProvider.php → src/Providers/LaravelServiceProvider.php

@@ -1,10 +1,11 @@
 <?php
 
-namespace Rich2k\LaravelWeatherKit;
+namespace Rich2k\LaravelWeatherKit\Providers;
 
 use Illuminate\Support\ServiceProvider;
+use Rich2k\LaravelWeatherKit\WeatherKit;
 
-class LaravelWeatherKitServiceProvider extends ServiceProvider
+class LaravelServiceProvider extends ServiceProvider
 {
     /**
      * Perform post-registration booting of services.
@@ -13,7 +14,7 @@ class LaravelWeatherKitServiceProvider extends ServiceProvider
      */
     public function boot()
     {
-        $source = dirname(__DIR__).'/config/weatherkit.php';
+        $source = dirname(__DIR__) . '/../config/weatherkit.php';
 
         $this->publishes([$source => config_path('weatherkit.php')]);
 
@@ -27,7 +28,7 @@ public function boot()
      */
     public function register()
     {
-        $this->app->singleton('weatherkit',function($app)
+        $this->app->singleton('weatherkit', function($app)
         {
             return new WeatherKit();
         });