Skip to content

Commit

Permalink
Add updated doc strings for php doc
Browse files Browse the repository at this point in the history
  • Loading branch information
@KerryJones
KerryJones committed Sep 3, 2024
1 parent 0b4b4bd commit bf4c3d8
Show file tree
Hide file tree
Showing 56 changed files with 1,897 additions and 552 deletions.
25 changes: 25 additions & 0 deletions src/Client.php
View file
Original file line number Diff line number Diff line change
Expand Up @@ -9,17 +9,27 @@
use MarketDataApp\Endpoints\Stocks;
use MarketDataApp\Endpoints\Utilities;

/**
* Client class for the Market Data API.
*
* This class provides access to various endpoints of the Market Data API,
* including indices, stocks, options, markets, mutual funds, and utilities.
*/
class Client extends ClientBase
{

/**
* The index endpoints provided by the Market Data API offer access to both real-time and historical data related to
* financial indices. These endpoints are designed to cater to a wide range of financial data needs.
*
* @var Indices
*/
public Indices $indices;

/**
* Stock endpoints include numerous fundamental, technical, and pricing data.
*
* @var Stocks
*/
public Stocks $stocks;

Expand All @@ -28,25 +38,40 @@ class Client extends ClientBase
* around options data. These endpoints are designed to be flexible and robust, supporting both real-time
* and historical data queries. They accommodate a wide range of optional parameters for detailed data
* retrieval, making the Market Data API a versatile tool for options traders and financial analysts.
*
* @var Options
*/
public Options $options;

/**
* The Markets endpoints provide reference and status data about the markets covered by Market Data.
*
* @var Markets
*/
public Markets $markets;

/**
* The mutual funds endpoints offer access to historical pricing data for mutual funds.
*
* @var MutualFunds
*/
public MutualFunds $mutual_funds;

/**
* These endpoints are designed to assist with API-related service issues, including checking the online status and
* uptime.
*
* @var Utilities
*/
public Utilities $utilities;

/**
* Constructor for the Client class.
*
* Initializes all endpoint classes with the provided API token.
*
* @param string $token The API token for authentication.
*/
public function __construct($token)
{
parent::__construct($token);
Expand Down
56 changes: 56 additions & 0 deletions src/ClientBase.php
View file
Original file line number Diff line number Diff line change
Expand Up @@ -8,27 +8,62 @@
use GuzzleHttp\Promise\PromiseInterface;
use MarketDataApp\Exceptions\ApiException;

/**
* Abstract base class for Market Data API client.
*
* This class provides core functionality for API communication,
* including parallel execution, async requests, and response handling.
*/
abstract class ClientBase
{

/**
* The base URL for the Market Data API.
*/
public const API_URL = "https://api.marketdata.app/";

/**
* The host for the Market Data API.
*/
public const API_HOST = "api.marketdata.app";

/**
* @var GuzzleClient The Guzzle HTTP client instance.
*/
protected GuzzleClient $guzzle;

/**
* @var string The API token for authentication.
*/
protected string $token;

/**
* ClientBase constructor.
*
* @param string $token The API token for authentication.
*/
public function __construct(string $token)
{
$this->guzzle = new GuzzleClient(['base_uri' => self::API_URL]);
$this->token = $token;
}

/**
* Set a custom Guzzle client.
*
* @param GuzzleClient $guzzleClient The Guzzle client to use.
*/
public function setGuzzle(GuzzleClient $guzzleClient): void
{
$this->guzzle = $guzzleClient;
}

/**
* Execute multiple API calls in parallel.
*
* @param array $calls An array of method calls, each containing the method name and arguments.
*
* @return array An array of decoded JSON responses.
* @throws \Throwable
*/
public function execute_in_parallel(array $calls): array
Expand All @@ -44,6 +79,14 @@ public function execute_in_parallel(array $calls): array
}, $responses);
}

