{curl} · PAD tags

Syntax

{curl 'https://example.com/data.json'}
{curl url='https://example.com/data.json', ttl=600}
{curl 'https://example.com/api', post='a=1&b=2', user='name', password=$secret}
{curl 'SELF://shop/?orders', $status='open'}
{curl 'https://example.com/api', get=$query, cookies=$jar, headers=$headers, options=$curlOptions}

Parameters

url: The address - also written url=. SELF:// at its start is this site's own host and mount prefix.

Options

ttl: Keep the answer this many seconds; when the source fails afterwards the last good copy is served and the failure logged.
post: The body to post - the request is then a POST.
user: The user name of basic authentication.
password: The password of basic authentication.
get: An array of query values added to the URL.
cookies: An array of cookies to send.
headers: An array of request headers.
options: An array of curl options by name.

Description

{curl 'https://...'} fetches a URL and answers the body of the response as the tag's value - a value, so braces in it stay text. url= or the first parameter gives the address; SELF:// at its start becomes this site's own host and mount prefix, so an application can call itself wherever it is served. A $name=value written on the tag is added to the URL as a query value.

The tag's parameters as a whole are the input of padCurl(): post= makes the request a POST with that body, user= and password= are basic authentication, and get=, cookies=, headers= and options= (curl options by name) are arrays. Any answer but HTTP 200 is a PAD error, and nothing of the failing answer goes into the page.

A cache

With ttl=600 the answer is kept ten minutes: the requests in that time are answered from the copy. When the source fails after the ttl the last good copy is served and the failure goes to the error log (and to the application's _events/curl.php); only a good answer is kept. $padCurlCache picks the store - 'file' (the default), 'apcu', 'redis', 'memcached' or FALSE. data='https://...' on a tag takes the same ttl= and reads the answer as data, and padPrefetch in the page's PHP fetches several sources in parallel.

In tests padCurlFake answers every fetch from fakes. A remote fetch is neither deterministic nor allowed here, so the examples are shown, not run.

Examples

Fetch a URL

The body of the answer is the tag's value; anything but HTTP 200 is a PAD error.

Templateexamples/curl/1-fetch.src

<pre>{curl 'https://api.example.com/status.txt'}</pre>

Kept for ten minutes

ttl=600 answers from a copy for ten minutes, and serves the last good copy when the source fails afterwards.

Templateexamples/curl/2-ttl.src

{pad data='https://api.example.com/rates.json', ttl=600}
  <p>{$code}: {$rate}</p>
{/pad}
{curl 'https://api.example.com/rates.json', ttl=600 | ignore}

A post with credentials

post= makes it a POST; user= and password= are basic authentication; a $name=value set on the tag goes into the query string.

Templateexamples/curl/3-post.src

{curl 'https://api.example.com/orders', post='number=1042&status=paid', user='shop', password=$apiKey | ignore}
{curl 'SELF://shop/?orders', $status='open' | ignore}