Skip to Main
View .mdAsk ClaudeAsk ChatGPT

The template functions are the PHP counterpart to the HuxxConnect: "api_id" attribute is required. shortcode: the same configured endpoints, called from a theme template, a block render callback, or another plugin. Unlike the shortcode, nothing is rendered for you — you receive the data and decide the markup. Full signatures are in the Template Function Reference.

Quick version:

$data = huxx_api( 'demo_api', 'get_products', array(
    'query_variables' => array( 'limit' => 5 ),
    'keys'            => 'products.[].title',
    'cache'           => 300,
) );

if ( huxx_api_is_error( $data ) ) {
    $error = huxx_api_get_error( $data );
    error_log( 'DummyJSON failed: ' . $error['message'] );
    return;
}

huxx_connect_api(), huxx_connect_is_error(), and huxx_connect_get_error() are identical long-form names.

Call an endpoint from a template

huxx_api( $api_id, $endpoint_id, $args ) executes a configured endpoint and returns the response — for the default Results Format, a decoded PHP array. This example renders the DummyJSON product list in a theme template:

<?php
// In a theme template file, e.g. page-products.php.
$data = huxx_api( 'demo_api', 'get_products' );

if ( ! huxx_api_is_error( $data ) && ! empty( $data['products'] ) ) : ?>
    <ul class="product-list">
        <?php foreach ( $data['products'] as $product ) : ?>
            <li>
                <?php echo esc_html( $product['title'] ); ?> —
                $<?php echo esc_html( number_format( (float) $product['price'], 2 ) ); ?>
            </li>
        <?php endforeach; ?>
    </ul>
<?php endif;

Output:

<ul class="product-list">
    <li>Essence Mascara Lash Princess — $9.99</li>
    <li>Eyeshadow Palette with Mirror — $19.99</li>
</ul>

Always escape API data on output (esc_html(), esc_url(), esc_attr()) — the response comes from an external server and must be treated as untrusted.

Handle errors before touching the data

A failed call does not return an array you can loop over. huxx_api() returns an ErrorResponse object on failure, or false when either id argument is empty. With debug set, a failure of the HTTP request itself is returned as an error array instead — but configuration failures (unknown API or endpoint id, deactivated API) return an ErrorResponse object regardless of debug. Check every response before use:

<?php
$data = huxx_api( 'demo_api', 'get_products' );

if ( huxx_api_is_error( $data ) ) {
    $error = huxx_api_get_error( $data );
    error_log( sprintf(
        'HuxxConnect error %d: %s',
        $error['code'],
        $error['message']
    ) );
    return; // Render fallback content instead.
}

Output in the PHP error log when the API server is unreachable:

HuxxConnect error 503: Connection refused. The API server may be down or unreachable.

huxx_api_is_error() recognizes both forms a failure can take — the ErrorResponse object and its array conversion — so one check covers every case. huxx_api_get_error() returns the details as an array with the keys _huxx_connect_error, code, message, original_response, and context, or null when the response is not an error.

Pass runtime arguments

The third parameter customizes a single call without touching the saved configuration. All entries are optional. This example uses a product_detail endpoint (GET /products/{0}) added to the demo API:

<?php
$product = huxx_api( 'demo_api', 'product_detail', array(
    'endpoint_variables' => array( 1 ),                       // Fills {0} in the path /products/{0}.
    'query_variables'    => array( 'select' => 'id,title,price' ),
    'header_variables'   => array( 'X-Request-Source' => 'theme' ),
    'keys'               => '{title},{price}',
) );

print_r( $product );

Output:

Array
(
    [title] => Essence Mascara Lash Princess
    [price] => 9.99
)
  • endpoint_variables — fills path variables; an indexed array maps by position, an associative array by name.
  • query_variables, header_variables, body_variables — merge over the saved parameters; runtime values win. Body values for multipart endpoints may be structured arrays with value, filename, type, and is_file.
  • keys — extraction path(s), string or array; see Extract Values with the keys Syntax.
  • debug — when true, a failure of the HTTP request itself returns the error as an array instead of an ErrorResponse object; configuration-lookup failures (unknown API or endpoint id) still return ErrorResponse. huxx_api_is_error() handles both forms.

Note that unlike the shortcode’s comma-separated attribute strings, PHP arrays carry values with commas (like select above) without any escaping concerns.

Override caching per call

Responses to GET requests are cached for the endpoint’s configured cache duration. The cache argument overrides it for one call:

<?php
// Force a fresh request — skip the cache entirely.
$fresh = huxx_api( 'demo_api', 'get_products', array( 'cache' => false ) );

// Cache this call's response for 10 minutes regardless of the endpoint setting.
$cached = huxx_api( 'demo_api', 'get_products', array( 'cache' => 600 ) );

echo esc_html( $fresh['total'] . ' / ' . $cached['total'] );

Output:

194 / 194

Both calls return the same decoded array — the difference is whether a stored copy may be served and how long the fresh response is kept. false or 0 disables caching for the call; a positive integer is the TTL in seconds. Only GET requests are ever cached.

If it didn’t work

  • huxx_api() returned false. One of the first two arguments was empty. The function does not look anything up in that case — check that both ids are non-empty strings.
  • huxx_api_is_error() is true and the message says the API or endpoint was “not found”. The id doesn’t match the configuration. Copy the exact ids from the API detail screen — they are slugs, not display names.
  • The call works but you see stale data. A cached response is being served. Pass 'cache' => false to confirm, then adjust the endpoint’s cache duration — see Cache Endpoint Responses. Cache-served calls do not appear in the request log — only real HTTP requests are logged, so the absence of a new log entry confirms a cache hit. See Debug API Requests.