Add universal parameters

CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## v0.6.0-beta
+
+Added universal parameters to all endpoints with the ability to change format to CSV and HTML (beta).
+
 ## v0.5.0-beta
 
 Added indices->quotes to parallelize and speed up multiple index quotes.

README.md

@@ -72,6 +72,21 @@ $status = $client->utilities->api_status();
 $headers = $client->utilities->headers();
 ```
 
+### Universal Parameters
+
+All endpoints (other than utilities) supports universal parameters. 
+
+For instance, you can change the format to CSV
+
+```
+$option_chain = $client->options->option_chain(
+    symbol: 'AAPL',
+    expiration: '2025-01-17',
+    side: Side::CALL,
+    parameters: new Parameters(format: Format::CSV),
+);
+```
+
 ## Testing
 
 ```bash

src/ClientBase.php

@@ -31,7 +31,7 @@ public function setGuzzle(GuzzleClient $guzzleClient): void
     /**
      * @throws \Throwable
      */
-    public function executeInParallel(array $calls): array
+    public function execute_in_parallel(array $calls): array
     {
         $promises = [];
         foreach ($calls as $call) {
@@ -59,8 +59,9 @@ protected function async($method, array $arguments = []): PromiseInterface
     public function execute($method, array $arguments = []): object
     {
         try {
+            $format = array_key_exists('format', $arguments) ? $arguments['format'] : 'json';
             $response = $this->guzzle->get($method, [
-                'headers' => $this->headers(),
+                'headers' => $this->headers($format),
                 'query'   => $arguments,
             ]);
         } catch (\GuzzleHttp\Exception\ClientException $e) {
@@ -70,22 +71,37 @@ public function execute($method, array $arguments = []): object
             };
         }
 
-        $json_response = (string)$response->getBody();
+        switch ($format) {
+            case 'csv':
+            case 'html':
+                $object_response = (object)array(
+                    $arguments['format'] => (string)$response->getBody()
+                );
+                break;
 
-        $response = json_decode($json_response);
+            case 'json':
+            default:
+                $json_response = (string)$response->getBody();
 
-        if (isset($response->s) && $response->s === 'error') {
-            throw new ApiException(message: $response->errmsg, response: $response);
+                $object_response = json_decode($json_response);
+
+                if (isset($object_response->s) && $object_response->s === 'error') {
+                    throw new ApiException(message: $object_response->errmsg, response: $response);
+                }
         }
 
-        return $response;
+        return $object_response;
     }
 
-    protected function headers(): array
+    protected function headers(string $format = 'json'): array
     {
         return [
             'Host'          => self::API_HOST,
-            'Accept'        => 'application/json',
+            'Accept'        => match ($format) {
+                'json' => 'application/json',
+                'csv' => 'text/csv',
+                'html' => 'text/html',
+            },
             'Authorization' => "Bearer $this->token",
         ];
     }

src/Endpoints/Indices.php

@@ -4,14 +4,18 @@
 
 use GuzzleHttp\Exception\GuzzleException;
 use MarketDataApp\Client;
+use MarketDataApp\Endpoints\Requests\Parameters;
 use MarketDataApp\Endpoints\Responses\Indices\Candles;
 use MarketDataApp\Endpoints\Responses\Indices\Quote;
 use MarketDataApp\Endpoints\Responses\Indices\Quotes;
 use MarketDataApp\Exceptions\ApiException;
+use MarketDataApp\Traits\UniversalParameters;
 
 class Indices
 {
 
+    use UniversalParameters;
+
     private Client $client;
     public const BASE_URL = "v1/indices/";
 
@@ -28,32 +32,40 @@ public function __construct($client)
      *
      * @param bool $fifty_two_week Enable the output of 52-week high and 52-week low data in the quote output.
      *
+     * @param Parameters|null $parameters Universal parameters for all methods (such as format).
+     *
      * @throws GuzzleException|ApiException
      */
-    public function quote(string $symbol, bool $fifty_two_week = false): Quote
-    {
-        return new Quote($this->client->execute(self::BASE_URL . "quotes/$symbol", ['52week' => $fifty_two_week]));
+    public function quote(
+        string $symbol,
+        bool $fifty_two_week = false,
+        ?Parameters $parameters = null
+    ): Quote {
+        return new Quote($this->execute("quotes/$symbol", ['52week' => $fifty_two_week], $parameters));
     }
 
 
-
     /**
      * Get a real-time price quote for a multiple indices by doing parallel requests.
      *
      * @param array $symbols The ticker symbols to return in the response.
      * @param bool $fifty_two_week Enable the output of 52-week high and 52-week low data in the quote output.
+     * @param Parameters|null $parameters Universal parameters for all methods (such as format).
      *
      * @throws \Throwable
      */
-    public function quotes(array $symbols, bool $fifty_two_week = false): Quotes
-    {
+    public function quotes(
+        array $symbols,
+        bool $fifty_two_week = false,
+        ?Parameters $parameters = null
+    ): Quotes {
         // Execute standard quotes in parallel
         $calls = [];
         foreach ($symbols as $symbol) {
-            $calls[] = [self::BASE_URL . "quotes/$symbol", ['52week' => $fifty_two_week]];
+            $calls[] = ["quotes/$symbol", ['52week' => $fifty_two_week]];
         }
 
-        return new Quotes($this->client->executeInParallel($calls));
+        return new Quotes($this->execute_in_parallel($calls, $parameters));
     }
 
     /**
@@ -78,17 +90,19 @@ public function quotes(array $symbols, bool $fifty_two_week = false): Quotes
      * @param int|null $countback Will fetch a number of candles before (to the left of) to. If you use from, countback
      * is not required.
      *
+     * @param Parameters|null $parameters Universal parameters for all methods (such as format).
+     *
      * @throws ApiException|GuzzleException
      */
     public function candles(
         string $symbol,
         string $from,
         string $to = null,
         string $resolution = 'D',
-        int $countback = null
+        int $countback = null,
+        ?Parameters $parameters = null
     ): Candles {
-        return new Candles($this->client->execute(self::BASE_URL . "candles/{$resolution}/{$symbol}/",
-            compact('from', 'to', 'countback')
-        ));
+        return new Candles($this->execute("candles/{$resolution}/{$symbol}/", compact('from', 'to', 'countback'),
+            $parameters));
     }
 }

src/Endpoints/Markets.php

@@ -4,12 +4,16 @@
 
 use GuzzleHttp\Exception\GuzzleException;
 use MarketDataApp\Client;
+use MarketDataApp\Endpoints\Requests\Parameters;
 use MarketDataApp\Endpoints\Responses\Markets\Statuses;
 use MarketDataApp\Exceptions\ApiException;
+use MarketDataApp\Traits\UniversalParameters;
 
 class Markets
 {
 
+    use UniversalParameters;
+
     private Client $client;
     public const BASE_URL = "v1/markets/";
 
@@ -37,16 +41,19 @@ public function __construct($client)
      * @param int|null $countback Countback will fetch a number of dates before to If you use from, countback is not
      * required.
      *
+     * @param Parameters|null $parameters Universal parameters for all methods (such as format).
+     *
      * @throws GuzzleException|ApiException
      */
     public function status(
         string $country = "US",
         string $date = null,
         string $from = null,
         string $to = null,
-        int $countback = null
+        int $countback = null,
+        ?Parameters $parameters = null
     ): Statuses {
-        return new Statuses($this->client->execute(self::BASE_URL . "status/",
-            compact('country', 'date', 'from', 'to', 'countback')));
+        return new Statuses($this->execute("status/",
+            compact('country', 'date', 'from', 'to', 'countback'), $parameters));
     }
 }

src/Endpoints/MutualFunds.php

@@ -4,12 +4,16 @@
 
 use GuzzleHttp\Exception\GuzzleException;
 use MarketDataApp\Client;
+use MarketDataApp\Endpoints\Requests\Parameters;
 use MarketDataApp\Endpoints\Responses\MutualFunds\Candles;
 use MarketDataApp\Exceptions\ApiException;
+use MarketDataApp\Traits\UniversalParameters;
 
 class MutualFunds
 {
 
+    use UniversalParameters;
+
     private Client $client;
     public const BASE_URL = "v1/funds/";
 
@@ -40,6 +44,8 @@ public function __construct($client)
      * @param int|null $countback Will fetch a number of candles before (to the left of) to. If you use from, countback
      * is not required.
      *
+     * @param Parameters|null $parameters Universal parameters for all methods (such as format).
+     *
      * @return Candles
      * @throws GuzzleException|ApiException
      */
@@ -49,9 +55,10 @@ public function candles(
         string $to = null,
         string $resolution = 'D',
         int $countback = null,
+        ?Parameters $parameters = null
     ): Candles {
-        return new Candles($this->client->execute(self::BASE_URL . "candles/{$resolution}/{$symbol}/",
-            compact('from', 'to', 'countback')
+        return new Candles($this->execute("candles/{$resolution}/{$symbol}/",
+            compact('from', 'to', 'countback'), $parameters
         ));
     }
 }