/**
* Perform an asynchronous API request.
*
* @param string $method The API method to call.
* @param array $arguments The arguments for the API call.
*
* @return PromiseInterface
*/
protected function async($method, array $arguments = []): PromiseInterface
{
return $this->guzzle->getAsync($method, [
Expand All @@ -53,6 +96,12 @@ protected function async($method, array $arguments = []): PromiseInterface
}

/**
* Execute a single API request.
*
* @param string $method The API method to call.
* @param array $arguments The arguments for the API call.
*
* @return object The API response as an object.
* @throws GuzzleException
* @throws ApiException
*/
Expand Down Expand Up @@ -93,6 +142,13 @@ public function execute($method, array $arguments = []): object
return $object_response;
}

/**
* Generate headers for API requests.
*
* @param string $format The desired response format (json, csv, or html).
*
* @return array An array of headers.
*/
protected function headers(string $format = 'json'): array
{
return [
Expand Down
60 changes: 37 additions & 23 deletions src/Endpoints/Indices.php
View file
Original file line number Diff line number Diff line change
Expand Up @@ -11,14 +11,25 @@
use MarketDataApp\Exceptions\ApiException;
use MarketDataApp\Traits\UniversalParameters;

/**
* Indices class for handling index-related API endpoints.
*/
class Indices
{

use UniversalParameters;

/** @var Client The Market Data API client instance. */
private Client $client;

/** @var string The base URL for index endpoints. */
public const BASE_URL = "v1/indices/";

/**
* Indices constructor.
*
* @param Client $client The Market Data API client instance.
*/
public function __construct($client)
{
$this->client = $client;
Expand All @@ -27,13 +38,15 @@ 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.
* @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 bool $fifty_two_week Enable the output of 52-week high and 52-week low data in the quote output.
* @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).
* @param Parameters|null $parameters Universal parameters for all methods (such as format).
*
* @return Quote
* @throws GuzzleException|ApiException
*/
public function quote(
Expand All @@ -44,14 +57,15 @@ public function 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.
* Get real-time price quotes for 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).
* @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).
*
* @return Quotes
* @throws \Throwable
*/
public function quotes(
Expand All @@ -71,27 +85,27 @@ public function quotes(
/**
* 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 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 string $from The leftmost candle on a chart (inclusive). If you use countback, to is not required.
* Accepted timestamp inputs: ISO 8601, unix, spreadsheet.
* @param string $from The leftmost candle on a chart (inclusive). If you use countback, to is not
* required. Accepted timestamp inputs: ISO 8601, unix, spreadsheet.
*
* @param string|null $to The rightmost candle on a chart (inclusive). Accepted timestamp inputs: ISO 8601, unix,
* spreadsheet.
* @param string|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 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.
* @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 ApiException|GuzzleException
*/
public function candles(
Expand Down
35 changes: 25 additions & 10 deletions src/Endpoints/Markets.php
View file
Original file line number Diff line number Diff line change
Expand Up @@ -9,40 +9,55 @@
use MarketDataApp\Exceptions\ApiException;
use MarketDataApp\Traits\UniversalParameters;

/**
* Markets class for handling market-related API endpoints.
*/
class Markets
{

use UniversalParameters;

/** @var Client The Market Data API client instance. */
private Client $client;

/** @var string The base URL for market endpoints. */
public const BASE_URL = "v1/markets/";

/**
* Markets constructor.
*
* @param Client $client The Market Data API client instance.
*/
public function __construct($client)
{
$this->client = $client;
}

/**
* Get the market status for a specific country and date range.
*
* Get the past, present, or future status for a stock market. The endpoint will respond with "open" for trading
* days or "closed" for weekends or market holidays.
*
* @param string $country The country. Use the two-digit ISO 3166 country code. If no country is specified, US will
* be assumed. Only countries that Market Data supports for stock price data are available (currently only the
* United States).
* @param string $country The country. Use the two-digit ISO 3166 country code. If no country is
* specified, US will be assumed. Only countries that Market Data supports for
* stock price data are available (currently only the United States).
*
* @param string|null $date Consult whether the market was open or closed on the specified date. Accepted timestamp
* inputs: ISO 8601, unix, spreadsheet.
* @param string|null $date Consult whether the market was open or closed on the specified date. Accepted
* timestamp inputs: ISO 8601, unix, spreadsheet.
*
* @param string|null $from The earliest date (inclusive). If you use countback, from is not required. Accepted
* timestamp inputs: ISO 8601, unix, spreadsheet.
* @param string|null $from The earliest date (inclusive). If you use countback, from is not required.
* Accepted timestamp inputs: ISO 8601, unix, spreadsheet.
*
* @param string|null $to The last date (inclusive). Accepted timestamp inputs: ISO 8601, unix, spreadsheet.
* @param string|null $to The last date (inclusive). Accepted timestamp inputs: ISO 8601, unix,
* spreadsheet.
*
* @param int|null $countback Countback will fetch a number of dates before to If you use from, countback is not
* required.
* @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).
*
* @return Statuses
* @throws GuzzleException|ApiException
*/
public function status(
Expand Down
Loading

0 comments on commit bf4c3d8

Please sign in to comment.