major changes and improvements

Author: SethSharp

README.md

@@ -18,6 +18,11 @@ A wrapper simplifies the usage and implementation of powerful APIs like "The Odd
 # Contribution Guide
 This is an open-source project, so contributions are welcome! Whether you want to add new features, fix bugs, or improve documentation, your help is appreciated. Submit your PR for review and I will review them as soon as possible.
 
+**Sport Enum opportunity**
+This package uses an enum to define the sports you can pass to the endpoints, this ensures you don't make a typo or have
+to worry about remembering the exact grammar. Currently, there are only a couple sports so if you need the support for more,
+make a PR to add them in.
+
 # Steps for Installation
 ### Composer
 ```bash
@@ -30,6 +35,57 @@ This file contains some essential information the Client requires to make succes
 php artisan vendor:publish --tag="odds-api-config"
 ```
 
+### Example Usages
+You can simply create a new Client, passing in your api key and thats it!
+```php
+$client = new OddsClient(config('odds-api.api_key'));
+
+$response = $client->setRegion('us')
+    ->dateFormat('iso')
+    ->getOddsForSport(SportsEnum::RUGBYLEAGUE_NRL);
+
+return $response->json();
+```
+
+This package is setup in a way that all the params you may need are functions which can be chained together on one
+line, as they all return `$this`. Once you call one of the API endpoints which return a response, you can no longer call 
+these functions.
+
+**Another way to define your Client Class**
+
+You can bind your Client class at runtime in the AppServiceProvider. Allowing you to simply define the Client 
+in the constructor of your class, without having to constantly pass the api credentials.
+```php
+$this->app->bind(OddsClient::class, function () {
+    return new OddsClient(config('odds-api.api_key'));
+});
+```
+then your class may look like
+```php
+public function __invoke(OddsClient $client): Response
+{
+    $response = $client->setRegion('us')
+        ->getOddsForSport(SportsEnum::RUGBYLEAGUE_NRL);
+        
+    return $response->json();
+}
+```
+
+**Additional**
+When constructing the Client, it will have some default parameters
+```php
+$this->params = [
+    'api_key' => $this->apiKey,
+    'regions' => config('odds-api.default_region'),
+    'oddsFormat' => config('odds-api.default_odds_format')
+];
+```
+This avoids having to define these on each request, but they can be overwritten with their corresponding class functions ie;
+`setRegions('au')`
+
+Also if this API ever becomes outdated for a small period of time, and you require to use new parameters, you can utilise
+the `addParams()` function, which accepts an array where you can pass any new parameters.
+
 ## Credits
 - [Seth Sharp](https://github.com/SethSharp)
 - [All Contributors](https://github.com/SethSharp/odds-api/graphs/contributors)

config/odds-api.php

@@ -2,5 +2,7 @@
 
 return [
     'secret' => env('ODDS_API_KEY'),
-    'version' => 'v4'
+    'version' => 'v4',
+    'default_region' => 'au',
+    'default_odds_format' => 'decimal'
 ];

src/Enums/SportsEnum.php

@@ -4,7 +4,8 @@
 
 enum SportsEnum: string
 {
-    // todo: fill in with the rest of the sports from  https://the-odds-api.com/sports-odds-data/sports-apis.html
+    // todo: https://the-odds-api.com/sports-odds-data/sports-apis.html
+    // Benefits are that you don't need to remember the exact naming, just start typing the sport in the enum
     case RUGBYLEAGUE_NRL = 'rugbyleague_nrl';
     case AUSSIERULES_AFL = 'aussierules_afl';
 }

src/OddsClient.php

@@ -4,20 +4,18 @@
 
 use GuzzleHttp\Client;
 use GuzzleHttp\Psr7\Response;
+use SethSharp\OddsApi\Enums\SportsEnum;
 use GuzzleHttp\Exception\RequestException;
 use SethSharp\OddsApi\Traits\UseHandleHeaders;
-use SethSharp\OddsApi\Traits\Endpoints\UseOdds;
-use SethSharp\OddsApi\Traits\Endpoints\UseSports;
 
 class OddsClient
 {
-    use UseOdds;
-    use UseSports;
     use UseHandleHeaders;
 
     private Client $client;
     private string $apiKey;
     private string $apiEndpoint = 'https://api.the-odds-api.com';
+    private array $params = [];
 
     public function __construct(string $apiKey, $apiEndpoint = null)
     {
@@ -33,29 +31,189 @@ public function __construct(string $apiKey, $apiEndpoint = null)
                 'Content-Type' => 'application/json'
             ]
         ]);
+
+        $this->setDefaultParams();
     }
 
     public function getApiEndpoint(): string
     {
         return $this->apiEndpoint;
     }
 
