Merge pull request #2 from MarketDataApp/add-quotes

Add quotes

Author: KerryJones

CHANGELOG.md

@@ -1,4 +1,12 @@
 # Changelog
 
-All notable changes to `marketdataapp-sdk-php` will be documented in this file.
+## v0.2.0-alpha
 
+- Completed Indices endpoints.
+- Added Stocks endpoints: quote, quotes, bulkQuotes, candles, bulkCandles.
+- Added custom ApiException class to handle status = 'error' messages.
+- Moved Responses to new directory.
+
+## v0.1.0-alpha
+
+- Initial release with single Indices > quote endpoint.

README.md

@@ -21,13 +21,20 @@ composer require MarketDataApp/sdk-php
 
 ```php
 $client = new MarketDataApp\Client();
+
+// Indices
 $quote = $client->indices->quote('DJI');
-$candles = $this->client->indices->candles(
+$candles = $client->indices->candles(
     symbol: "DJI",
     from: Carbon::parse('2022-09-01'),
     to: Carbon::parse('2022-09-05'),
     resolution: 'D'
 );
+
+// Stocks
+$quote = $client->stocks->quote('AAPL');
+$quotes = $client->stocks->quotes(['AAPL', 'NFLX']);
+$bulk_quotes = $client->stocks->bulk_quotes(['AAPL', 'NFLX']);
 ```
 
 ## Testing

src/Client.php

@@ -3,6 +3,7 @@
 namespace MarketDataApp;
 
 use MarketDataApp\Endpoints\Indices;
+use MarketDataApp\Endpoints\Stocks;
 
 class Client extends ClientBase
 {
@@ -13,10 +14,16 @@ class Client extends ClientBase
      */
     public Indices $indices;
 
+    /**
+     * Stock endpoints include numerous fundamental, technical, and pricing data.
+     */
+    public Stocks $stocks;
+
     public function __construct($token)
     {
         parent::__construct($token);
 
         $this->indices = new Indices($this);
+        $this->stocks = new Stocks($this);
     }
 }

src/ClientBase.php

@@ -6,6 +6,7 @@
 use GuzzleHttp\Exception\GuzzleException;
 use GuzzleHttp\Promise;
 use GuzzleHttp\Promise\PromiseInterface;
+use MarketDataApp\Exceptions\ApiException;
 
 abstract class ClientBase
 {
@@ -53,6 +54,7 @@ protected function async($method, array $arguments = []): PromiseInterface
 
     /**
      * @throws GuzzleException
+     * @throws ApiException
      */
     public function execute($method, array $arguments = []): object
     {
@@ -62,7 +64,13 @@ public function execute($method, array $arguments = []): object
         ]);
         $json_response = (string)$response->getBody();
 
-        return json_decode($json_response);
+        $response = json_decode($json_response);
+
+        if($response->s === 'error') {
+            throw new ApiException(message: $response->errmsg, response: $response);
+        }
+
+        return $response;
     }
 
     protected function headers(): array

src/Endpoints/Indices.php

@@ -5,8 +5,9 @@
 use Carbon\Carbon;
 use GuzzleHttp\Exception\GuzzleException;
 use MarketDataApp\Client;
-use MarketDataApp\Endpoints\Responses\IndicesCandles;
-use MarketDataApp\Endpoints\Responses\IndicesQuote;
+use MarketDataApp\Endpoints\Responses\Indices\Candles;
+use MarketDataApp\Endpoints\Responses\Indices\Quote;
+use MarketDataApp\Exceptions\ApiException;
 
 class Indices
 {
@@ -20,41 +21,46 @@ public function __construct($client)
     }
 
     /**
+     * Get a real-time quote for an index.
+     *
      * @param string $symbol The index symbol, without any leading or trailing index identifiers. For example, use DJI
      * do not use $DJI, ^DJI, .DJI, DJI.X, etc.
-     * @throws GuzzleException
+     * @throws GuzzleException|ApiException
      */
