# Prices (PHP SDK)

Get real-time midpoint prices for one or more stocks using the SmartMid model.

## Making Requests

Use the `prices()` method on the `stocks` resource to fetch midpoint prices:

| Output Format | Return Type | Description                                                        |
|---------------|-------------|--------------------------------------------------------------------|
| **JSON**      | `Prices`    | Returns a Prices object containing price data (default).           |
| **CSV**       | `Prices`    | Returns a Prices object with CSV data accessible via `getCsv()`.   |
| **HTML**      | `Prices`    | Returns a Prices object with HTML data accessible via `getHtml()`. |

> [!WARNING]
> **HTML Not Yet Available**
>
> `Format::HTML` is included for forward compatibility, but HTML responses are not currently implemented by the Market Data API.

<a name="prices"></a>
## prices

```php
public function prices(
    string|array $symbols,
    bool $extended = true,
    ?Parameters $parameters = null
): Prices
```

Get real-time midpoint prices for stocks using the SmartMid model. Supports both single and multiple symbol requests.

### Parameters

- `symbols` (string|array)

  A single stock ticker symbol as a string (e.g., `"AAPL"`), or an array of symbols (e.g., `['AAPL', 'MSFT']`).

- `extended` (bool, optional)

  Control the inclusion of extended hours (pre-market and after-hours) data. Defaults to `true`.
  - When `true`: Returns the most recent price regardless of trading session.
  - When `false`: Returns only prices from the primary trading session.

- `parameters` ([Parameters](https://www.marketdata.app/docs/sdk/php/parameters), optional)

  Universal parameters for customizing the output format. See [Parameters](https://www.marketdata.app/docs/sdk/php/parameters) for details.

### Returns

- `Prices`

  A Prices response object containing an array of Price objects.

### Notes

- The SmartMid model calculates the midpoint price between the bid and ask, weighted by size and market conditions.
- For single symbols, the API uses the path format `prices/{symbol}/`.
- For multiple symbols, the API uses the query format `prices/?symbols={comma-separated}`.

### Example (Quick Display)

```php
<?php

use MarketDataApp\Client;

$client = new Client();

// Get prices and display with a single line
$prices = $client->stocks->prices(['AAPL', 'MSFT', 'GOOGL']);
echo $prices;

// Or display individual prices
foreach ($prices->prices as $price) {
    echo $price . "\n";
}
```

**Output**

```
Prices: 3 symbols (status: ok)
  AAPL: $186.19 (+0.71%) Change: +$1.31  Updated: Jan 15, 2024 4:00 PM
  MSFT: $380.55 (+1.25%) Change: +$4.70  Updated: Jan 15, 2024 4:00 PM
  GOOGL: $143.12 (-0.50%) Change: -$0.72  Updated: Jan 15, 2024 4:00 PM

AAPL: $186.19 (+0.71%) Change: +$1.31  Updated: Jan 15, 2024 4:00 PM
MSFT: $380.55 (+1.25%) Change: +$4.70  Updated: Jan 15, 2024 4:00 PM
GOOGL: $143.12 (-0.50%) Change: -$0.72  Updated: Jan 15, 2024 4:00 PM
```

### Example (Single Symbol)

```php
<?php

use MarketDataApp\Client;

$client = new Client();

// Get price for a single symbol
$prices = $client->stocks->prices('AAPL');

foreach ($prices->prices as $price) {
    echo "Symbol: " . $price->symbol . "\n";
    echo "Price: $" . number_format($price->mid, 2) . "\n";
    echo "Change: $" . number_format($price->change, 2) . "\n";
    echo "Updated: " . $price->updated->format('Y-m-d H:i:s') . "\n";
}
```

**Output**

```
Symbol: AAPL
Price: $186.19
Updated: 2024-01-15 16:00:00
```

### Example (Multiple Symbols)

```php
<?php

use MarketDataApp\Client;

$client = new Client();

// Get prices for multiple symbols
$prices = $client->stocks->prices(['AAPL', 'MSFT', 'GOOGL', 'AMZN']);

echo "Current Prices\n";
echo "==============\n";

foreach ($prices->prices as $price) {
    echo sprintf(
        "%s: $%.2f (Change: %+.2f%%)\n",
        $price->symbol,
        $price->mid,
        $price->changepct * 100
    );
}
```

**Output**

```
Current Prices
==============
AAPL: $186.19
MSFT: $380.55
GOOGL: $143.12
AMZN: $157.45
```

### Example (Regular Hours)

```php
<?php

use MarketDataApp\Client;

$client = new Client();

// Get prices excluding extended hours
$prices = $client->stocks->prices(
    symbols: ['AAPL', 'MSFT'],
    extended: false
);

// During extended hours, returns closing prices from regular session
foreach ($prices->prices as $price) {
    echo sprintf(
        "%s: $%.2f (Regular Session)\n",
        $price->symbol,
        $price->mid
    );
}
```

### Example (CSV)

```php
<?php

use MarketDataApp\Client;
use MarketDataApp\Endpoints\Requests\Parameters;
use MarketDataApp\Enums\Format;

$client = new Client();

// Get prices as CSV
$prices = $client->stocks->prices(
    symbols: ['AAPL', 'MSFT', 'GOOGL'],
    parameters: new Parameters(format: Format::CSV)
);

echo $prices->getCsv();
```

<a name="Prices"></a>
## Prices

```php
class Prices extends ResponseBase
{
    public string $status;
    /** @var Price[] */
    public array $prices;
}
```

Represents stock prices for one or more symbols. Contains an array of `Price` objects, each representing a single stock's price data.

### Properties

- `status` (string): Response status (`"ok"`, `"no_data"`, or `"error"`).
- `prices` (Price[]): Array of Price objects containing individual stock price data.

### Methods

- `getCsv()`: Returns the raw CSV data (when using `Format::CSV`).
- `getHtml()`: Returns the raw HTML data (when using `Format::HTML`).
- `isJson()`: Returns `true` if the response contains JSON data.

<a name="Price"></a>
## Price

```php
class Price
{
    public string $symbol;
    public float $mid;
    public float $change;
    public float $changepct;
    public Carbon $updated;
}
```

Represents a single stock's price data.

### Properties

- `symbol` (string): The ticker symbol for this price.
- `mid` (float): The midpoint price as calculated by the SmartMid model.
- `change` (float): Price change in currency units compared to the previous day's close.
- `changepct` (float): Price change as a decimal (e.g., 0.03 = 3%).
- `updated` (Carbon): Timestamp when this price was last updated.