-    // todo: mocked endpoint tests
-    protected function get($endpoint, $params = []): Response
+    protected function get($endpoint): Response
     {
-        $params['apiKey'] = $this->apiKey;
-
         try {
             return $this->client->get('/' . config('odds-api.version') . $endpoint, [
-                'query' => $params
+                'query' => $this->params
             ]);
         } catch (RequestException $e) {
             throw new \RuntimeException('Request failed: ' . $e->getMessage());
         }
     }
 
-    protected function decodeResponse($response)
+    private function setDefaultParams(): void
+    {
+        $this->params = [
+            'api_key' => $this->apiKey,
+            'regions' => config('odds-api.default_region'),
+            'oddsFormat' => config('odds-api.default_odds_format')
+        ];
+    }
+
+    /**
+     * @return Response
+     */
+    public function getSports(): Response
+    {
+        return $this->get('/sports');
+    }
+
+    /**
+     * @param SportsEnum $sport
+     * @return Response
+     */
+    public function getScoresForSport(SportsEnum $sport): Response
+    {
+        return $this->get("/sports/{$sport->value}/scores");
+    }
+
+    /**
+     * @param SportsEnum $sport
+     * @return Response
+     */
+    public function getOddsForSport(SportsEnum $sport): Response
+    {
+        return $this->get("/sports/$sport->value/odds");
+    }
+
+    /**
+     * @param SportsEnum $sport
+     * @param string $event
+     * @return Response
+     */
+    public function getOddsForEvent(SportsEnum $sport, string $event): Response
+    {
+        return $this->get("/sports/{$sport->value}/events/{$event}/odds");
+    }
+
+    /**
+     * @param string $regionCode
+     * @return $this
+     */
+    public function setRegion(string $regionCode): self
+    {
+        $this->params['regions'] = $regionCode;
+
+        return $this;
+    }
+
+    /**
+     * https://the-odds-api.com/sports-odds-data/betting-markets.html
+     *
+     * @param mixed $markets
+     * @return $this
+     */
+    public function setMarkets(mixed $markets): self
+    {
+        if (is_array($markets)) {
+            $marketString = http_build_query($markets, '', ',');
+        }
+
+        $this->params['markets'] = $marketString ?? $markets;
+
+        return $this;
+    }
+
+    /**
+     * https://the-odds-api.com/sports-odds-data/bookmaker-apis.html
+     *
+     * @param mixed $bookmakers
+     * @return $this
+     */
+    public function setBookmakers(mixed $bookmakers): self
+    {
+        if (is_array($bookmakers)) {
+            $bookmakerString = http_build_query($bookmakers, '', ',');
+        }
+
+        $this->params['markets'] = $bookmakerString ?? $bookmakers;
+
+        return $this;
+    }
+
+    /**
+     * @param string $eventId
+     * @return $this
+     */
+    public function setEvent(string $eventId): self
+    {
+        $this->params['eventIds'] = $eventId;
+
+        return $this;
+    }
+
+    /**
+     * decimal or american
+     *
+     * @param string $format
+     * @return $this
+     */
+    public function oddsFormat(string $format): self
+    {
+        $this->params['oddsFormat'] = $format;
+
+        return $this;
+    }
+
+    /**
+     * Format of returned timestamps. Can be iso (ISO8601) or unix timestamp (seconds since epoch)
+     *
+     * @param string $dateFormat
+     * @return $this
+     */
+    public function dateFormat(string $dateFormat): self
     {
-        return json_decode($response->getBody(), true);
+        $this->params['dateForm'] = $dateFormat;
+
+        return $this;
+    }
+
+    /**
+     * Filters the response to show events that commence on and after this parameter. Values are in ISO8601 format
+     *
+     * @param string $time
+     * @return $this
+     */
+    public function commenceTimeFrom(string $time): self
+    {
+        $this->params['commenceTimeFrom'] = $time;
+
+        return $this;
+    }
+
+    /**
+     * Filters the response to show events that commence on and before this parameter. Values are in ISO8601 format
+     *
+     * @param string $time
+     * @return $this
+     */
+    public function commenceTimeTo(string $time): self
+    {
+        $this->params['commenceTimeTo'] = $time;
+
+        return $this;
+    }
+
+    /**
+     * Additional params in case API is not caught up with the latest API
+     *
+     * @param array $params
+     * @return self
+     */
+    public function addParams(array $params): self
+    {
+        $this->params = array_merge_recursive($this->params, $params);
+
+        return $this;
     }
 }