Response Formats

Response Formats

The Marketstack PHP SDK offers a variety of response formats, allowing you to choose the one that best fits your application's needs. You can retrieve data as a Laravel Collection, a single Data Transfer Object (DTO), a raw JSON array, or a full HTTP response object.

Available Formats

Here are the methods you can use to specify the response format:

Method	Description
collect()	Executes the request and returns a Illuminate\Support\Collection of DTOs. Ideal for handling multiple results.
dto()	Executes the request and returns a single DTO or null if no result is found. Useful for latest or specific data.
json()	Executes the request and returns a raw JSON array. Good for when you need to work with plain arrays.
get()	Executes the request and returns the raw Illuminate\Http\Client\Response object. For advanced use cases.

Collection of DTOs

This is the recommended format for most use cases, as it provides the power of Laravel Collections combined with the type safety of DTOs.

$collection = Marketstack::eod()
    ->symbols('AAPL')
    ->collect();

Single DTO

When you expect a single result, such as when using the latest() method, dto() is the most convenient option.

$dto = Marketstack::eod()
    ->latest('AAPL')
    ->dto();

Raw JSON Array

If you prefer to work with plain PHP arrays, you can use the json() method.

$json = Marketstack::eod()
    ->symbols('AAPL')
    ->json();

Raw HTTP Response

For advanced scenarios where you need to inspect headers or the status code, you can get the full response object.

$response = Marketstack::eod()
    ->symbols('AAPL')
    ->get();

Working with DTOs

All DTOs in the package provide magic property access for clean and easy reading of data. They also include a toArray() method to convert the DTO to an array.

$eod = Marketstack::eod()
    ->latest('AAPL')
    ->dto();

// Access properties
echo $eod->symbol;
echo $eod->close;
echo $eod->volume;

// Convert to array
$array = $eod->toArray();

// Check if a property exists
if (isset($eod->dividend)) {
    echo "Dividend: {$eod->dividend}";
}

Using DTOs provides significant benefits, including IDE autocompletion, static analysis support, and a reduced risk of runtime errors due to typos or incorrect property access.