Merge pull request #1 from MarketDataApp/add-indices

Add Indices > Candles

Author: KerryJones

README.md

@@ -5,7 +5,7 @@
 [![Codecov](https://codecov.io/gh/MarketDataApp/sdk-php/graph/badge.svg?token=5W2IB9F6RU)](https://codecov.io/github/MarketDataApp/sdk-php)
 [![Total Downloads](https://img.shields.io/packagist/dt/MarketDataApp/sdk-php.svg?style=flat-square)](https://packagist.org/packages/MarketDataApp/sdk-php)
 
-This is an official PHP SDK for Market Data. It provides developers with a powerful, easy-to-use interface to obtain
+This is the official PHP SDK for [Market Data](https://marketdata.app). It provides developers with a powerful, easy-to-use interface to obtain
 real-time and historical financial data. Ideal for building financial applications, trading bots, and investment
 strategies.
 
@@ -21,7 +21,13 @@ composer require MarketDataApp/sdk-php
 
 ```php
 $client = new MarketDataApp\Client();
-$quote = $client->indices->quote('AAPL');
+$quote = $client->indices->quote('DJI');
+$candles = $this->client->indices->candles(
+    symbol: "DJI",
+    from: Carbon::parse('2022-09-01'),
+    to: Carbon::parse('2022-09-05'),
+    resolution: 'D'
+);
 ```
 
 ## Testing

src/Endpoints/Indices.php

@@ -2,8 +2,10 @@
 
 namespace MarketDataApp\Endpoints;
 
+use Carbon\Carbon;
 use GuzzleHttp\Exception\GuzzleException;
 use MarketDataApp\Client;
+use MarketDataApp\Endpoints\Responses\IndicesCandles;
 use MarketDataApp\Endpoints\Responses\IndicesQuote;
 
 class Indices
@@ -26,4 +28,34 @@ public function quote(string $symbol): IndicesQuote
     {
         return new IndicesQuote($this->client->execute(self::BASE_URL . "quotes/{$symbol}"));
     }
+
+    /**
+     * @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 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
+     */
+    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}/",
+            compact('from', 'to', 'countback')
+        ));
+    }
 }

src/Endpoints/Responses/IndicesCandle.php

@@ -0,0 +1,33 @@
+<?php
+
+namespace MarketDataApp\Endpoints\Responses;
+
+use Carbon\Carbon;
+
+class IndicesCandle
+{
+
+    // Open price.
+    public string $open;
+
+    // High price.
+    public float $high;
+
+    // Low price.
+    public float $low;
+
+    // Close price.
+    public float $close;
+
+    // Candle time (Unix timestamp, UTC). Daily, weekly, monthly, yearly candles are returned without times.
+    public Carbon $timestamp;
+
+    public function __construct(float $open, float $high, float $low, float $close, Carbon $timestamp)
+    {
+        $this->open = $open;
+        $this->high = $high;
+        $this->low = $low;
+        $this->close = $close;
+        $this->timestamp = $timestamp;
+    }
+}

src/Endpoints/Responses/IndicesCandles.php

@@ -0,0 +1,30 @@
+<?php
+
+namespace MarketDataApp\Endpoints\Responses;
+
+use Carbon\Carbon;
+
+class IndicesCandles
+{
+    // Will always be ok when there is data for the candles requested.
+    public string $status;
+
+    /** @var IndicesCandle[] $candles */
+    public array $candles;
+
+    public function __construct(object $response)
+    {
+        // Convert the response to this object.
+        $this->status = $response->s;
+
+        for($i = 0; $i < count($response->o); $i++) {
+            $this->candles[] = new IndicesCandle(
+                $response->o[$i],
+                $response->h[$i],
+                $response->l[$i],
+                $response->c[$i],
+                Carbon::parse($response->t[$i]),
+            );
+        }
+    }
+}

tests/IndicesTest.php

@@ -10,6 +10,8 @@
 use GuzzleHttp\Psr7\Request;
 use GuzzleHttp\Psr7\Response;
 use MarketDataApp\Client;
+use MarketDataApp\Endpoints\Responses\IndicesCandle;
+use MarketDataApp\Endpoints\Responses\IndicesCandles;
 use MarketDataApp\Endpoints\Responses\IndicesQuote;
 use PHPUnit\Framework\TestCase;
 
@@ -39,7 +41,7 @@ public function testIndicesQuote_success()
         ];
         $this->setMockResponses([new Response(200, [], json_encode($mocked_response))]);
 
-        $response = $this->client->indices->quote("AAPL");
+        $response = $this->client->indices->quote("DJI");
         $this->assertInstanceOf(IndicesQuote::class, $response);
         $this->assertEquals($mocked_response['s'], $response->status);
         $this->assertEquals($mocked_response['symbol'][0], $response->symbol);
@@ -51,6 +53,40 @@ public function testIndicesQuote_success()
         $this->assertEquals(Carbon::parse($mocked_response['updated']), $response->updated);
     }
 
+    public function testIndicesCandles_fromTo_success()
+    {
+        $mocked_response = [
+            's' => 'ok',
+            'c' => [22.84, 23.93, 21.95, 21.44, 21.15],
+            'h' => [23.27, 24.68, 23.92, 22.66, 22.58],
+            'l' => [22.26, 22.67, 21.68, 21.44, 20.76],
+            'o' => [22.41, 24.08, 23.86, 22.06, 21.5],
+            't' => [1659326400, 1659412800, 1659499200, 1659585600, 1659672000]
+        ];
+        $this->setMockResponses([new Response(200, [], json_encode($mocked_response))]);
+
+        $response = $this->client->indices->candles(
+            symbol: "DJI",
+            from: Carbon::parse('2022-09-01'),
+            to: Carbon::parse('2022-09-05'),
+            resolution: 'D'
+        );
+
+        // Verify that the response is an object of the correct type.
+        $this->assertInstanceOf(IndicesCandles::class, $response);
+        $this->assertCount(5, $response->candles);
+
+        // Verify each item in the response is an object of the correct type and has the correct values.
+        for($i = 0; $i < count($response->candles); $i++) {
+            $this->assertInstanceOf(IndicesCandle::class, $response->candles[$i]);
+            $this->assertEquals($mocked_response['c'][$i], $response->candles[$i]->close);
+            $this->assertEquals($mocked_response['h'][$i], $response->candles[$i]->high);
+            $this->assertEquals($mocked_response['l'][$i], $response->candles[$i]->low);
+            $this->assertEquals($mocked_response['o'][$i], $response->candles[$i]->open);
+            $this->assertEquals(Carbon::parse($mocked_response['t'][$i]), $response->candles[$i]->timestamp);
+        }
+    }
+
     public function testExceptionHandling_throwsGuzzleException()
     {
         $this->setMockResponses([