-    public function quote(string $symbol): IndicesQuote
+    public function quote(string $symbol, bool $fifty_two_week = false): Quote
     {
-        return new IndicesQuote($this->client->execute(self::BASE_URL . "quotes/{$symbol}"));
+        return new Quote($this->client->execute(self::BASE_URL . "quotes/{$symbol}", ['52week' => $fifty_two_week]));
     }
 
     /**
+     * Get historical price candles for an index.
+     *
      * @param string $symbol The index symbol, without any leading or trailing index identifiers. For example, use DJI
      * do not use $DJI, ^DJI, .DJI, DJI.X, etc.
+     *
      * @param Carbon $from The leftmost candle on a chart (inclusive). If you use countback, to is not required.
-     * Accepted timestamp inputs: ISO 8601, unix, spreadsheet.
-     * @param Carbon|null $to The rightmost candle on a chart (inclusive). Accepted timestamp inputs: ISO 8601, unix,
-     * spreadsheet.
+     * @param Carbon|null $to The rightmost candle on a chart (inclusive).
      * @param string $resolution The duration of each candle.
      * Minutely Resolutions: (minutely, 1, 3, 5, 15, 30, 45, ...) Hourly Resolutions: (hourly, H, 1H, 2H, ...)
      * Daily Resolutions: (daily, D, 1D, 2D, ...)
      * Weekly Resolutions: (weekly, W, 1W, 2W, ...)
      * Monthly Resolutions: (monthly, M, 1M, 2M, ...)
      * Yearly Resolutions:(yearly, Y, 1Y, 2Y, ...)
+     *
      * @param int|null $countback Will fetch a number of candles before (to the left of) to. If you use from, countback
      * is not required.
-     * @return IndicesCandles
-     * @throws GuzzleException
+     *
+     * @return Candles
+     * @throws GuzzleException|ApiException
      */
     public function candles(
         string $symbol,
         Carbon $from,
         Carbon $to = null,
         string $resolution = 'D',
         int $countback = null
-    ): IndicesCandles {
-        return new IndicesCandles($this->client->execute(self::BASE_URL . "candles/{$resolution}/{$symbol}/",
+    ): Candles {
+        return new Candles($this->client->execute(self::BASE_URL . "candles/{$resolution}/{$symbol}/",
             compact('from', 'to', 'countback')
         ));
     }

src/Endpoints/Responses/IndicesCandle.php …c/Endpoints/Responses/Indices/Candle.phpsrc/Endpoints/Responses/IndicesCandle.php renamed to src/Endpoints/Responses/Indices/Candle.php src/Endpoints/Responses/IndicesCandle.php renamed to src/Endpoints/Responses/Indices/Candle.php

@@ -1,10 +1,10 @@
 <?php
 
-namespace MarketDataApp\Endpoints\Responses;
+namespace MarketDataApp\Endpoints\Responses\Indices;
 
 use Carbon\Carbon;
 
-class IndicesCandle
+class Candle
 {
 
     // Open price.

src/Endpoints/Responses/Indices/Candles.php

@@ -0,0 +1,50 @@
+<?php
+
+namespace MarketDataApp\Endpoints\Responses\Indices;
+
+use Carbon\Carbon;
+
+class Candles
+{
+
+    /**
+     * - Will always be ok when there is data for the candles requested.
+     * - Status will be no_data if no candles are found for the request.
+     * - Status will be error if the request produces an error response.
+     */
+    public string $status;
+
+    /** @var Candle[] $candles */
+    public array $candles = [];
+
+    // Unix time of the next quote if there is no data in the requested period, but there is data in a subsequent
+    // period.
+    public int $next_time;
+
+    /**
+     * @throws \Exception
+     */
+    public function __construct(object $response)
+    {
+        // Convert the response to this object.
+        $this->status = $response->s;
+
+        switch ($this->status) {
+            case 'ok':
+                for ($i = 0; $i < count($response->o); $i++) {
+                    $this->candles[] = new Candle(
+                        $response->o[$i],
+                        $response->h[$i],
+                        $response->l[$i],
+                        $response->c[$i],
+                        Carbon::parse($response->t[$i]),
+                    );
+                }
+                break;
+
+            case 'no_data' && isset($response->nextTime):
+                $this->next_time = $response->nextTime;
+                break;
+        }
+    }
+}

src/Endpoints/Responses/IndicesQuote.php src/Endpoints/Responses/Indices/Quote.phpsrc/Endpoints/Responses/IndicesQuote.php renamed to src/Endpoints/Responses/Indices/Quote.php

@@ -1,10 +1,10 @@
 <?php
 
-namespace MarketDataApp\Endpoints\Responses;
+namespace MarketDataApp\Endpoints\Responses\Indices;
 
 use Carbon\Carbon;
 
-class IndicesQuote
+class Quote
 {
 
     // Will always be ok when there is data for the symbol requested.
@@ -34,14 +34,15 @@ class IndicesQuote
 
     public function __construct(object $response)
     {
-        // Convert the response to this object.
         $this->status = $response->s;
-        $this->symbol = $response->symbol[0];
-        $this->last = $response->last[0];
-        $this->change = $response->change[0];
-        $this->change_percent = $response->changepct[0];
-        $this->fifty_two_week_high = $response->{'52weekHigh'}[0];
-        $this->fifty_two_week_low = $response->{'52weekLow'}[0];
-        $this->updated = Carbon::parse($response->updated);
+        if ($this->status === "ok") {
+            $this->symbol = $response->symbol[0];
+            $this->last = $response->last[0];
+            $this->change = $response->change[0];
+            $this->change_percent = $response->changepct[0];
+            $this->fifty_two_week_high = $response->{'52weekHigh'}[0];
+            $this->fifty_two_week_low = $response->{'52weekLow'}[0];
+            $this->updated = Carbon::parse($response->updated);
+        }
     }
 }

src/Endpoints/Responses/IndicesCandles.php

@@ -0,0 +1,38 @@
+<?php
+
+namespace MarketDataApp\Endpoints\Responses\Stocks;
+
+use Carbon\Carbon;
+
+class BulkCandles
+{
+
+    // Will always be ok when there is data for the candles requested.
+    public string $status;
+
+    // The ticker symbols of the stock.
+    public array $symbols = [];
+
+    /** @var Candle[] $candles */
+    public array $candles = [];
+
+    public function __construct(object $response)
+    {
+        // Convert the response to this object.
+        $this->status = $response->s;
+
+        if ($this->status === 'ok') {
+            $this->symbols = array_map('trim', explode(',', $response->symbol));
+            for ($i = 0; $i < count($response->o); $i++) {
+                $this->candles[] = new Candle(
+                    $response->o[$i],
+                    $response->h[$i],
+                    $response->l[$i],
+                    $response->c[$i],
+                    $response->v[$i],
+                    Carbon::parse($response->t[$i]),
+                );
+            }
+        }
+    }
+}