# Add a Macro Observation Card to a PHP Application

Canonical: https://fxmacrodata.com/articles/fxmacrodata-php-workflow-guide
Author: Robert Tidball
Published: 2026-10-20T13:24:47Z

Use the generated FXMacroData PHP client, configure header authentication, and handle an empty release history before rendering a card.

**Quick answer:**Use the generated FXMacroData PHP client, configure header authentication, and handle an empty release history before rendering a card.

A policy-rate card in a PHP application should identify the series and period as clearly as it displays the number. It also needs an honest empty state when no observation is returned.

This guide uses the generated FXMacroData PHP client to request the[US policy-rate series](/usd/policy_rate#api-docs) . The example keeps the credential in the server environment and checks for a missing observation before handing a value to the view.

**Who this is for:**Teams using PHP who want a repeatable macro-data workflow with explicit inputs and understandable failure states.

## Prerequisites

A PHP application using Composer and a compatible Guzzle client. The FXMacroData SDK catalogue provides a GitHub VCS installation route for fxmacrodata/fxmacrodata-php. A protected dataset needs a subscription key in FXMACRODATA_API_KEY.

**The working sequence**
- **Configure client**

- **Read observation**

- **Render card**

## 1. Use the documented package route

The SDK is distributed through its GitHub repository. Configure that VCS repository in the project's Composer configuration and require the version shown in the[SDK guide](/documentation/sdks) . Do not assume the package is discoverable on Packagist merely because Composer installs it.

Retain the lockfile and test the package against the PHP version used by the application. Keep the API integration in a server-side service so templates do not need to construct clients or read credentials.

## 2. Configure header authentication

The generated configuration uses the X-API-Key scheme. A free USD example can omit the key; protected requests should read it from the server environment:

```
<?php
require_once __DIR__ . '/vendor/autoload.php';

$config = FXMacroData\Configuration::getDefaultConfiguration();
$key = getenv('FXMACRODATA_API_KEY');
if ($key) {
    $config->setApiKey('X-API-Key', $key);
}
$api = new FXMacroData\Api\FXMacroDataApi(
    new GuzzleHttp\Client(), $config
);
```

Do not expose the key in rendered HTML, a query string or a browser request. Keep request exceptions inside the application's normal error handling and avoid returning credential-bearing diagnostics to visitors.

## 3. Read and check the observation

Continue with the documented announcement method:

```
$rates = $api->getAnnouncements('USD', 'policy_rate');
$latest = $rates->getData()[0] ?? null;
if ($latest === null || $latest->getVal() === null) {
    fwrite(STDERR, "no observations returned\n");
    exit(1);
}
printf("USD policy rate: %s on %s\n",
    $latest->getVal(), $latest->getDate());
```

This command-line check confirms which fields the client exposes. In a web application, replace the diagnostic exit with an unavailable view state. Keep the selected reference date and unit alongside the value instead of rendering an unexplained percentage.

## 4. Render a traceable card

Map the observation into a small view object, escape text through the template engine and link the card to the relevant series page. Show when the application last refreshed the data. If a request fails, decide explicitly whether the view shows unavailable data or a visibly dated previous response.

Add caching at the service boundary according to the application's freshness needs and the data licence. A page view should not create an uncontrolled sequence of identical authenticated requests. Keep the cache key tied to the currency, indicator and request parameters.

## Workflow checks

Part Purpose Configuration Sets the header credential on the server API method Returns the generated response model View object Keeps value, reference date and unit together Template Escapes text and presents unavailable states

**Before relying on the workflow:**Check the empty-response path, request exception path and rendered HTML for credential exposure. Confirm that the card labels the series and period even when the number is unavailable.

## Keep a polished card analytically honest

A policy-rate card often sits beside a pair chart, which encourages the reader to treat the two as contemporaneous. The card should therefore carry its reference date and a useful source link, rather than relying on the page’s refresh time to imply when the economic observation was published. Retrieval freshness and economic reference period answer different questions.

Suppose the visitor changes from a USD series to another currency and the second request fails. Keeping the USD number under the new label would create a false comparison even if the original response was valid. The view object should preserve series identity and provide an unavailable state that the template can render as clearly as a number.

A useful acceptance check is to read the card without the surrounding page. Can the reader name the measure and period, understand its unit, and follow the evidence? Repeat that check for a cached response and a failed refresh. Good application design keeps these facts intact as a response becomes a card, a chart caption or a research export. The visible simplicity comes from making those choices before rendering, rather than asking the template to guess.

## Continue from the working example

Continue with the linked setup guide for supported installation and request options. Keep the selected series and its response context together as the workflow expands.

## Sources and related guides

- [FXMacroData PHP client](https://github.com/fxmacrodata/fxmacrodata-php)

- [FXMacroData PHP setup](/documentation/sdks)

- [Integration directory](/documentation/integrations)

AI was used for research, creating images and editing.

Source: FXMacroData