diff --git a/src/Client.php b/src/Client.php index 0c458ee..e08c691 100644 --- a/src/Client.php +++ b/src/Client.php @@ -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; @@ -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); diff --git a/src/ClientBase.php b/src/ClientBase.php index bcd6e7d..d1c0553 100644 --- a/src/ClientBase.php +++ b/src/ClientBase.php @@ -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 @@ -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, [ @@ -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 */ @@ -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 [ diff --git a/src/Endpoints/Indices.php b/src/Endpoints/Indices.php index bde5d6f..96ea2c7 100644 --- a/src/Endpoints/Indices.php +++ b/src/Endpoints/Indices.php @@ -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; @@ -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( @@ -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( @@ -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( diff --git a/src/Endpoints/Markets.php b/src/Endpoints/Markets.php index 1ecb01e..f3dfd9d 100644 --- a/src/Endpoints/Markets.php +++ b/src/Endpoints/Markets.php @@ -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( diff --git a/src/Endpoints/MutualFunds.php b/src/Endpoints/MutualFunds.php index 95be4f6..94bbacf 100644 --- a/src/Endpoints/MutualFunds.php +++ b/src/Endpoints/MutualFunds.php @@ -9,14 +9,25 @@ use MarketDataApp\Exceptions\ApiException; use MarketDataApp\Traits\UniversalParameters; +/** + * MutualFunds class for handling mutual fund-related API endpoints. + */ class MutualFunds { use UniversalParameters; + /** @var Client The Market Data API client instance. */ private Client $client; + + /** @var string The base URL for mutual fund endpoints. */ public const BASE_URL = "v1/funds/"; + /** + * MutualFunds constructor. + * + * @param Client $client The Market Data API client instance. + */ public function __construct($client) { $this->client = $client; @@ -25,24 +36,24 @@ public function __construct($client) /** * Get historical price candles for a mutual fund. * - * @param string $symbol The mutual fund's ticker symbol. + * @param string $symbol The mutual fund's ticker symbol. * - * @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). * diff --git a/src/Endpoints/Options.php b/src/Endpoints/Options.php index 93467ae..85eea74 100644 --- a/src/Endpoints/Options.php +++ b/src/Endpoints/Options.php @@ -16,14 +16,33 @@ use MarketDataApp\Exceptions\ApiException; use MarketDataApp\Traits\UniversalParameters; +/** + * Class Options + * + * Handles API requests related to options data. + */ class Options { use UniversalParameters; + /** + * The MarketDataApp API client instance. + * + * @var Client + */ private Client $client; + + /** + * The base URL for options-related API endpoints. + */ public const BASE_URL = "v1/options/"; + /** + * Options constructor. + * + * @param Client $client The MarketDataApp API client instance. + */ public function __construct($client) { $this->client = $client; @@ -33,17 +52,20 @@ public function __construct($client) * Get a list of current or historical option expiration dates for an underlying symbol. If no optional parameters * are used, the endpoint returns all expiration dates in the option chain. * - * @param string $symbol The underlying ticker symbol for the options chain you wish to lookup. + * @param string $symbol The underlying ticker symbol for the options chain you wish to lookup. * - * @param int|null $strike Limit the lookup of expiration dates to the strike provided. This will cause the endpoint to - * only return expiration dates that include this strike. + * @param int|null $strike Limit the lookup of expiration dates to the strike provided. This will cause + * the endpoint to only return expiration dates that include this strike. * - * @param string|null $date Use to lookup a historical list of expiration dates from a specific previous trading - * day. If date is omitted the expiration dates will be from the current trading day during market hours or from the - * last trading day when the market is closed. Accepted timestamp inputs: ISO 8601, unix, spreadsheet. + * @param string|null $date Use to lookup a historical list of expiration dates from a specific previous + * trading day. If date is omitted the expiration dates will be from the current + * trading day during market hours or from the last trading day when the market + * is closed. Accepted timestamp inputs: ISO 8601, unix, spreadsheet. * * @param Parameters|null $parameters Universal parameters for all methods (such as format). * + * @return Expirations + * * @throws ApiException|GuzzleException */ public function expirations( @@ -57,18 +79,21 @@ public function expirations( } /** - * Generate a properly formatted OCC option symbol based on the user's human-readable description of an option. This endpoint converts text such as "AAPL 7/28/23 $200 Call" to OCC option symbol format: AAPL230728C00200000. + * Generate a properly formatted OCC option symbol based on the user's human-readable description of an option. + * This endpoint converts text such as "AAPL 7/28/23 $200 Call" to OCC option symbol format: AAPL230728C00200000. * - * @param string $input The human-readable string input that contains - * - (1) stock symbol - * - (2) strike - * - (3) expiration date - * - (4) option side (i.e. put or call). + * @param string $input The human-readable string input that contains + * - (1) stock symbol + * - (2) strike + * - (3) expiration date + * - (4) option side (i.e. put or call). * * @param Parameters|null $parameters Universal parameters for all methods (such as format). * * This endpoint will translate the user's input into a valid OCC option symbol. * Example: "AAPL 7/28/23 $200 Call". + * + * @return Lookup */ public function lookup(string $input, ?Parameters $parameters = null): Lookup { @@ -76,19 +101,24 @@ public function lookup(string $input, ?Parameters $parameters = null): Lookup } /** - * Get a list of current or historical options strikes for an underlying symbol. If no optional parameters are used, + * Get a list of current or historical options strikes for an underlying symbol. If no optional parameters are + * used, * the endpoint returns the strikes for every expiration in the chain. * - * @param string $symbol The underlying ticker symbol for the options chain you wish to lookup. + * @param string $symbol The underlying ticker symbol for the options chain you wish to lookup. * - * @param string|null $expiration Limit the lookup of strikes to options that expire on a specific expiration date. + * @param string|null $expiration Limit the lookup of strikes to options that expire on a specific expiration + * date. * - * @param string|null $date Use to lookup a historical list of strikes from a specific previous trading day. If date - * is omitted the expiration dates will be from the current trading day during market hours or from the last trading - * day when the market is closed. Accepted timestamp inputs: ISO 8601, unix, spreadsheet. + * @param string|null $date Use to lookup a historical list of strikes from a specific previous trading + * day. If date is omitted the expiration dates will be from the current trading + * day during market hours or from the last trading day when the market is + * closed. Accepted timestamp inputs: ISO 8601, unix, spreadsheet. * * @param Parameters|null $parameters Universal parameters for all methods (such as format). * + * @return Strikes + * * @throws ApiException|GuzzleException */ public function strikes( @@ -106,22 +136,27 @@ public function strikes( * for extensive filtering of the chain. Use the optionSymbol returned from this endpoint to get quotes, greeks, or * other information using the other endpoints. * - * CAUTION: The from, to, month, year, weekly, monthly, and quarterly filtering parameters are not yet supported for + * CAUTION: The from, to, month, year, weekly, monthly, and quarterly filtering parameters are not yet supported + * for * real-time quotes. If you are requesting a real-time quote you must request a single expiration date or request * all expirations. * - * @param string $symbol The ticker symbol of the underlying asset. + * @param string $symbol The ticker symbol of the underlying asset. * - * @param string|null $date Use to lookup a historical end of day options chain from a specific trading day. If no - * date is specified the chain will be the most current chain available during market hours. When the market is - * closed the chain will be from the last trading day. Accepted timestamp inputs: ISO 8601, unix, spreadsheet. + * @param string|null $date Use to lookup a historical end of day options chain from a + * specific trading day. If no date is specified the chain will be + * the most current chain available during market hours. When the + * market is closed the chain will be from the last trading day. + * Accepted timestamp inputs: ISO 8601, unix, spreadsheet. * * @param string|Expiration $expiration - * - Limits the option chain to a specific expiration date. Accepted date inputs: ISO 8601, unix, spreadsheet. This - * parameter is only required if requesting a quote along with the chain. Accepted timestamp inputs: ISO 8601, unix, - * spreadsheet. + * - Limits the option chain to a specific expiration date. + * Accepted date inputs: ISO 8601, unix, spreadsheet. This + * parameter is only required if requesting a quote along with the + * chain. Accepted timestamp inputs: ISO 8601, unix, spreadsheet. * - * - If omitted the next monthly expiration for real-time quotes or the next monthly expiration relative to the date + * - If omitted the next monthly expiration for real-time quotes or the next monthly expiration relative to the + * date * parameter for historical quotes will be returned. * * - Use the keyword all to return the complete option chain. @@ -130,57 +165,80 @@ public function strikes( * consume your requests very quickly. The full SPX option chain has more than 20,000 contracts. A request is * consumed for each contact you request with a price in the option chain. * - * @param string|null $from Limit the option chain to expiration dates after from (inclusive). Should be combined - * with to create a range. Accepted timestamp inputs: ISO 8601, unix, spreadsheet. - * - * @param string|null $to Limit the option chain to expiration dates before to (not inclusive). Should be combined - * with from to create a range. Accepted timestamp inputs: ISO 8601, unix, spreadsheet. - * - * @param int|null $month Limit the option chain to options that expire in a specific month (1-12). - * - * @param int|null $year Limit the option chain to options that expire in a specific year. - * - * @param bool $weekly Limit the option chain to weekly expirations by setting weekly to true and omitting the - * monthly and quarterly parameters. If set to false, no weekly expirations will be returned. - * - * @param bool $monthly Limit the option chain to standard monthly expirations by setting monthly to true and - * omitting the weekly and quarterly parameters. If set to false, no monthly expirations will be returned. - * - * @param bool $quarterly Limit the option chain to quarterly expirations by setting quarterly to true and omitting - * the weekly and monthly parameters. If set to false, no quarterly expirations will be returned. - * - * @param bool $non_standard Include non-standard contracts by nonstandard to true. If set to false, no non-standard - * options expirations will be returned. If no parameter is provided, the output will default to false. - * - * @param int|null $dte Days to expiry. Limit the option chain to a single expiration date closest to the dte - * provided. Should not be used together with from and to. Take care before combining with weekly, monthly, - * quarterly, since that will limit the expirations dte can return. If you are using the date parameter, dte is - * relative to the date provided. - * - * @param float|null $delta - * - Limit the option chain to a single strike closest to the delta provided. (e.g. .50) - * - Limit the option chain to a specific set of deltas (e.g. .60,.30) - * - Limit the option chain to an open interval of strikes using a logical expression (e.g. >.50) - * - Limit the option chain to a closed interval of strikes by specifying both endpoints. (e.g. .30-.60) + * @param string|null $from Limit the option chain to expiration dates after from + * (inclusive). Should be combined with to create a range. + * Accepted timestamp inputs: ISO 8601, unix, spreadsheet. + * + * @param string|null $to Limit the option chain to expiration dates before to (not + * inclusive). Should be combined with from to create a range. + * Accepted timestamp inputs: ISO 8601, unix, spreadsheet. + * + * @param int|null $month Limit the option chain to options that expire in a specific + * month (1-12). + * + * @param int|null $year Limit the option chain to options that expire in a specific + * year. + * + * @param bool $weekly Limit the option chain to weekly expirations by setting weekly + * to true and omitting the monthly and quarterly parameters. If + * set to false, no weekly expirations will be returned. + * + * @param bool $monthly Limit the option chain to standard monthly expirations by + * setting monthly to true and omitting the weekly and quarterly + * parameters. If set to false, no monthly expirations will be + * returned. + * + * @param bool $quarterly Limit the option chain to quarterly expirations by setting + * quarterly to true and omitting the weekly and monthly + * parameters. If set to false, no quarterly expirations will be + * returned. + * + * @param bool $non_standard Include non-standard contracts by nonstandard to true. If set + * to false, no non-standard options expirations will be returned. + * If no parameter is provided, the output will default to false. + * + * @param int|null $dte Days to expiry. Limit the option chain to a single expiration + * date closest to the dte provided. Should not be used together + * with from and to. Take care before combining with weekly, + * monthly, quarterly, since that will limit the expirations dte + * can return. If you are using the date parameter, dte is + * relative to the date provided. + * + * @param float|null $delta + * - Limit the option chain to a single strike closest to the + * delta provided. (e.g. .50) + * - Limit the option chain to a specific set of deltas (e.g. + * .60,.30) + * - Limit the option chain to an open interval of strikes using a + * logical expression (e.g. >.50) + * - Limit the option chain to a closed interval of strikes by + * specifying both endpoints. (e.g. .30-.60) * * TIP: Filter strikes using the aboslulte value of the delta. The values used will always return both sides of the * chain (e.g. puts & calls). This means you must filter using side to exclude puts or calls. Delta cannot be used * to filter the side of the chain, only the strikes. * - * @param Side|null $side Limit the option chain to either call or put. If omitted, both sides will be returned. + * @param Side|null $side Limit the option chain to either call or put. If omitted, both + * sides will be returned. * - * @param Range $range Limit the option chain to strikes that are in the money, out of the money, at the money, or - * include all. If omitted all options will be returned. + * @param Range $range Limit the option chain to strikes that are in the money, out of + * the money, at the money, or include all. If omitted all options + * will be returned. * - * @param string|null $strike - * - Limit the option chain to options with the specific strike specified. (e.g. 400) - * - Limit the option chain to a specific set of strikes (e.g. 400,405) - * - Limit the option chain to an open interval of strikes using a logical expression (e.g. >400) - * - Limit the option chain to a closed interval of strikes by specifying both endpoints. (e.g. 400-410) + * @param string|null $strike + * - Limit the option chain to options with the specific strike + * specified. (e.g. 400) + * - Limit the option chain to a specific set of strikes (e.g. + * 400,405) + * - Limit the option chain to an open interval of strikes using a + * logical expression (e.g. >400) + * - Limit the option chain to a closed interval of strikes by + * specifying both endpoints. (e.g. 400-410) * - * @param int|null $strike_limit Limit the number of total strikes returned by the option chain. For example, if a - * complete chain included 30 strikes and the limit was set to 10, the 20 strikes furthest from the money will be - * excluded from the response. + * @param int|null $strike_limit Limit the number of total strikes returned by the option chain. + * For example, if a complete chain included 30 strikes and the + * limit was set to 10, the 20 strikes furthest from the money + * will be excluded from the response. * * TIP: If strikeLimit is combined with the range or side parameter, those parameters will be applied first. In the * above example, if the range were set to itm (in the money) and side set to call, all puts and out of the money @@ -189,32 +247,36 @@ public function strikes( * then strikeLimit will return the requested number of calls and puts for each side of the chain, but duplicating * the number of strikes that are received. * - * @param float|null $min_bid Limit the option chain to options with a bid price greater than or equal to the number - * provided. + * @param float|null $min_bid Limit the option chain to options with a bid price greater than + * or equal to the number provided. * - * @param float|null $max_bid Limit the option chain to options with a bid price less than or equal to the number - * provided. + * @param float|null $max_bid Limit the option chain to options with a bid price less than or + * equal to the number provided. * - * @param float|null $min_ask Limit the option chain to options with an ask price greater than or equal to the - * number provided. + * @param float|null $min_ask Limit the option chain to options with an ask price greater + * than or equal to the number provided. * - * @param float|null $max_ask Limit the option chain to options with an ask price less than or equal to the number - * provided. + * @param float|null $max_ask Limit the option chain to options with an ask price less than + * or equal to the number provided. * - * @param float|null $min_bid_ask_spread Limit the option chain to options with a bid-ask spread less than or equal - * to the number provided. + * @param float|null $min_bid_ask_spread Limit the option chain to options with a bid-ask spread less + * than or equal to the number provided. * - * @param float|null $max_bid_ask_spread_pct Limit the option chain to options with a bid-ask spread less than or - * equal to the percent provided (relative to the underlying). For example, a value of 0.5% would exclude all - * options trading with a bid-ask spread greater than $1.00 in an underlying that trades at $200. + * @param float|null $max_bid_ask_spread_pct Limit the option chain to options with a bid-ask spread less + * than or equal to the percent provided (relative to the + * underlying). For example, a value of 0.5% would exclude all + * options trading with a bid-ask spread greater than $1.00 in an + * underlying that trades at $200. * - * @param int|null $min_open_interest Limit the option chain to options with an open interest greater than or equal - * to the number provided. + * @param int|null $min_open_interest Limit the option chain to options with an open interest greater + * than or equal to the number provided. * - * @param int|null $min_volume Limit the option chain to options with a volume transacted greater than or equal to - * the number provided. + * @param int|null $min_volume Limit the option chain to options with a volume transacted + * greater than or equal to the number provided. * - * @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 OptionChains * * @throws GuzzleException|ApiException */ @@ -277,24 +339,32 @@ public function option_chain( /** * Get a current or historical end of day quote for a single options contract. * - * @param string $option_symbol The option symbol (as defined by the OCC) for the option you wish to lookup. Use the - * current OCC option symbol format, even for historic options that quoted before the format change in 2010. + * @param string $option_symbol The option symbol (as defined by the OCC) for the option you wish to + * lookup. Use the current OCC option symbol format, even for historic + * options that quoted before the format change in 2010. * - * @param string|null $date Use to lookup a historical end of day quote from a specific trading day. If no date is - * specified the quote will be the most current price available during market hours. When the market is closed the - * quote will be from the last trading day. Accepted timestamp inputs: ISO 8601, unix, spreadsheet. + * @param string|null $date Use to lookup a historical end of day quote from a specific trading day. + * If no date is specified the quote will be the most current price available + * during market hours. When the market is closed the quote will be from the + * last trading day. Accepted timestamp inputs: ISO 8601, unix, spreadsheet. * - * @param string|null $from Use to lookup a series of end of day quotes. From is the oldest (leftmost) date to - * return (inclusive). If from/to is not specified the quote will be the most current price available during market - * hours. When the market is closed the quote will be from the last trading day. Accepted timestamp inputs: ISO - * 8601, unix, spreadsheet. + * @param string|null $from Use to lookup a series of end of day quotes. From is the oldest (leftmost) + * date to return (inclusive). If from/to is not specified the quote will be + * the most current price available during market hours. When the market is + * closed the quote will be from the last trading day. Accepted timestamp + * inputs: ISO + * 8601, unix, spreadsheet. * - * @param string|null $to Use to lookup a series of end of day quotes. From is the newest (rightmost) date to return - * (exclusive). If from/to is not specified the quote will be the most current price available during market hours. - * When the market is closed the quote will be from the last trading day. Accepted timestamp inputs: ISO 8601, unix, - * spreadsheet. + * @param string|null $to Use to lookup a series of end of day quotes. From is the newest + * (rightmost) date to return + * (exclusive). If from/to is not specified the quote will be the most + * current price available during market hours. When the market is closed the + * quote will be from the last trading day. Accepted timestamp inputs: ISO + * 8601, unix, spreadsheet. * - * @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 Quotes * * @throws ApiException|GuzzleException */ diff --git a/src/Endpoints/Requests/Parameters.php b/src/Endpoints/Requests/Parameters.php index f5efbd7..b7ce63b 100644 --- a/src/Endpoints/Requests/Parameters.php +++ b/src/Endpoints/Requests/Parameters.php @@ -1,10 +1,20 @@ status = $response->s; - $this->option_symbol = $response->optionSymbol;} + $this->option_symbol = $response->optionSymbol; + } } diff --git a/src/Endpoints/Responses/Options/OptionChainStrike.php b/src/Endpoints/Responses/Options/OptionChainStrike.php index 7ef3df6..d4cfd0a 100644 --- a/src/Endpoints/Responses/Options/OptionChainStrike.php +++ b/src/Endpoints/Responses/Options/OptionChainStrike.php @@ -5,86 +5,73 @@ use Carbon\Carbon; use MarketDataApp\Enums\Side; +/** + * Represents a single option chain strike with associated data. + */ class OptionChainStrike { + /** + * Constructs a new OptionChainStrike instance. + * + * @param string $option_symbol The option symbol according to OCC symbology. + * @param string $underlying The ticker symbol of the underlying security. + * @param Carbon $expiration The option's expiration date in Unix time. + * @param Side $side The response will be call or put. + * @param float $strike The exercise price of the option. + * @param Carbon $first_traded The date the option was first traded. + * @param int $dte The number of days until the option expires. + * @param float $ask The ask price. + * @param int $ask_size The number of contracts offered at the ask price. + * @param float $bid The bid price. + * @param int $bid_size The number of contracts offered at the bid price. + * @param float $mid The midpoint price between the ask and the bid, also known as the mark + * price. + * @param float|null $last The last price negotiated for this option contract at the time of this + * quote. + * @param int $volume The number of contracts negotiated during the trading day at the time of + * this quote. + * @param int $open_interest The total number of contracts that have not yet been settled at the time + * of this quote. + * @param float $underlying_price The last price of the underlying security at the time of this quote. + * @param bool $in_the_money Specifies whether the option contract was in the money true or false at + * the time of this quote. + * @param float $intrinsic_value The intrinsic value of the option. + * @param float $extrinsic_value The extrinsic value of the option. + * @param float|null $implied_volatility The implied volatility of the option. + * @param float|null $delta The delta of the option. + * @param float|null $gamma The gamma of the option. + * @param float|null $theta The theta of the option. + * @param float|null $vega The vega of the option. + * @param float|null $rho The rho of the option. + * @param Carbon $updated The date/time of the quote. + */ public function __construct( - // The option symbol according to OCC symbology. public string $option_symbol, - - // The ticker symbol of the underlying security. public string $underlying, - - // The option's expiration date in Unix time. public Carbon $expiration, - - // The response will be call or put. public Side $side, - - // The exercise price of the option. public float $strike, - - // The date the option was first traded. public Carbon $first_traded, - - // The number of days until the option expires. public int $dte, - - // The ask price. public float $ask, - - // The number of contracts offered at the ask price. public int $ask_size, - - // The bid price. public float $bid, - - // The number of contracts offered at the bid price. public int $bid_size, - - // The midpoint price between the ask and the bid, also known as the mark price. public float $mid, - - // The last price negotiated for this option contract at the time of this quote. public float|null $last, - - // The number of contracts negotiated during the trading day at the time of this quote. public int $volume, - - // The total number of contracts that have not yet been settled at the time of this quote. public int $open_interest, - - // The last price of the underlying security at the time of this quote. public float $underlying_price, - - // Specifies whether the option contract was in the money true or false at the time of this quote. public bool $in_the_money, - - // The intrinsic value of the option. public float $intrinsic_value, - - // The extrinsic value of the option. public float $extrinsic_value, - - // The implied volatility of the option. public float|null $implied_volatility, - - // The delta of the option. public float|null $delta, - - // The gamma of the option. public float|null $gamma, - - // The theta of the option. public float|null $theta, - - // The vega of the option. public float|null $vega, - - // The rho of the option. public float|null $rho, - - // The date/time of the quote. public Carbon $updated, ) { } diff --git a/src/Endpoints/Responses/Options/OptionChains.php b/src/Endpoints/Responses/Options/OptionChains.php index c545a2b..ba7f8b4 100644 --- a/src/Endpoints/Responses/Options/OptionChains.php +++ b/src/Endpoints/Responses/Options/OptionChains.php @@ -6,21 +6,45 @@ use MarketDataApp\Endpoints\Responses\ResponseBase; use MarketDataApp\Enums\Side; +/** + * Represents a collection of option chains with associated data. + */ class OptionChains extends ResponseBase { - // Status will always be ok when there is the quote requested. + /** + * Status of the option chains request. Will always be ok when there is the quote requested. + * + * @var string + */ public string $status; - // Time of the next quote if there is no data in the requested period, but there is data in a subsequent period. + /** + * Time of the next quote if there is no data in the requested period, but there is data in a subsequent period. + * + * @var Carbon + */ public Carbon $next_time; - // Time of the previous quote if there is no data in the requested period, but there is data in a previous period. + /** + * Time of the previous quote if there is no data in the requested period, but there is data in a previous period. + * + * @var Carbon + */ public Carbon $prev_time; - /** @var array[array[OptionChainStrike[]]] $option_chains */ + /** + * Multidimensional array of OptionChainStrike objects organized by date. + * + * @var array + */ public array $option_chains = []; + /** + * Constructs a new OptionChains instance from the given response object. + * + * @param object $response The response object containing option chains data. + */ public function __construct(object $response) { parent::__construct($response); diff --git a/src/Endpoints/Responses/Options/Quote.php b/src/Endpoints/Responses/Options/Quote.php index 4d2c978..bd085b3 100644 --- a/src/Endpoints/Responses/Options/Quote.php +++ b/src/Endpoints/Responses/Options/Quote.php @@ -4,68 +4,59 @@ use Carbon\Carbon; +/** + * Represents a single option quote with associated data. + */ class Quote { + /** + * Constructs a new Quote instance. + * + * @param string $option_symbol The option symbol according to OCC symbology. + * @param float $ask The ask price. + * @param int $ask_size The number of contracts offered at the ask price. + * @param float $bid The bid price. + * @param int $bid_size The number of contracts offered at the bid price. + * @param float $mid The midpoint price between the ask and the bid, also known as the mark price. + * @param float $last The last price negotiated for this option contract at the time of this quote. + * @param int $volume The number of contracts negotiated during the trading day at the time of this + * quote. + * @param int $open_interest The total number of contracts that have not yet been settled at the time of + * this quote. + * @param float $underlying_price The last price of the underlying security at the time of this quote. + * @param bool $in_the_money Specifies whether the option contract was in the money true or false at the + * time of this quote. + * @param float $intrinsic_value The intrinsic value of the option. + * @param float $extrinsic_value The extrinsic value of the option. + * @param float $implied_volatility The implied volatility of the option. + * @param float $delta The delta of the option. + * @param float $gamma The gamma of the option. + * @param float $theta The theta of the option. + * @param float $vega The vega of the option. + * @param float $rho The rho of the option. + * @param Carbon $updated The date and time of this quote snapshot in Unix time. + */ public function __construct( - // The option symbol according to OCC symbology. public string $option_symbol, - - // The ask price. public float $ask, - - // The number of contracts offered at the ask price. public int $ask_size, - - // The bid price. public float $bid, - - // The number of contracts offered at the bid price. public int $bid_size, - - // The midpoint price between the ask and the bid, also known as the mark price. public float $mid, - - // The last price negotiated for this option contract at the time of this quote. public float $last, - - // The number of contracts negotiated during the trading day at the time of this quote. public int $volume, - - // The total number of contracts that have not yet been settled at the time of this quote. public int $open_interest, - - // The last price of the underlying security at the time of this quote. public float $underlying_price, - - // Specifies whether the option contract was in the money true or false at the time of this quote. public bool $in_the_money, - - // The intrinsic value of the option. public float $intrinsic_value, - - // The extrinsic value of the option. public float $extrinsic_value, - - // The implied volatility of the option. public float $implied_volatility, - - // The delta of the option. public float $delta, - - // The gamma of the option. public float $gamma, - - // The theta of the option. public float $theta, - - // The vega of the option. public float $vega, - - // The rho of the option. public float $rho, - - // The date and time of this quote snapshot in Unix time. public Carbon $updated, ) { } diff --git a/src/Endpoints/Responses/Options/Quotes.php b/src/Endpoints/Responses/Options/Quotes.php index 41125da..4cab3c6 100644 --- a/src/Endpoints/Responses/Options/Quotes.php +++ b/src/Endpoints/Responses/Options/Quotes.php @@ -5,21 +5,45 @@ use Carbon\Carbon; use MarketDataApp\Endpoints\Responses\ResponseBase; +/** + * Represents a collection of option quotes with associated data. + */ class Quotes extends ResponseBase { - // Status will always be ok when there is data for the quote requested. + /** + * Status of the quotes request. Will always be ok when there is data for the quote requested. + * + * @var string + */ public string $status; - // Time of the next quote if there is no data in the requested period, but there is data in a subsequent period. + /** + * Time of the next quote if there is no data in the requested period, but there is data in a subsequent period. + * + * @var Carbon + */ public Carbon $next_time; - // Time of the previous quote if there is no data in the requested period, but there is data in a previous period. + /** + * Time of the previous quote if there is no data in the requested period, but there is data in a previous period. + * + * @var Carbon + */ public Carbon $prev_time; - /** @var Quote[] $quotes */ + /** + * Array of Quote objects. + * + * @var Quote[] + */ public array $quotes = []; + /** + * Constructs a new Quotes instance from the given response object. + * + * @param object $response The response object containing quotes data. + */ public function __construct(object $response) { parent::__construct($response); diff --git a/src/Endpoints/Responses/Options/Strikes.php b/src/Endpoints/Responses/Options/Strikes.php index e492348..1bc5157 100644 --- a/src/Endpoints/Responses/Options/Strikes.php +++ b/src/Endpoints/Responses/Options/Strikes.php @@ -5,32 +5,53 @@ use Carbon\Carbon; use MarketDataApp\Endpoints\Responses\ResponseBase; +/** + * Represents a collection of option strikes with associated data. + */ class Strikes extends ResponseBase { - // Will always be ok when there is data for the candles requested. + + /** + * Status of the strikes request. Will always be ok when there is data for the candles requested. + * + * @var string + */ public string $status; /** * The expiration dates requested for the underlying with the option strikes for each expiration. * - * @var array[int[]] $dates + * @var array */ public array $dates = []; /** - * The date and time of this list of options strikes was updated in Unix time. For historical strikes, this number - * should match the date parameter. + * The date and time of this list of options strikes was updated in Unix time. + * For historical strikes, this number should match the date parameter. * - * @var Carbon $updated + * @var Carbon */ public Carbon $updated; - // Time of the next quote if there is no data in the requested period, but there is data in a subsequent period. + /** + * Time of the next quote if there is no data in the requested period, but there is data in a subsequent period. + * + * @var Carbon + */ public Carbon $next_time; - // Time of the previous quote if there is no data in the requested period, but there is data in a previous period. + /** + * Time of the previous quote if there is no data in the requested period, but there is data in a previous period. + * + * @var Carbon + */ public Carbon $prev_time; + /** + * Constructs a new Strikes instance from the given response object. + * + * @param object $response The response object containing strikes data. + */ public function __construct(object $response) { parent::__construct($response); @@ -43,9 +64,10 @@ public function __construct(object $response) switch ($this->status) { case 'ok': - foreach($response as $key => $value) { - if(in_array($key, ['s', 'updated'])) + foreach ($response as $key => $value) { + if (in_array($key, ['s', 'updated'])) { continue; + } $this->dates[$key] = $value; } diff --git a/src/Endpoints/Responses/ResponseBase.php b/src/Endpoints/Responses/ResponseBase.php index 6b40123..896773b 100644 --- a/src/Endpoints/Responses/ResponseBase.php +++ b/src/Endpoints/Responses/ResponseBase.php @@ -2,12 +2,25 @@ namespace MarketDataApp\Endpoints\Responses; +/** + * Base class for API responses. + * + * This class provides common functionality for handling different response formats (CSV, HTML, JSON). + */ class ResponseBase { + /** @var string The CSV content of the response. */ protected string $csv; + + /** @var string The HTML content of the response. */ protected string $html; + /** + * ResponseBase constructor. + * + * @param object $response The raw response object from the API. + */ public function __construct($response) { if (isset($response->csv)) { @@ -19,26 +32,51 @@ public function __construct($response) } } + /** + * Get the CSV content of the response. + * + * @return string The CSV content. + */ public function getCsv(): string { return $this->csv; } + /** + * Get the HTML content of the response. + * + * @return string The HTML content. + */ public function getHtml(): string { return $this->html; } + /** + * Check if the response is in JSON format. + * + * @return bool True if the response is in JSON format, false otherwise. + */ public function isJson(): bool { return empty($this->csv) && empty($this->html); } + /** + * Check if the response is in HTML format. + * + * @return bool True if the response is in HTML format, false otherwise. + */ public function isHtml(): bool { return !empty($this->html); } + /** + * Check if the response is in CSV format. + * + * @return bool True if the response is in CSV format, false otherwise. + */ public function isCsv(): bool { return !empty($this->csv); diff --git a/src/Endpoints/Responses/Stocks/BulkCandles.php b/src/Endpoints/Responses/Stocks/BulkCandles.php index ac398c2..166015f 100644 --- a/src/Endpoints/Responses/Stocks/BulkCandles.php +++ b/src/Endpoints/Responses/Stocks/BulkCandles.php @@ -5,15 +5,31 @@ use Carbon\Carbon; use MarketDataApp\Endpoints\Responses\ResponseBase; +/** + * Represents a collection of stock candles data in bulk format. + */ class BulkCandles extends ResponseBase { - // Will always be ok when there is data for the candles requested. + /** + * Status of the bulk candles request. Will always be ok when there is data for the candles requested. + * + * @var string + */ public string $status; - /** @var Candle[] $candles */ + /** + * Array of Candle objects representing individual stock candles. + * + * @var Candle[] + */ public array $candles = []; + /** + * Constructs a new BulkCandles instance from the given response object. + * + * @param object $response The response object containing bulk candles data. + */ public function __construct(object $response) { parent::__construct($response); diff --git a/src/Endpoints/Responses/Stocks/BulkQuote.php b/src/Endpoints/Responses/Stocks/BulkQuote.php index f874b8a..e6d74fd 100644 --- a/src/Endpoints/Responses/Stocks/BulkQuote.php +++ b/src/Endpoints/Responses/Stocks/BulkQuote.php @@ -4,51 +4,48 @@ use Carbon\Carbon; +/** + * Represents a bulk quote for a stock with various price and volume information. + */ class BulkQuote { + /** + * Constructs a new BulkQuote instance. + * + * @param string $symbol The symbol of the stock. + * @param float $ask The ask price of the stock. + * @param int $ask_size The number of shares offered at the ask price. + * @param float $bid The bid price. + * @param int $bid_size The number of shares that may be sold at the bid price. + * @param float $mid The midpoint price between the ask and the bid. + * @param float $last The last price the stock traded at. + * @param float|null $change The difference in price in dollars (or the security's currency if + * different from dollars) compared to the closing price of the previous + * day. + * @param float|null $change_percent The difference in price in percent, expressed as a decimal, compared to + * the closing price of the previous day. For example, a 30% change will be + * represented as 0.30. + * @param float|null $fifty_two_week_high The 52-week high for the stock. This parameter is omitted unless the + * optional 52week request parameter is set to true. + * @param float|null $fifty_two_week_low The 52-week low for the stock. This parameter is omitted unless the + * optional 52week request parameter is set to true. + * @param int $volume The number of shares traded during the current session. + * @param Carbon $updated The date/time of the current stock quote. + */ public function __construct( - // The symbol of the stock. public string $symbol, - - // The ask price of the stock. public float $ask, - - // The number of shares offered at the ask price. public int $ask_size, - - // The bid price. public float $bid, - - // The number of shares that may be sold at the bid price. public int $bid_size, - - // The midpoint price between the ask and the bid. public float $mid, - - // The last price the stock traded at. public float $last, - - // The difference in price in dollars (or the security's currency if different from dollars) compared to the closing - // price of the previous day. public float|null $change, - - // The difference in price in percent, expressed as a decimal, compared to the closing price of the previous day. - // For example, a 30% change will be represented as 0.30. public float|null $change_percent, - - // The 52-week high for the stock. This parameter is omitted unless the optional 52week request parameter is set to - // true. public float|null $fifty_two_week_high, - - // The 52-week low for the stock. This parameter is omitted unless the optional 52week request parameter is set to - // true. public float|null $fifty_two_week_low, - - // The number of shares traded during the current session. public int $volume, - - // The date/time of the current stock quote. public Carbon $updated ) { } diff --git a/src/Endpoints/Responses/Stocks/BulkQuotes.php b/src/Endpoints/Responses/Stocks/BulkQuotes.php index 4d5e805..b90f379 100644 --- a/src/Endpoints/Responses/Stocks/BulkQuotes.php +++ b/src/Endpoints/Responses/Stocks/BulkQuotes.php @@ -5,15 +5,31 @@ use Carbon\Carbon; use MarketDataApp\Endpoints\Responses\ResponseBase; +/** + * Represents a collection of bulk stock quotes. + */ class BulkQuotes extends ResponseBase { - // Will always be ok when there is data for the symbol requested. + /** + * Status of the bulk quotes request. Will always be ok when there is data for the symbol requested. + * + * @var string + */ public string $status; - /** @var BulkQuote[] $quotes */ + /** + * Array of BulkQuote objects representing individual stock quotes. + * + * @var BulkQuote[] + */ public array $quotes; + /** + * Constructs a new BulkQuotes instance from the given response object. + * + * @param object $response The response object containing bulk quotes data. + */ public function __construct(object $response) { parent::__construct($response); diff --git a/src/Endpoints/Responses/Stocks/Candle.php b/src/Endpoints/Responses/Stocks/Candle.php index f3c72d3..ce7d392 100644 --- a/src/Endpoints/Responses/Stocks/Candle.php +++ b/src/Endpoints/Responses/Stocks/Candle.php @@ -4,27 +4,29 @@ use Carbon\Carbon; +/** + * Represents a single stock candle with open, high, low, close prices, volume, and timestamp. + */ class Candle { + /** + * Constructs a new Candle instance. + * + * @param float $open Open price of the candle. + * @param float $high High price of the candle. + * @param float $low Low price of the candle. + * @param float $close Close price of the candle. + * @param int $volume Trading volume during the candle period. + * @param Carbon $timestamp Candle time (Unix timestamp, UTC). Daily, weekly, monthly, yearly candles are returned + * without times. + */ public function __construct( - - // Open price. public float $open, - - // High price. public float $high, - - // Low price. public float $low, - - // Close price. public float $close, - - // Volume. public int $volume, - - // Candle time (Unix timestamp, UTC). Daily, weekly, monthly, yearly candles are returned without times. public Carbon $timestamp, ) { } diff --git a/src/Endpoints/Responses/Stocks/Candles.php b/src/Endpoints/Responses/Stocks/Candles.php index a390b84..c39fa9d 100644 --- a/src/Endpoints/Responses/Stocks/Candles.php +++ b/src/Endpoints/Responses/Stocks/Candles.php @@ -5,19 +5,41 @@ use Carbon\Carbon; use MarketDataApp\Endpoints\Responses\ResponseBase; +/** + * Class Candles + * + * Represents a collection of stock candles data and handles the response parsing. + */ class Candles extends ResponseBase { - // Will always be ok when there is data for the candles requested. + /** + * The status of the response. Will always be "ok" when there is data for the candles requested. + * + * @var string + */ public string $status; - // Unix time of the next quote if there is no data in the requested period, but there is data in a subsequent - // period. + /** + * Unix time of the next quote if there is no data in the requested period, but there is data in a subsequent + * period. + * + * @var int + */ public int $next_time; - /** @var Candle[] $candles */ + /** + * Array of Candle objects representing individual candle data. + * + * @var Candle[] + */ public array $candles = []; + /** + * Constructs a new Candles object and parses the response data. + * + * @param object $response The raw response object to be parsed. + */ public function __construct(object $response) { parent::__construct($response); @@ -42,8 +64,10 @@ public function __construct(object $response) } break; - case 'no_data' && isset($response->nextTime): - $this->next_time = $response->nextTime; + case 'no_data': + if (isset($response->nextTime)) { + $this->next_time = $response->nextTime; + } break; } } diff --git a/src/Endpoints/Responses/Stocks/Earning.php b/src/Endpoints/Responses/Stocks/Earning.php index 7891592..dc6d398 100644 --- a/src/Endpoints/Responses/Stocks/Earning.php +++ b/src/Endpoints/Responses/Stocks/Earning.php @@ -4,54 +4,48 @@ use Carbon\Carbon; +/** + * Class Earning + * + * Represents earnings data for a stock, including fiscal information, report details, and EPS data. + */ class Earning { + /** + * Constructs a new Earning object with detailed earnings information. + * + * @param string $symbol The symbol of the stock. + * @param int $fiscal_year The fiscal year of the earnings report. This may not always align with the + * calendar year. + * @param int $fiscal_quarter The fiscal quarter of the earnings report. This may not always align with + * the calendar quarter. + * @param Carbon $date The last calendar day that corresponds to this earnings report. + * @param Carbon $report_date The date the earnings report was released or is projected to be released. + * @param string $report_time The value will be either before market open, after market close, or during + * market hours. + * @param string $currency The currency of the earnings report. + * @param float|null $reported_eps The earnings per share reported by the company. Earnings reported are + * typically non-GAAP unless the company does not report non-GAAP earnings. + * @param float|null $estimated_eps The average consensus estimate by Wall Street analysts. + * @param float|null $surprise_eps The difference (in earnings per share) between the estimated earnings per + * share and the reported earnings per share. + * @param float|null $surprise_eps_pct The difference in percentage terms between the estimated EPS and the + * reported EPS. + * @param Carbon $updated The date/time the earnings data for this ticker was last updated. + */ public function __construct( - // The symbol of the stock. public string $symbol, - - // The fiscal year of the earnings report. This may not always align with the calendar year. public int $fiscal_year, - - // The fiscal quarter of the earnings report. This may not always align with the calendar quarter. public int $fiscal_quarter, - - // The last calendar day that corresponds to this earnings report. public Carbon $date, - - // The date the earnings report was released or is projected to be released. public Carbon $report_date, - - // The value will be either before market open, after market close, or during market hours. public string $report_time, - - // The currency of the earnings report. public string $currency, - - /** - * The earnings per share reported by the company. Earnings reported are typically non-GAAP unless the company does - * not report non-GAAP earnings. - * - * TIP: GAAP (Generally Accepted Accounting Principles) earnings per share (EPS) count all financial activities - * except for discontinued operations and major changes in accounting methods. Non-GAAP EPS, on the other hand, - * typically doesn't include losses or devaluation of assets, and often leaves out irregular expenses like - * significant restructuring costs, large tax or legal charges, especially for companies not in the - * financial sector. - */ public float|null $reported_eps, - - // The average consensus estimate by Wall Street analysts. public float|null $estimated_eps, - - // The difference (in earnings per share) between the estimated earnings per share and the reported earnings per - // share. public float|null $surprise_eps, - - // The difference in percentage terms between the estimated EPS and the reported EPS. public float|null $surprise_eps_pct, - - // The date/time the earnings data for this ticker was last updated. public Carbon $updated ) { } diff --git a/src/Endpoints/Responses/Stocks/Earnings.php b/src/Endpoints/Responses/Stocks/Earnings.php index c1ab5b4..f463787 100644 --- a/src/Endpoints/Responses/Stocks/Earnings.php +++ b/src/Endpoints/Responses/Stocks/Earnings.php @@ -5,15 +5,33 @@ use Carbon\Carbon; use MarketDataApp\Endpoints\Responses\ResponseBase; +/** + * Class Earnings + * + * Represents a collection of earnings data for stocks and handles the response parsing. + */ class Earnings extends ResponseBase { - // Will always be ok when there is data for the symbol requested. + /** + * The status of the response. Will always be "ok" when there is data for the symbol requested. + * + * @var string + */ public string $status; - /** @var Earning[] $earnings */ + /** + * Array of Earning objects representing individual stock earnings data. + * + * @var Earning[] + */ public array $earnings; + /** + * Constructs a new Earnings object and parses the response data. + * + * @param object $response The raw response object to be parsed. + */ public function __construct(object $response) { parent::__construct($response); diff --git a/src/Endpoints/Responses/Stocks/News.php b/src/Endpoints/Responses/Stocks/News.php index f9dc383..635788b 100644 --- a/src/Endpoints/Responses/Stocks/News.php +++ b/src/Endpoints/Responses/Stocks/News.php @@ -5,16 +5,33 @@ use Carbon\Carbon; use MarketDataApp\Endpoints\Responses\ResponseBase; +/** + * Class News + * + * Represents news data for a stock and handles the response parsing. + */ class News extends ResponseBase { - // Will always be ok when there is data for the symbol requested. + /** + * The status of the response. Will always be "ok" when there is data for the symbol requested. + * + * @var string + */ public string $status; - // The symbol of the stock. + /** + * The symbol of the stock. + * + * @var string + */ public string $symbol; - // The headline of the news article. + /** + * The headline of the news article. + * + * @var string + */ public string $headline; /** @@ -23,15 +40,30 @@ class News extends ResponseBase * TIP: Please be aware that this may or may not include the full content of the news article. Additionally, it may * include captions of images, copyright notices, syndication information, and other elements that may not be * suitable for reproduction without additional filtering. + * + * @var string */ public string $content; - // The source URL where the news appeared. + /** + * The source URL where the news appeared. + * + * @var string + */ public string $source; - // The date the news was published on the source website. + /** + * The date the news was published on the source website. + * + * @var Carbon + */ public Carbon $publication_date; + /** + * Constructs a new News object and parses the response data. + * + * @param object $response The raw response object to be parsed. + */ public function __construct(object $response) { parent::__construct($response); diff --git a/src/Endpoints/Responses/Stocks/Quote.php b/src/Endpoints/Responses/Stocks/Quote.php index 06b3eb2..237cd68 100644 --- a/src/Endpoints/Responses/Stocks/Quote.php +++ b/src/Endpoints/Responses/Stocks/Quote.php @@ -5,55 +5,121 @@ use Carbon\Carbon; use MarketDataApp\Endpoints\Responses\ResponseBase; +/** + * Class Quote + * + * Represents a stock quote and handles the response parsing for stock quote data. + */ class Quote extends ResponseBase { - // Will always be ok when there is data for the symbol requested. + /** + * The status of the response. Will always be "ok" when there is data for the symbol requested. + * + * @var string + */ public string $status; - // The symbol of the stock. + /** + * The symbol of the stock. + * + * @var string + */ public string $symbol; - // The ask price of the stock. + /** + * The ask price of the stock. + * + * @var float + */ public float $ask; - // The number of shares offered at the ask price. + /** + * The number of shares offered at the ask price. + * + * @var int + */ public int $ask_size; - // The bid price. + /** + * The bid price. + * + * @var float + */ public float $bid; - // The number of shares that may be sold at the bid price. + /** + * The number of shares that may be sold at the bid price. + * + * @var int + */ public int $bid_size; - // The midpoint price between the ask and the bid. + /** + * The midpoint price between the ask and the bid. + * + * @var float + */ public float $mid; - // The last price the stock traded at. + /** + * The last price the stock traded at. + * + * @var float + */ public float $last; - // The difference in price in dollars (or the security's currency if different from dollars) compared to the closing - // price of the previous day. + /** + * The difference in price in dollars (or the security's currency if different from dollars) compared to the closing + * price of the previous day. + * + * @var float|null + */ public float|null $change; - // The difference in price in percent, expressed as a decimal, compared to the closing price of the previous day. - // For example, a 30% change will be represented as 0.30. + /** + * The difference in price in percent, expressed as a decimal, compared to the closing price of the previous day. + * For example, a 30% change will be represented as 0.30. + * + * @var float|null + */ public float|null $change_percent; - // The 52-week high for the stock. This parameter is omitted unless the optional 52week request parameter is set to - // true. + /** + * The 52-week high for the stock. This parameter is omitted unless the optional 52week request parameter is set to + * true. + * + * @var float|null + */ public float|null $fifty_two_week_high = null; - // The 52-week low for the stock. This parameter is omitted unless the optional 52week request parameter is set to - // true. + /** + * The 52-week low for the stock. This parameter is omitted unless the optional 52week request parameter is set to + * true. + * + * @var float|null + */ public float|null $fifty_two_week_low = null; - // The number of shares traded during the current session. + /** + * The number of shares traded during the current session. + * + * @var int + */ public int $volume; - // The date/time of the current stock quote. + /** + * The date/time of the current stock quote. + * + * @var Carbon + */ public Carbon $updated; + /** + * Constructs a new Quote object and parses the response data. + * + * @param object $response The raw response object to be parsed. + */ public function __construct(object $response) { parent::__construct($response); diff --git a/src/Endpoints/Responses/Stocks/Quotes.php b/src/Endpoints/Responses/Stocks/Quotes.php index 2127f6a..b2f630d 100644 --- a/src/Endpoints/Responses/Stocks/Quotes.php +++ b/src/Endpoints/Responses/Stocks/Quotes.php @@ -2,11 +2,24 @@ namespace MarketDataApp\Endpoints\Responses\Stocks; +/** + * Represents a collection of stock quotes. + */ class Quotes { - /** @var Quote[] $quotes */ + + /** + * Array of Quote objects. + * + * @var Quote[] + */ public array $quotes; + /** + * Quotes constructor. + * + * @param array $quotes Array of raw quote data. + */ public function __construct(array $quotes) { foreach ($quotes as $quote) { diff --git a/src/Endpoints/Responses/Utilities/ApiStatus.php b/src/Endpoints/Responses/Utilities/ApiStatus.php index 60ee988..2842905 100644 --- a/src/Endpoints/Responses/Utilities/ApiStatus.php +++ b/src/Endpoints/Responses/Utilities/ApiStatus.php @@ -4,15 +4,31 @@ use Carbon\Carbon; +/** + * Represents the status of the API and its services. + */ class ApiStatus { - // Will always be ok when the status information is successfully retrieved. + /** + * Will always be ok when the status information is successfully retrieved. + * + * @var string + */ public string $status; - /* @var ServiceStatus[] $services */ + /** + * Array of ServiceStatus objects representing the status of each service. + * + * @var ServiceStatus[] + */ public array $services; + /** + * ApiStatus constructor. + * + * @param object $response The raw response object containing API status information. + */ public function __construct(object $response) { // Convert the response to this object. diff --git a/src/Endpoints/Responses/Utilities/Headers.php b/src/Endpoints/Responses/Utilities/Headers.php index c2f3a63..07a5913 100644 --- a/src/Endpoints/Responses/Utilities/Headers.php +++ b/src/Endpoints/Responses/Utilities/Headers.php @@ -2,8 +2,17 @@ namespace MarketDataApp\Endpoints\Responses\Utilities; +/** + * Represents the headers of an API response. + */ class Headers { + + /** + * Headers constructor. + * + * @param object $response The response object containing header information. + */ public function __construct(object $response) { // Set the headers based on response object. diff --git a/src/Endpoints/Responses/Utilities/ServiceStatus.php b/src/Endpoints/Responses/Utilities/ServiceStatus.php index 4ae5ca1..f3efa2d 100644 --- a/src/Endpoints/Responses/Utilities/ServiceStatus.php +++ b/src/Endpoints/Responses/Utilities/ServiceStatus.php @@ -4,25 +4,27 @@ use Carbon\Carbon; +/** + * Represents the status of a service. + */ class ServiceStatus { + /** + * ServiceStatus constructor. + * + * @param string $service The service being monitored. + * @param string $status The current status of each service (online or offline). + * @param float $uptime_percentage_30d The uptime percentage of each service over the last 30 days. + * @param float $uptime_percentage_90d The uptime percentage of each service over the last 90 days. + * @param Carbon $updated The timestamp of the last update for each service's status. + */ public function __construct( - // The service being monitored. public string $service, - - // The current status of each service (online or offline). public string $status, - - // The uptime percentage of each service over the last 30 days. public float $uptime_percentage_30d, - - // The uptime percentage of each service over the last 90 days. public float $uptime_percentage_90d, - - // The timestamp of the last update for each service's status. public Carbon $updated, ) { - } } diff --git a/src/Endpoints/Stocks.php b/src/Endpoints/Stocks.php index 203fa04..fd52904 100644 --- a/src/Endpoints/Stocks.php +++ b/src/Endpoints/Stocks.php @@ -15,42 +15,58 @@ use MarketDataApp\Exceptions\ApiException; use MarketDataApp\Traits\UniversalParameters; +/** + * Stocks class for handling stock-related API endpoints. + */ class Stocks { use UniversalParameters; + /** @var Client The Market Data API client instance. */ private Client $client; + + /** @var string The base URL for stock endpoints. */ public const BASE_URL = "v1/stocks/"; + /** + * Stocks constructor. + * + * @param Client $client The Market Data API client instance. + */ public function __construct($client) { $this->client = $client; } /** + * Get bulk candle data for stocks. + * * Get bulk candle data for stocks. This endpoint returns bulk daily candle data for multiple stocks. Unlike the * standard candles endpoint, this endpoint returns a single daily for each symbol provided. The typical use-case * for this endpoint is to get a complete market snapshot during trading hours, though it can also be used for bulk * snapshots of historical daily candles. * - * @param array $symbols The ticker symbols to return in the response, separated by commas. The symbols parameter - * may be omitted if the snapshot parameter is set to true. + * @param array $symbols The ticker symbols to return in the response, separated by commas. The + * symbols parameter may be omitted if the snapshot parameter is set to true. * - * @param string $resolution The duration of each candle. Only daily candles are supported at this time. - * Daily Resolutions: (daily, D, 1D, 2D, ...) + * @param string $resolution The duration of each candle. Only daily candles are supported at this + * time. + * Daily Resolutions: (daily, D, 1D, 2D, ...) * - * @param bool $snapshot Returns candles for all available symbols for the date indicated. The symbols parameter can - * be omitted if snapshot is set to true. + * @param bool $snapshot Returns candles for all available symbols for the date indicated. The + * symbols parameter can be omitted if snapshot is set to true. * - * @param string|null $date The date of the candles to be returned. If no date is specified, during market hours the - * candles returned will be from the current session. If the market is closed the candles will be from the most - * recent session. Accepted timestamp inputs: ISO 8601, unix, spreadsheet. + * @param string|null $date The date of the candles to be returned. If no date is specified, during + * market hours the candles returned will be from the current session. If the + * market is closed the candles will be from the most recent session. + * Accepted timestamp inputs: ISO 8601, unix, spreadsheet. * - * @param bool $adjust_splits Adjust historical data for historical splits and reverse splits. Market Data uses - * the CRSP methodology for adjustment. Daily candles default: true. + * @param bool $adjust_splits Adjust historical data for historical splits and reverse splits. Market + * Data uses the CRSP methodology for adjustment. Daily candles default: + * true. * - * @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 BulkCandles * @throws ApiException @@ -83,46 +99,51 @@ public function bulkCandles( /** * Get historical price candles for an index. * - * @param string $symbol The company's ticker symbol. + * @param string $symbol The company's ticker symbol. * - * @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 string|null $exchange Use to specify the exchange of the ticker. This is useful when you need to specify - * a stock that quotes on several exchanges with the same symbol. You may specify the exchange using the EXCHANGE - * ACRONYM, MIC CODE, or two digit YAHOO FINANCE EXCHANGE CODE. If no exchange is specified symbols will be matched - * to US exchanges first. + * @param string|null $exchange Use to specify the exchange of the ticker. This is useful when you need + * to specify a stock that quotes on several exchanges with the same + * symbol. You may specify the exchange using the EXCHANGE ACRONYM, MIC + * CODE, or two digit YAHOO FINANCE EXCHANGE CODE. If no exchange is + * specified symbols will be matched to US exchanges first. * - * @param bool $extended Include extended hours trading sessions when returning intraday candles. Daily resolutions - * never return extended hours candles. The default is false. + * @param bool $extended Include extended hours trading sessions when returning intraday + * candles. Daily resolutions never return extended hours candles. The + * default is false. * - * @param string|null $country Use to specify the country of the exchange (not the country of the company) in - * conjunction with the symbol argument. This argument is useful when you know the ticker symbol and the country of - * the exchange, but not the exchange code. Use the two digit ISO 3166 country code. If no country is specified, US - * exchanges will be assumed. + * @param string|null $country Use to specify the country of the exchange (not the country of the + * company) in conjunction with the symbol argument. This argument is + * useful when you know the ticker symbol and the country of the exchange, + * but not the exchange code. Use the two digit ISO 3166 country code. If + * no country is specified, US exchanges will be assumed. * - * @param bool $adjust_splits Adjust historical data for for historical splits and reverse splits. Market Data uses - * the CRSP methodology for adjustment. Daily candles default: true. Intraday candles default: false. + * @param bool $adjust_splits Adjust historical data for for historical splits and reverse splits. + * Market Data uses the CRSP methodology for adjustment. Daily candles + * default: true. Intraday candles default: false. * - * @param bool $adjust_dividends CAUTION: Adjusted dividend data is planned for the future, but not yet implemented. - * All data is currently returned unadjusted for dividends. Market Data uses the CRSP methodology for adjustment. - * Daily candles default: true. Intraday candles default: false. + * @param bool $adjust_dividends CAUTION: Adjusted dividend data is planned for the future, but not yet + * implemented. All data is currently returned unadjusted for dividends. + * Market Data uses the CRSP methodology for adjustment. Daily candles + * default: true. Intraday candles default: false. * - * @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 Candles * @throws GuzzleException|ApiException @@ -156,13 +177,14 @@ public function candles( /** * Get a real-time price quote for a stock. * - * @param string $symbol The company's ticker symbol. + * @param string $symbol The company's ticker symbol. * - * @param bool $fifty_two_week Enable the output of 52-week high and 52-week low data in the quote output. By - * default this parameter is false if omitted. + * @param bool $fifty_two_week Enable the output of 52-week high and 52-week low data in the quote + * output. By default this parameter is false if omitted. * - * @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(string $symbol, bool $fifty_two_week = false, ?Parameters $parameters = null): Quote @@ -172,12 +194,14 @@ public function quote(string $symbol, bool $fifty_two_week = false, ?Parameters } /** - * Get a real-time price quote for a multiple stocks by doing parallel requests. + * Get real-time price quotes for multiple stocks 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(array $symbols, bool $fifty_two_week = false, ?Parameters $parameters = null): Quotes @@ -192,20 +216,21 @@ public function quotes(array $symbols, bool $fifty_two_week = false, ?Parameters } /** - * Get a real-time price quote for a multiple stocks in a single API request. + * Get real-time price quotes for multiple stocks in a single API request. * * The bulkQuotes endpoint is designed to return hundreds of symbols at once or full market snapshots. Response * times for less than 50 symbols will be quicker using the standard quotes endpoint and sending your requests in * parallel. * - * @param array $symbols The ticker symbols to return in the response, separated by commas. The symbols parameter - * may be omitted if the snapshot parameter is set to true. + * @param array $symbols The ticker symbols to return in the response, separated by commas. The + * symbols parameter may be omitted if the snapshot parameter is set to true. * - * @param bool $snapshot Returns a full market snapshot with quotes for all symbols when set to true. The symbols - * parameter may be omitted if the snapshot parameter is set. + * @param bool $snapshot Returns a full market snapshot with quotes for all symbols when set to true. + * The symbols parameter may be omitted if the snapshot parameter is set. * * @param Parameters|null $parameters Universal parameters for all methods (such as format). * + * @return BulkQuotes * @throws GuzzleException * @throws \Exception */ @@ -224,20 +249,21 @@ public function bulkQuotes(array $symbols = [], bool $snapshot = false, ?Paramet * * Premium subscription required. * - * @param string $symbol The company's ticker symbol. + * @param string $symbol The company's ticker symbol. * - * @param string|null $from The earliest earnings report to include in the output. If you use countback, from is not - * required. + * @param string|null $from The earliest earnings report to include in the output. If you use countback, + * from is not required. * - * @param string|null $to The latest earnings report to include in the output. + * @param string|null $to The latest earnings report to include in the output. * - * @param int|null $countback Countback will fetch a specific number of earnings reports before to. If you use from, - * countback is not required. + * @param int|null $countback Countback will fetch a specific number of earnings reports before to. If you + * use from, countback is not required. * - * @param string|null $date Retrieve a specific earnings report by date. + * @param string|null $date Retrieve a specific earnings report by date. * - * @param string|null $datekey Retrieve a specific earnings report by date and quarter. Example: 2023-Q4. This - * allows you to retrieve a 4th quarter value without knowing the company's specific fiscal year. + * @param string|null $datekey Retrieve a specific earnings report by date and quarter. Example: 2023-Q4. + * This allows you to retrieve a 4th quarter value without knowing the company's + * specific fiscal year. * * @param Parameters|null $parameters Universal parameters for all methods (such as format). * @@ -263,23 +289,25 @@ public function earnings( } /** - * Retrieves news articles for a given stock symbol within a specified date range. + * Retrieve news articles for a given stock symbol within a specified date range. * * CAUTION: This endpoint is in beta. * - * @param string $symbol The ticker symbol of the stock. + * @param string $symbol The ticker symbol of the stock. * - * @param string|null $from The earliest news to include in the output. If you use countback, from is not required. + * @param string|null $from The earliest news to include in the output. If you use countback, from is not + * required. * - * @param string|null $to The latest news to include in the output. + * @param string|null $to The latest news to include in the output. * - * @param int|null $countback Countback will fetch a specific number of news before to. If you use from, countback - * is not required. + * @param int|null $countback Countback will fetch a specific number of news before to. If you use from, + * countback is not required. * - * @param string|null $date Retrieve news for a specific day. + * @param string|null $date Retrieve news for a specific day. * * @param Parameters|null $parameters Universal parameters for all methods (such as format). * + * @return News * @throws \InvalidArgumentException */ public function news( diff --git a/src/Endpoints/Utilities.php b/src/Endpoints/Utilities.php index e7e04bb..eaaa067 100644 --- a/src/Endpoints/Utilities.php +++ b/src/Endpoints/Utilities.php @@ -8,23 +8,37 @@ use MarketDataApp\Endpoints\Responses\Utilities\Headers; use MarketDataApp\Exceptions\ApiException; +/** + * Utilities class for Market Data API. + * + * This class provides utility methods for checking API status and retrieving request headers. + */ class Utilities { + /** @var Client The Market Data API client instance. */ private Client $client; + /** + * Utilities constructor. + * + * @param Client $client The Market Data API client instance. + */ public function __construct($client) { $this->client = $client; } /** + * Check the current status of Market Data services. + * * Check the current status of Market Data services and historical uptime. The status of the Market Data API is * updated every 5 minutes. Historical uptime is available for the last 30 and 90 days. * * TIP: This endpoint will continue to respond with the current status of the Market Data API, even if the API is * offline. This endpoint is public and does not require a token. * + * @return ApiStatus The current API status and historical uptime information. * @throws GuzzleException|ApiException */ public function api_status(): ApiStatus @@ -33,11 +47,16 @@ public function api_status(): ApiStatus } /** + * Retrieve the headers sent by the application. + * * This endpoint allows users to retrieve a JSON response of the headers their application is sending, aiding in * troubleshooting authentication issues, particularly with the Authorization header. * * TIP: The values in sensitive headers such as Authorization are partially redacted in the response for security * purposes. + * + * @return Headers The headers sent in the request. + * @throws GuzzleException|ApiException */ public function headers(): Headers { diff --git a/src/Enums/Expiration.php b/src/Enums/Expiration.php index b3ab55b..ccfaebf 100644 --- a/src/Enums/Expiration.php +++ b/src/Enums/Expiration.php @@ -2,8 +2,16 @@ namespace MarketDataApp\Enums; +/** + * Enum Expiration + * + * Represents expiration options for market data queries. + */ enum Expiration: string { + /** + * Represents all expirations. + */ case ALL = 'all'; } diff --git a/src/Enums/Format.php b/src/Enums/Format.php index 37ccb55..339b1c3 100644 --- a/src/Enums/Format.php +++ b/src/Enums/Format.php @@ -2,10 +2,28 @@ namespace MarketDataApp\Enums; +/** + * Enum Format + * + * Represents the available output formats for market data responses. + */ enum Format: string { + /** + * Represents JSON format output. + */ case JSON = 'json'; + + /** + * Represents CSV format output. + */ case CSV = 'csv'; - case HTML = 'html'; // In beta, use at your own risk + + /** + * Represents HTML format output. + * + * @note This format is in beta and should be used at your own risk. + */ + case HTML = 'html'; } diff --git a/src/Enums/Range.php b/src/Enums/Range.php index 8fc7853..7ffbd55 100644 --- a/src/Enums/Range.php +++ b/src/Enums/Range.php @@ -2,10 +2,26 @@ namespace MarketDataApp\Enums; +/** + * Enum Range + * + * Represents the range options for market data queries. + */ enum Range: string { + /** + * Represents options that are "in the money". + */ case IN_THE_MONEY = 'itm'; + + /** + * Represents options that are "out of the money". + */ case OUT_OF_THE_MONEY = 'otm'; + + /** + * Represents all options. + */ case ALL = 'all'; } diff --git a/src/Enums/Side.php b/src/Enums/Side.php index ffb2803..8b9ffbb 100644 --- a/src/Enums/Side.php +++ b/src/Enums/Side.php @@ -2,9 +2,27 @@ namespace MarketDataApp\Enums; +/** + * Enum Side + * + * Represents the types of options in options trading. + */ enum Side: string { + /** + * Represents a put option. + * + * A put option gives the holder the right to sell the underlying asset at a specified price within a specific time + * period. + */ case PUT = 'put'; + + /** + * Represents a call option. + * + * A call option gives the holder the right to buy the underlying asset at a specified price within a specific time + * period. + */ case CALL = 'call'; } diff --git a/src/Exceptions/ApiException.php b/src/Exceptions/ApiException.php index 43c3b9f..583b5b5 100644 --- a/src/Exceptions/ApiException.php +++ b/src/Exceptions/ApiException.php @@ -1,15 +1,42 @@ response = $response; } - public function getResponse() { + /** + * Get the API response associated with this exception. + * + * @return mixed The API response. + */ + public function getResponse() + { return $this->response; } } diff --git a/src/Traits/UniversalParameters.php b/src/Traits/UniversalParameters.php index 494b8fe..9c77c00 100644 --- a/src/Traits/UniversalParameters.php +++ b/src/Traits/UniversalParameters.php @@ -4,12 +4,29 @@ use MarketDataApp\Endpoints\Requests\Parameters; +/** + * Trait UniversalParameters + * + * This trait provides methods for executing API requests with universal parameters. + * It can be used to add common functionality across different endpoint classes. + */ trait UniversalParameters { + /** + * Execute a single API request with universal parameters. + * + * @param string $method The API method to call. + * @param array $arguments The arguments for the API call. + * @param Parameters|null $parameters Optional Parameters object for additional settings. + * + * @return object The API response as an object. + */ protected function execute(string $method, $arguments, ?Parameters $parameters): object { - if(is_null($parameters)) $parameters = new Parameters(); + if (is_null($parameters)) { + $parameters = new Parameters(); + } return $this->client->execute(self::BASE_URL . $method, array_merge($arguments, [ @@ -19,13 +36,21 @@ protected function execute(string $method, $arguments, ?Parameters $parameters): } /** + * Execute multiple API requests in parallel with universal parameters. + * + * @param array $calls An array of method calls, each containing the method name and arguments. + * @param Parameters|null $parameters Optional Parameters object for additional settings. + * + * @return array An array of API responses. * @throws \Throwable */ protected function execute_in_parallel(array $calls, ?Parameters $parameters = null): array { - if(is_null($parameters)) $parameters = new Parameters(); + if (is_null($parameters)) { + $parameters = new Parameters(); + } - for($i = 0; $i < count($calls); $i++) { + for ($i = 0; $i < count($calls); $i++) { $calls[$i][0] = self::BASE_URL . $calls[$i][0]; $calls[$i][1]['format'] = $parameters->format->value; } diff --git a/tests/Integration/IndicesTest.php b/tests/Integration/IndicesTest.php index 561130a..435df3d 100644 --- a/tests/Integration/IndicesTest.php +++ b/tests/Integration/IndicesTest.php @@ -11,11 +11,22 @@ use MarketDataApp\Enums\Format; use PHPUnit\Framework\TestCase; +/** + * Class IndicesTest + * + * Integration tests for indices-related functionality in the MarketDataApp. + */ class IndicesTest extends TestCase { + /** + * @var Client The client instance used for testing. + */ private Client $client; + /** + * Set up the test environment. + */ protected function setUp(): void { $token = "your_api_token"; @@ -23,6 +34,9 @@ protected function setUp(): void $this->client = $client; } + /** + * Test successful quote retrieval. + */ public function testQuote_success() { $response = $this->client->indices->quote("VIX"); @@ -37,6 +51,9 @@ public function testQuote_success() $this->assertInstanceOf(Carbon::class, $response->updated); } + /** + * Test successful quote retrieval in CSV format. + */ public function testQuote_csv_success() { $response = $this->client->indices->quote(symbol: "VIX", parameters: new Parameters(format: Format::CSV)); @@ -44,7 +61,9 @@ public function testQuote_csv_success() $this->assertEquals('string', gettype($response->getCsv())); } - + /** + * Test successful retrieval of multiple quotes. + */ public function testQuotes_success() { $response = $this->client->indices->quotes(['VIX']); @@ -60,8 +79,9 @@ public function testQuotes_success() $this->assertInstanceOf(Carbon::class, $response->quotes[0]->updated); } - /** + * Test successful candles retrieval. + * * @throws GuzzleException */ public function testCandles_success() @@ -85,6 +105,8 @@ public function testCandles_success() } /** + * Test candles retrieval with no data. + * * @throws GuzzleException */ public function testCandles_noData() diff --git a/tests/Integration/MutualFundsTest.php b/tests/Integration/MutualFundsTest.php index b2ec8e8..01d7493 100644 --- a/tests/Integration/MutualFundsTest.php +++ b/tests/Integration/MutualFundsTest.php @@ -10,11 +10,22 @@ use MarketDataApp\Enums\Format; use PHPUnit\Framework\TestCase; +/** + * Class MutualFundsTest + * + * Integration tests for mutual funds-related functionality in the MarketDataApp. + */ class MutualFundsTest extends TestCase { + /** + * @var Client The client instance used for testing. + */ private Client $client; + /** + * Set up the test environment. + */ protected function setUp(): void { $token = 'your_api_token'; @@ -22,6 +33,9 @@ protected function setUp(): void $this->client = $client; } + /** + * Test successful candles retrieval for mutual funds. + */ public function testCandles_success() { $response = $this->client->mutual_funds->candles( @@ -44,6 +58,9 @@ public function testCandles_success() $this->assertInstanceOf(Carbon::class, $response->candles[0]->timestamp); } + /** + * Test successful candles retrieval for mutual funds in CSV format. + */ public function testCandles_csv_success() { $response = $this->client->mutual_funds->candles( diff --git a/tests/Integration/OptionsTest.php b/tests/Integration/OptionsTest.php index b6f9bc0..2040434 100644 --- a/tests/Integration/OptionsTest.php +++ b/tests/Integration/OptionsTest.php @@ -17,11 +17,25 @@ use MarketDataApp\Enums\Side; use PHPUnit\Framework\TestCase; +/** + * Class OptionsTest + * + * Integration tests for options-related functionality in the MarketDataApp. + * This class tests various API endpoints related to options, including + * expirations, lookups, strikes, quotes, and option chains. + */ class OptionsTest extends TestCase { + /** + * @var Client The client instance used for testing. + */ private Client $client; + /** + * Set up the test environment. + * Initializes a new Client instance with the API token. + */ protected function setUp(): void { $token = 'your_api_token'; @@ -29,37 +43,50 @@ protected function setUp(): void $this->client = $client; } + /** + * Test successful retrieval of option expirations. + * Verifies that the response contains valid expiration dates. + */ public function testExpirations_success() { $response = $this->client->options->expirations('AAPL'); - // Verify that the response is an object of the correct type. $this->assertInstanceOf(Expirations::class, $response); $this->assertNotEmpty($response->expirations); $this->assertInstanceOf(Carbon::class, $response->updated); $this->assertInstanceOf(Carbon::class, $response->expirations[0]); } + /** + * Test successful retrieval of option expirations in CSV format. + * Verifies that the response is a string containing CSV data. + */ public function testExpirations_csv_success() { $response = $this->client->options->expirations( symbol: 'AAPL', parameters: new Parameters(format: Format::CSV) ); - // Verify that the response is an object of the correct type. $this->assertInstanceOf(Expirations::class, $response); $this->assertEquals('string', gettype($response->getCsv())); } + /** + * Test successful lookup of an option symbol. + * Verifies that the response contains the correct option symbol. + */ public function testLookup_success() { $response = $this->client->options->lookup('AAPL 7/28/23 $200 Call'); - // Verify that the response is an object of the correct type. $this->assertInstanceOf(Lookup::class, $response); $this->assertEquals('AAPL230728C00200000', $response->option_symbol); } + /** + * Test successful retrieval of option strikes. + * Verifies that the response contains valid strike prices. + */ public function testStrikes_success() { $response = $this->client->options->strikes( @@ -67,13 +94,16 @@ public function testStrikes_success() date: '2023-01-03', ); - // Verify that the response is an object of the correct type. $this->assertInstanceOf(Strikes::class, $response); $this->assertInstanceOf(Carbon::class, $response->updated); $this->assertNotEmpty($response->dates); $this->assertNotEmpty(array_pop($response->dates)); } + /** + * Test successful retrieval of option strikes in CSV format. + * Verifies that the response is a string containing CSV data. + */ public function testStrikes_csv_success() { $response = $this->client->options->strikes( @@ -82,11 +112,14 @@ public function testStrikes_csv_success() parameters: new Parameters(format: Format::CSV), ); - // Verify that the response is an object of the correct type. $this->assertInstanceOf(Strikes::class, $response); $this->assertEquals('string', gettype($response->getCsv())); } + /** + * Test successful retrieval of option quotes. + * Verifies that the response contains valid quote data with correct types. + */ public function testQuotes_success() { $response = $this->client->options->quotes('AAPL250117C00150000'); @@ -95,7 +128,6 @@ public function testQuotes_success() $this->assertEquals('ok', $response->status); $this->assertNotEmpty($response->quotes); - // Verify that the response is an object of the correct type. $this->assertInstanceOf(Quote::class, $response->quotes[0]); $this->assertEquals('string', gettype($response->quotes[0]->option_symbol)); $this->assertEquals('double', gettype($response->quotes[0]->ask)); @@ -119,6 +151,10 @@ public function testQuotes_success() $this->assertInstanceOf(Carbon::class, $response->quotes[0]->updated); } + /** + * Test successful retrieval of option quotes in CSV format. + * Verifies that the response is a string containing CSV data. + */ public function testQuotes_csv_success() { $response = $this->client->options->quotes( @@ -130,6 +166,10 @@ public function testQuotes_csv_success() $this->assertEquals('string', gettype($response->getCsv())); } + /** + * Test successful retrieval of option chain. + * Verifies that the response contains valid option chain data with correct types. + */ public function testOptionChain_success() { $response = $this->client->options->option_chain( @@ -138,13 +178,11 @@ public function testOptionChain_success() side: Side::CALL, ); - // Verify that the response is an object of the correct type. $this->assertInstanceOf(OptionChains::class, $response); $this->assertNotEmpty($response->option_chains); $option_chain = array_pop($response->option_chains); $this->assertNotEmpty($option_chain); - // Verify each item in the response is an object of the correct type and has the correct values. $option_strike = array_pop($option_chain); $this->assertInstanceOf(OptionChainStrike::class, $option_strike); $this->assertEquals('string', gettype($option_strike->option_symbol)); @@ -175,6 +213,10 @@ public function testOptionChain_success() $this->assertEquals('double', gettype($option_strike->underlying_price)); } + /** + * Test successful retrieval of option chain in CSV format. + * Verifies that the response is a string containing CSV data. + */ public function testOptionChain_csv_success() { $response = $this->client->options->option_chain( @@ -184,11 +226,15 @@ public function testOptionChain_csv_success() parameters: new Parameters(format: Format::CSV), ); - // Verify that the response is an object of the correct type. $this->assertInstanceOf(OptionChains::class, $response); $this->assertEquals('string', gettype($response->getCsv())); } + /** + * Test successful retrieval of option chain using Expiration enum. + * Verifies that the response contains valid option chain data with correct types + * when using the Expiration::ALL enum value. + */ public function testOptionChain_expirationEnum_success() { $response = $this->client->options->option_chain( @@ -197,13 +243,11 @@ public function testOptionChain_expirationEnum_success() side: Side::CALL, ); - // Verify that the response is an object of the correct type. $this->assertInstanceOf(OptionChains::class, $response); $this->assertNotEmpty($response->option_chains); $option_chain = array_pop($response->option_chains); $this->assertNotEmpty($option_chain); - // Verify each item in the response is an object of the correct type and has the correct values. $option_strike = array_pop($option_chain); $this->assertInstanceOf(OptionChainStrike::class, $option_strike); $this->assertEquals('string', gettype($option_strike->option_symbol)); diff --git a/tests/Integration/StocksTest.php b/tests/Integration/StocksTest.php index 8fb86a5..0f7519b 100644 --- a/tests/Integration/StocksTest.php +++ b/tests/Integration/StocksTest.php @@ -17,11 +17,25 @@ use MarketDataApp\Exceptions\ApiException; use PHPUnit\Framework\TestCase; +/** + * Class StocksTest + * + * Integration tests for stocks-related functionality in the MarketDataApp. + * This class tests various API endpoints related to stocks, including + * candles, quotes, bulk quotes, and earnings data. + */ class StocksTest extends TestCase { + /** + * @var Client The client instance used for testing. + */ private Client $client; + /** + * Set up the test environment. + * Initializes a new Client instance with the API token. + */ protected function setUp(): void { error_reporting(E_ALL); @@ -31,6 +45,8 @@ protected function setUp(): void } /** + * Test successful retrieval of stock candles. + * * @throws GuzzleException|ApiException */ public function testCandles_success() @@ -42,11 +58,9 @@ public function testCandles_success() resolution: 'D' ); - // Verify that the response is an object of the correct type. $this->assertInstanceOf(Candles::class, $response); $this->assertNotEmpty($response->candles); - // Verify each item in the response is an object of the correct type and has the correct values. $this->assertInstanceOf(Candle::class, $response->candles[0]); $this->assertEquals('double', gettype($response->candles[0]->close)); $this->assertEquals('double', gettype($response->candles[0]->high)); @@ -56,6 +70,9 @@ public function testCandles_success() $this->assertInstanceOf(Carbon::class, $response->candles[0]->timestamp); } + /** + * Test successful retrieval of stock candles in CSV format. + */ public function testCandles_csv_success() { $response = $this->client->stocks->candles( @@ -66,12 +83,13 @@ public function testCandles_csv_success() parameters: new Parameters(format: Format::CSV) ); - // Verify that the response is an object of the correct type. $this->assertInstanceOf(Candles::class, $response); $this->assertEquals('string', gettype($response->getCsv())); } /** + * Test successful retrieval of bulk stock candles. + * * @throws GuzzleException|ApiException */ public function testBulkCandles_success() @@ -81,11 +99,9 @@ public function testBulkCandles_success() resolution: 'D' ); - // Verify that the response is an object of the correct type. $this->assertInstanceOf(BulkCandles::class, $response); $this->assertNotEmpty($response->candles); - // Verify each item in the response is an object of the correct type and has the correct values. $this->assertInstanceOf(Candle::class, $response->candles[0]); $this->assertEquals('double', gettype($response->candles[0]->close)); $this->assertEquals('double', gettype($response->candles[0]->high)); @@ -96,6 +112,8 @@ public function testBulkCandles_success() } /** + * Test successful retrieval of bulk stock candles in CSV format. + * * @throws GuzzleException|ApiException */ public function testBulkCandles_csv_success() @@ -106,11 +124,13 @@ public function testBulkCandles_csv_success() parameters: new Parameters(format: Format::CSV) ); - // Verify that the response is an object of the correct type. $this->assertInstanceOf(BulkCandles::class, $response); $this->assertEquals('string', gettype($response->getCsv())); } + /** + * Test successful retrieval of a stock quote. + */ public function testQuote_success() { $response = $this->client->stocks->quote('AAPL'); @@ -132,6 +152,9 @@ public function testQuote_success() $this->assertInstanceOf(Carbon::class, $response->updated); } + /** + * Test successful retrieval of a stock quote in CSV format. + */ public function testQuote_csv_success() { $response = $this->client->stocks->quote( @@ -143,6 +166,9 @@ public function testQuote_csv_success() $this->assertEquals('string', gettype($response->getCsv())); } + /** + * Test successful retrieval of multiple stock quotes. + */ public function testQuotes_success() { $response = $this->client->stocks->quotes(['AAPL']); @@ -165,6 +191,8 @@ public function testQuotes_success() } /** + * Test successful retrieval of bulk stock quotes. + * * @throws \Throwable */ public function testBulkQuotes_success() @@ -189,6 +217,8 @@ public function testBulkQuotes_success() } /** + * Test successful retrieval of bulk stock quotes in CSV format. + * * @throws \Throwable */ public function testBulkQuotes_csv_success() @@ -201,9 +231,12 @@ public function testBulkQuotes_csv_success() $this->assertNotEmpty($response->getCsv()); } + /** + * Test successful retrieval of earnings data. + */ public function testEarnings_success() { - $response = $this->client->stocks->earnings(symbol: 'AAPL', from: '2023-01-01'); + $response = $this->client->stocks->earnings(symbol: 'AAPL', from: '2024-01-01'); $this->assertInstanceOf(Earnings::class, $response); $this->assertNotEmpty($response->earnings); @@ -223,11 +256,14 @@ public function testEarnings_success() $this->assertInstanceOf(Carbon::class, $response->earnings[0]->updated); } + /** + * Test successful retrieval of earnings data in CSV format. + */ public function testEarnings_csv_success() { $response = $this->client->stocks->earnings( symbol: 'AAPL', - from: '2023-01-01', + from: '2024-01-01', parameters: new Parameters(format: Format::CSV) ); diff --git a/tests/Integration/UtilitiesTest.php b/tests/Integration/UtilitiesTest.php index 21f1ff0..67ffc55 100644 --- a/tests/Integration/UtilitiesTest.php +++ b/tests/Integration/UtilitiesTest.php @@ -9,11 +9,24 @@ use MarketDataApp\Endpoints\Responses\Utilities\ServiceStatus; use PHPUnit\Framework\TestCase; +/** + * Integration tests for the Utilities endpoints of the MarketDataApp API. + */ class UtilitiesTest extends TestCase { + /** + * The MarketDataApp API client instance. + * + * @var Client + */ private Client $client; + /** + * Set up the test environment. + * + * @return void + */ protected function setUp(): void { $token = 'your_api_token'; @@ -21,6 +34,11 @@ protected function setUp(): void $this->client = $client; } + /** + * Test the API status endpoint. + * + * @return void + */ public function testApiStatus_success() { $response = $this->client->utilities->api_status(); @@ -37,6 +55,11 @@ public function testApiStatus_success() $this->assertInstanceOf(Carbon::class, $response->services[0]->updated); } + /** + * Test the headers endpoint. + * + * @return void + */ public function testHeaders_success() { $response = $this->client->utilities->headers(); diff --git a/tests/Traits/MockResponses.php b/tests/Traits/MockResponses.php index c9e8699..dd791a7 100644 --- a/tests/Traits/MockResponses.php +++ b/tests/Traits/MockResponses.php @@ -6,9 +6,22 @@ use GuzzleHttp\Handler\MockHandler; use GuzzleHttp\HandlerStack; +/** + * Trait for setting up mock responses in HTTP client tests. + */ trait MockResponses { + /** + * Set mock responses for the HTTP client. + * + * This method creates a new GuzzleHttp client with a mock handler + * and sets it on the current client instance. + * + * @param array $responses An array of mock responses to be returned by the client. + * + * @return void + */ private function setMockResponses(array $responses): void { $mock = new MockHandler($responses); diff --git a/tests/Unit/IndicesTest.php b/tests/Unit/IndicesTest.php index ec293d7..4b66709 100644 --- a/tests/Unit/IndicesTest.php +++ b/tests/Unit/IndicesTest.php @@ -18,13 +18,28 @@ use MarketDataApp\Tests\Traits\MockResponses; use PHPUnit\Framework\TestCase; +/** + * Test case for the Indices endpoints of the MarketDataApp. + * + * This class tests various scenarios of the quote endpoint for indices data. + */ class IndicesTest extends TestCase { use MockResponses; + /** + * The client instance used for testing. + * + * @var Client + */ private Client $client; + /** + * Mocked response data for AAPL stock. + * + * @var array + */ private array $aapl_mocked_response = [ 's' => 'ok', 'symbol' => ['AAPL'], @@ -36,6 +51,13 @@ class IndicesTest extends TestCase 'updated' => ['2020-01-01T00:00:00.000000Z'], ]; + /** + * Set up the test environment. + * + * This method is called before each test. + * + * @return void + */ protected function setUp(): void { $token = "your_api_token"; @@ -43,6 +65,13 @@ protected function setUp(): void $this->client = $client; } + /** + * Test the quote endpoint for a successful JSON response. + * + * @return void + * @throws GuzzleException + * @throws ApiException + */ public function testQuote_success() { $mocked_response = [ @@ -69,6 +98,13 @@ public function testQuote_success() $this->assertEquals(Carbon::parse($mocked_response['updated'][0]), $response->updated); } + /** + * Test the quote endpoint for a successful CSV response. + * + * @return void + * @throws GuzzleException + * @throws ApiException + */ public function testQuote_csv_success() { $mocked_response = 's, symbol, last, change, changepct, 52weekHigh, 52weekLow, updated'; @@ -78,6 +114,13 @@ public function testQuote_csv_success() $this->assertEquals($mocked_response, $response->getCsv()); } + /** + * Test the quote endpoint for a successful HTML response. + * + * @return void + * @throws GuzzleException + * @throws ApiException + */ public function testQuote_HTML_success() { $mocked_response = '
Hello World
'; @@ -87,8 +130,10 @@ public function testQuote_HTML_success() $this->assertEquals($mocked_response, $response->getHtml()); } - /** + * Test the quotes endpoint for multiple symbols. + * + * @return void * @throws GuzzleException * @throws \Throwable */ @@ -126,6 +171,13 @@ public function testQuotes_success() } } + /** + * Test the quote endpoint for a successful 'no data' response. + * + * @return void + * @throws GuzzleException + * @throws ApiException + */ public function testQuote_noData_success() { $mocked_response = [ @@ -146,7 +198,11 @@ public function testQuote_noData_success() } /** + * Test the candles endpoint for a successful response with 'from' and 'to' parameters. + * + * @return void * @throws GuzzleException + * @throws ApiException */ public function testCandles_fromTo_success() { @@ -182,9 +238,12 @@ public function testCandles_fromTo_success() } } - /** - * @throws GuzzleException|ApiException + * Test the candles endpoint for a successful CSV response. + * + * @return void + * @throws GuzzleException + * @throws ApiException */ public function testCandles_csv_success() { @@ -205,7 +264,11 @@ public function testCandles_csv_success() } /** + * Test the candles endpoint for a successful 'no data' response. + * + * @return void * @throws GuzzleException + * @throws ApiException */ public function testCandles_noData_success() { @@ -230,7 +293,11 @@ public function testCandles_noData_success() } /** + * Test the candles endpoint for a successful 'no data' response with next and previous times. + * + * @return void * @throws GuzzleException + * @throws ApiException */ public function testCandles_noDataNextTimePrevTime_success() { @@ -258,6 +325,11 @@ public function testCandles_noDataNextTimePrevTime_success() $this->assertEquals(Carbon::parse($mocked_response['prevTime']), $response->next_time); } + /** + * Test exception handling for GuzzleException. + * + * @return void + */ public function testExceptionHandling_throwsGuzzleException() { $this->setMockResponses([ @@ -268,6 +340,11 @@ public function testExceptionHandling_throwsGuzzleException() $this->client->indices->quote("INVALID"); } + /** + * Test exception handling for ApiException. + * + * @return void + */ public function testExceptionHandling_throwsApiException() { $mocked_response = [ diff --git a/tests/Unit/MarketsTest.php b/tests/Unit/MarketsTest.php index 12212d3..9bec3ff 100644 --- a/tests/Unit/MarketsTest.php +++ b/tests/Unit/MarketsTest.php @@ -12,13 +12,30 @@ use MarketDataApp\Tests\Traits\MockResponses; use PHPUnit\Framework\TestCase; +/** + * Test case for the Markets endpoints of the MarketDataApp. + * + * This class tests the functionality of the market status endpoint. + */ class MarketsTest extends TestCase { use MockResponses; + /** + * The client instance used for testing. + * + * @var Client + */ private Client $client; + /** + * Set up the test environment. + * + * This method is called before each test. + * + * @return void + */ protected function setUp(): void { $token = "your_api_token"; @@ -26,6 +43,11 @@ protected function setUp(): void $this->client = $client; } + /** + * Test the status endpoint for a successful response. + * + * @return void + */ public function testStatus_success() { $mocked_response = [ @@ -50,6 +72,12 @@ public function testStatus_success() $this->assertEquals($mocked_response['status'][$i], $response->statuses[$i]->status); } } + + /** + * Test the status endpoint with CSV format for a successful response. + * + * @return void + */ public function testStatus_csv_success() { $mocked_response = 's, date, status'; diff --git a/tests/Unit/MutualFundsTest.php b/tests/Unit/MutualFundsTest.php index dd440a8..1733cf7 100644 --- a/tests/Unit/MutualFundsTest.php +++ b/tests/Unit/MutualFundsTest.php @@ -14,13 +14,30 @@ use MarketDataApp\Tests\Traits\MockResponses; use PHPUnit\Framework\TestCase; +/** + * Test case for the Mutual Funds endpoints of the MarketDataApp. + * + * This class tests various scenarios of the candles endpoint for mutual funds data. + */ class MutualFundsTest extends TestCase { use MockResponses; + /** + * The client instance used for testing. + * + * @var Client + */ private Client $client; + /** + * Set up the test environment. + * + * This method is called before each test. + * + * @return void + */ protected function setUp(): void { $token = 'your_api_token'; @@ -28,6 +45,13 @@ protected function setUp(): void $this->client = $client; } + /** + * Test the candles endpoint with 'from' and 'to' parameters for a successful response. + * + * @return void + * @throws GuzzleException + * @throws ApiException + */ public function testCandles_fromTo_success() { $mocked_response = [ @@ -61,6 +85,14 @@ public function testCandles_fromTo_success() $this->assertEquals(Carbon::parse($mocked_response['t'][$i]), $response->candles[$i]->timestamp); } } + + /** + * Test the candles endpoint with CSV format for a successful response. + * + * @return void + * @throws GuzzleException + * @throws ApiException + */ public function testCandles_csv_success() { $mocked_response = "s, t, o, h, l, c\r\n"; @@ -80,7 +112,11 @@ public function testCandles_csv_success() } /** - * @throws GuzzleException|ApiException + * Test the candles endpoint for a successful response with no data. + * + * @return void + * @throws GuzzleException + * @throws ApiException */ public function testCandles_noData_success() { @@ -103,7 +139,11 @@ public function testCandles_noData_success() } /** - * @throws GuzzleException|ApiException + * Test the candles endpoint for a successful response with no data and next time. + * + * @return void + * @throws GuzzleException + * @throws ApiException */ public function testCandles_noDataNextTime_success() { diff --git a/tests/Unit/OptionsTest.php b/tests/Unit/OptionsTest.php index 09789a3..0b37fe3 100644 --- a/tests/Unit/OptionsTest.php +++ b/tests/Unit/OptionsTest.php @@ -18,13 +18,30 @@ use MarketDataApp\Tests\Traits\MockResponses; use PHPUnit\Framework\TestCase; +/** + * Test case for the Options endpoints of the MarketDataApp. + * + * This class tests various scenarios of the options-related endpoints. + */ class OptionsTest extends TestCase { use MockResponses; + /** + * The client instance used for testing. + * + * @var Client + */ private Client $client; + /** + * Set up the test environment. + * + * This method is called before each test. + * + * @return void + */ protected function setUp(): void { $token = 'your_api_token'; @@ -32,6 +49,11 @@ protected function setUp(): void $this->client = $client; } + /** + * Test the expirations endpoint for a successful response. + * + * @return void + */ public function testExpirations_success() { $mocked_response = [ @@ -54,6 +76,11 @@ public function testExpirations_success() } } + /** + * Test the expirations endpoint for a successful CSV response. + * + * @return void + */ public function testExpirations_csv_success() { $mocked_response = "s, expirations, updated\r\n"; @@ -69,6 +96,11 @@ public function testExpirations_csv_success() $this->assertEquals($mocked_response, $response->getCsv()); } + /** + * Test the expirations endpoint for a successful 'no data' response. + * + * @return void + */ public function testExpirations_noData_success() { $mocked_response = [ @@ -87,6 +119,11 @@ public function testExpirations_noData_success() $this->assertEquals(Carbon::parse($mocked_response['prevTime']), $response->prev_time); } + /** + * Test the lookup endpoint for a successful response. + * + * @return void + */ public function testLookup_success() { $mocked_response = [ @@ -102,7 +139,11 @@ public function testLookup_success() $this->assertEquals($mocked_response['optionSymbol'], $response->option_symbol); } - + /** + * Test the lookup endpoint for a successful CSV response. + * + * @return void + */ public function testLookup_csv_success() { $mocked_response = "s, optionSymbol\r\n"; @@ -115,6 +156,11 @@ public function testLookup_csv_success() $this->assertEquals($mocked_response, $response->getCsv()); } + /** + * Test the strikes endpoint for a successful response. + * + * @return void + */ public function testStrikes_success() { $mocked_response = [ @@ -139,6 +185,11 @@ public function testStrikes_success() $this->assertEquals($mocked_response['2023-01-20'], $response->dates['2023-01-20']); } + /** + * Test the strikes endpoint for a successful CSV response. + * + * @return void + */ public function testStrikes_csv_success() { $mocked_response = "s, updated, 2023-01-20\r\n"; @@ -156,6 +207,11 @@ public function testStrikes_csv_success() $this->assertEquals($mocked_response, $response->getCsv()); } + /** + * Test the strikes endpoint for a successful 'no data' response. + * + * @return void + */ public function testStrikes_noData_success() { $mocked_response = [ @@ -178,6 +234,11 @@ public function testStrikes_noData_success() $this->assertEquals(Carbon::parse($mocked_response['prevTime']), $response->prev_time); } + /** + * Test the quotes endpoint for a successful response. + * + * @return void + */ public function testQuotes_success() { $mocked_response = [ @@ -237,6 +298,11 @@ public function testQuotes_success() } } + /** + * Test the quotes endpoint for a successful CSV response. + * + * @return void + */ public function testQuotes_csv_success() { $mocked_response = "s, optionSymbol, ask...\r\n"; @@ -252,6 +318,11 @@ public function testQuotes_csv_success() $this->assertEquals($mocked_response, $response->getCsv()); } + /** + * Test the quotes endpoint for a successful 'no data' response. + * + * @return void + */ public function testQuotes_noData_success() { $mocked_response = [ @@ -270,6 +341,11 @@ public function testQuotes_noData_success() $this->assertEquals(Carbon::parse($mocked_response['prevTime']), $response->prev_time); } + /** + * Test the option_chain endpoint for a successful response. + * + * @return void + */ public function testOptionChain_success() { $mocked_response = [ @@ -348,8 +424,11 @@ public function testOptionChain_success() } } - - + /** + * Test the option_chain endpoint for a successful CSV response. + * + * @return void + */ public function testOptionChain_csv_success() { $mocked_response = "s, optionSymbol, underlying...\r\n"; @@ -366,6 +445,11 @@ public function testOptionChain_csv_success() $this->assertEquals($mocked_response, $response->getCsv()); } + /** + * Test the option_chain endpoint for a successful 'no data' response. + * + * @return void + */ public function testOptionChain_noData_success() { $mocked_response = [ diff --git a/tests/Unit/StocksTest.php b/tests/Unit/StocksTest.php index adf1040..a76fac9 100644 --- a/tests/Unit/StocksTest.php +++ b/tests/Unit/StocksTest.php @@ -25,13 +25,28 @@ use MarketDataApp\Tests\Traits\MockResponses; use PHPUnit\Framework\TestCase; +/** + * Test case for the Stocks endpoints of the MarketDataApp. + * + * This class tests various scenarios of the stocks-related endpoints. + */ class StocksTest extends TestCase { use MockResponses; + /** + * The client instance used for testing. + * + * @var Client + */ private Client $client; + /** + * Mocked response data for AAPL stock. + * + * @var array + */ private array $aapl_mocked_response = [ 's' => 'ok', 'symbol' => ['AAPL'], @@ -47,6 +62,11 @@ class StocksTest extends TestCase 'updated' => [1663958092] ]; + /** + * Mocked response data for multiple stocks. + * + * @var array + */ private array $multiple_mocked_response = [ 's' => 'ok', 'symbol' => ['APPL', 'NFLX'], @@ -62,6 +82,13 @@ class StocksTest extends TestCase 'updated' => [1663958094, 1663958092] ]; + /** + * Set up the test environment. + * + * This method is called before each test. + * + * @return void + */ protected function setUp(): void { $token = "your_api_token"; @@ -70,7 +97,11 @@ protected function setUp(): void } /** - * @throws GuzzleException|ApiException + * Test the candles endpoint for a successful response with 'from' and 'to' parameters. + * + * @return void + * @throws GuzzleException + * @throws ApiException */ public function testCandles_fromTo_success() { @@ -108,6 +139,13 @@ public function testCandles_fromTo_success() } } + /** + * Test the candles endpoint for a successful CSV response. + * + * @return void + * @throws GuzzleException + * @throws ApiException + */ public function testCandles_csv_success() { $mocked_response = "s, c, h, l, o, v, t"; @@ -127,7 +165,11 @@ public function testCandles_csv_success() } /** - * @throws GuzzleException|ApiException + * Test the candles endpoint for a successful 'no data' response. + * + * @return void + * @throws GuzzleException + * @throws ApiException */ public function testCandles_noData_success() { @@ -150,7 +192,11 @@ public function testCandles_noData_success() } /** - * @throws GuzzleException|ApiException + * Test the candles endpoint for a successful 'no data' response with next time. + * + * @return void + * @throws GuzzleException + * @throws ApiException */ public function testCandles_noDataNextTime_success() { @@ -173,9 +219,12 @@ public function testCandles_noDataNextTime_success() $this->assertEmpty($response->candles); } - /** - * @throws GuzzleException|ApiException + * Test the bulkCandles endpoint for a successful response. + * + * @return void + * @throws GuzzleException + * @throws ApiException */ public function testBulkCandles_success() { @@ -211,6 +260,11 @@ public function testBulkCandles_success() } } + /** + * Test the bulkCandles endpoint for a successful CSV response. + * + * @return void + */ public function testBulkCandles_csv_success() { $mocked_response = "s, c, h, l, o, v, t"; @@ -228,7 +282,11 @@ public function testBulkCandles_csv_success() } /** - * @throws GuzzleException|ApiException + * Test the bulkCandles endpoint for a successful 'no data' response. + * + * @return void + * @throws GuzzleException + * @throws ApiException */ public function testBulkCandles_noData_success() { @@ -248,7 +306,11 @@ public function testBulkCandles_noData_success() } /** - * @throws GuzzleException|ApiException + * Test the bulkCandles endpoint for invalid arguments. + * + * @return void + * @throws GuzzleException + * @throws ApiException */ public function testBulkCandles_invalidArguments_throwsInvalidArgumentException() { @@ -258,6 +320,11 @@ public function testBulkCandles_invalidArguments_throwsInvalidArgumentException( $this->client->stocks->bulkCandles(resolution: 'D'); } + /** + * Test the quote endpoint for a successful response. + * + * @return void + */ public function testQuote_success() { $mocked_response = $this->aapl_mocked_response; @@ -283,6 +350,11 @@ public function testQuote_success() $this->assertEquals(Carbon::parse($mocked_response['updated'][0]), $quote->updated); } + /** + * Test the quote endpoint for a successful CSV response. + * + * @return void + */ public function testQuote_csv_success() { $mocked_response = "a, b, c"; @@ -298,6 +370,11 @@ public function testQuote_csv_success() $this->assertEquals($mocked_response, $quote->getCsv()); } + /** + * Test the quote endpoint for a successful response with 52-week high/low. + * + * @return void + */ public function testQuote_52week_success() { $mocked_response = $this->aapl_mocked_response; @@ -326,6 +403,9 @@ public function testQuote_52week_success() } /** + * Test the quotes endpoint for a successful response. + * + * @return void * @throws GuzzleException * @throws \Throwable */ @@ -372,6 +452,9 @@ public function testQuotes_success() } /** + * Test the bulkQuotes endpoint for a successful response. + * + * @return void * @throws \Throwable */ public function testBulkQuotes_success() @@ -403,6 +486,11 @@ public function testBulkQuotes_success() } } + /** + * Test the bulkQuotes endpoint for a successful CSV response. + * + * @return void + */ public function testBulkQuotes_csv_success() { $mocked_response = "a, b, c"; @@ -417,6 +505,9 @@ public function testBulkQuotes_csv_success() } /** + * Test the bulkQuotes endpoint for a successful response with 52-week high/low. + * + * @return void * @throws \Throwable */ public function testBulkQuotes_52week_success() @@ -451,6 +542,9 @@ public function testBulkQuotes_52week_success() } /** + * Test the bulkQuotes endpoint for a successful response with snapshot parameter. + * + * @return void * @throws GuzzleException */ public function testBulkQuotes_snapshot_success() @@ -481,6 +575,9 @@ public function testBulkQuotes_snapshot_success() } /** + * Test the bulkQuotes endpoint for an exception when no parameters are provided. + * + * @return void * @throws GuzzleException */ public function testBulkQuotes_noParameters_throwsException() @@ -489,6 +586,11 @@ public function testBulkQuotes_noParameters_throwsException() $this->client->stocks->bulkQuotes(); } + /** + * Test the earnings endpoint for a successful response. + * + * @return void + */ public function testEarnings_success() { $mocked_response = [ @@ -531,6 +633,11 @@ public function testEarnings_success() } } + /** + * Test the earnings endpoint for a successful CSV response. + * + * @return void + */ public function testEarnings_csv_success() { $mocked_response = "s, symbol, fiscalYear..."; @@ -546,7 +653,11 @@ public function testEarnings_csv_success() } /** - * @throws GuzzleException|ApiException + * Test the earnings endpoint for an exception when neither 'from' nor 'countback' is provided. + * + * @return void + * @throws GuzzleException + * @throws ApiException */ public function testEarnings_noFromOrCountback_throwsException() { @@ -554,6 +665,11 @@ public function testEarnings_noFromOrCountback_throwsException() $this->client->stocks->earnings('AAPL'); } + /** + * Test the news endpoint for a successful response. + * + * @return void + */ public function testNews_success() { $mocked_response = [ @@ -576,6 +692,11 @@ public function testNews_success() $this->assertEquals(Carbon::parse($mocked_response['publicationDate']), $news->publication_date); } + /** + * Test the news endpoint for a successful CSV response. + * + * @return void + */ public function testNews_csv_success() { $mocked_response = "s, symbol, headline..."; @@ -590,12 +711,22 @@ public function testNews_csv_success() $this->assertEquals($mocked_response, $news->getCsv()); } + /** + * Test the news endpoint for an exception when neither 'from' nor 'countback' is provided. + * + * @return void + */ public function testNews_noFromOrCountback_throwsException() { $this->expectException(\InvalidArgumentException::class); $this->client->stocks->news('AAPL'); } + /** + * Test exception handling for GuzzleException. + * + * @return void + */ public function testExceptionHandling_throwsGuzzleException() { $this->setMockResponses([ diff --git a/tests/Unit/UtilitiesTest.php b/tests/Unit/UtilitiesTest.php index 28f39e3..c5a1eac 100644 --- a/tests/Unit/UtilitiesTest.php +++ b/tests/Unit/UtilitiesTest.php @@ -11,13 +11,30 @@ use MarketDataApp\Tests\Traits\MockResponses; use PHPUnit\Framework\TestCase; +/** + * Test case for the Utilities endpoints of the MarketDataApp. + * + * This class tests the functionality of the API status and headers endpoints. + */ class UtilitiesTest extends TestCase { use MockResponses; + /** + * The client instance used for testing. + * + * @var Client + */ private Client $client; + /** + * Set up the test environment. + * + * This method is called before each test. + * + * @return void + */ protected function setUp(): void { $token = 'your_api_token'; @@ -25,6 +42,11 @@ protected function setUp(): void $this->client = $client; } + /** + * Test the API status endpoint for a successful response. + * + * @return void + */ public function testApiStatus_success() { $mocked_response = [ @@ -55,6 +77,11 @@ public function testApiStatus_success() } } + /** + * Test the headers endpoint for a successful response. + * + * @return void + */ public function testHeaders_success() { $mocked_response = [