Reference - Data types - curl

<ul>
  {rates}<li>{$code}: {$rate}</li>{/rates}
</ul>

{meta title='Remote data with a cache'}

<p>Data can come from another server: a URL as the data of a tag, a <code>.curl</code> file
in <code>_data/</code>, or the {tag 'curl'} tag for the raw answer. Each of them takes a
<code>ttl</code> - the seconds to keep the answer - and within that time the page is served
from the copy instead of asking the source again. A dashboard on an external API then costs
one call per ttl, not one per visitor.</p>

<p>A <code>.curl</code> file names the URL and the ttl. Here <code>_data/rates.curl</code>
reads the rates from a page of this manual standing in for an API:</p>

{ignore}
<code><curl>
  <url>SELF://manual/?fragments/rates&amp;amp;padInclude</url>
  <ttl>600</ttl>
</curl></code>
{/ignore}

<p>Its name is a tag, like any data file:</p>

{example 'fragments/remote_1'}

<p>The same with the URL in the template - the ttl is an option of the tag the data is
for, <code>{pad data='https://...', ttl=600}</code> - or the answer as it came,
with {tag 'curl'}:</p>

{example 'fragments/remote_2'}

<p>When the source fails after the ttl - it is down, or answers with an error - the last good
copy is served and the failure is written to the error log, where an
<a href="?pages/events">event hook</a> on <code>curl</code> hears it too. Only a good answer
is kept, and a copy stays a day beyond its ttl for that purpose
(<code>$padCurlStale</code>). <code>$padCurlCache</code> chooses where the copies live:
<code>'file'</code>, <code>'apcu'</code>, <code>'redis'</code>, <code>'memcached'</code>,
or <code>FALSE</code> to fetch every time.</p>

<?php

  // A request value that merely equals the port - ?amount=9 - chooses nothing: the page's
  // own address on port 9 is fetched (and fails, nothing listens there), where every
  // address on the port of a request's number was refused - ?amount=8000 on pad serve.

  $_GET ['amount'] = '9';

  $u = 'http://127.0.0.1:9/probe';

?>

[{pad data=$u}{$a}{/pad}]

<?php

  // The fetches of this request answered from fakes: padCurl, padCurlCached (which passes
  // its cache by while faking), padPrefetch, and in the template {curl} and data=. The
  // URLs fetched are read back after the template made its own.

  padCurlFake ( [
    'https://api.example.com/rates'  => [ 'data' => [ 'eur' => 1.08 ] ],
    'https://api.example.com/list*'  => [ 'status'  => 200, 'data' => "name,price\nTea,2\nCake,3",
                                          'headers' => [ 'Content-Type' => 'text/csv', 'X-Fake' => 'yes' ] ],
    'api.example.com/down'           => 503,
    'https://api.example.com/echo'   => fn ( $request ) => $request ['method'] . ' ' . $request ['post']
  ] );

  $rates  = padCurl ( 'https://api.example.com/rates' );
  $cached = padCurlCached ( 'https://api.example.com/rates', 600 );
  $down   = padCurl ( 'https://api.example.com/down' );
  $echo   = padCurl ( [ 'url' => 'https://api.example.com/echo', 'post' => 'a=1' ] );

  padPrefetch ( [ 'menu' => 'https://api.example.com/list?for=menu' ] );

  $summary = json_encode ( [
    'rates'  => [ $rates ['result'], $rates ['type'], $rates ['data'] ],
    'cached' => [ $cached ['result'], $cached ['cache'] ],
    'down'   => [ $down ['result'], $down ['data'] ],
    'echo'   => $echo ['data'],
  ], JSON_UNESCAPED_SLASHES );

  function httpFakeCalls () {
    return implode ( ' | ', array_map ( fn ( $call ) => $call ['method'] . ' ' . $call ['url'], padCurlRecorded () ) );
  }

?>

{!summary}
{menu}{$name}={$price} {/menu}
{curl 'https://api.example.com/list.csv'}
{pad data='https://api.example.com/list?for=data'}{$name} {/pad}
{php:httpFakeCalls}

<?php

  // An address the page's own PHP holds is the author's - from its configuration, an
  // environment value, the engine's $padHost - and is fetched; only one a visitor chose is
  // refused. {data 'd', $u} and data='{$padHost}...' were refused as values.

  $u = 'SELF://regression/remote/?stamp';

?>

[{pad data=$u}{$source}{/pad}][{data 'd', $u}{d}{$source}{/d}][{pad data='{$padHost}regression/remote/?stamp'}{$source}{/pad}]

{define 'feed'}[{pad data='{#src}'}{$source}{/pad}][{data 'd', '{#src}'}{d}{$source}{/d}]{/define}{feed src='SELF://regression/remote/?stamp'}

<?php

  // An address the page's PHP built is fetched though request values merely hold its host
  // as text - a search for "regression-dark", a cookie "my regression": only a value that
  // is the host, its port or the start of the address chose it. Before, any value holding
  // the host refused the page, a short host even by the random padReqID cookie.

  $_GET ['q']         = 'regression-dark';
  $_COOKIE ['theme'] = 'my regression';

  $u = 'SELF://regression/remote/?stamp';

?>

[{pad data=$u}{$source}{/pad}][{data 'd', $u}{d}{$source}{/d}]

<?php

  // An address written in the template is fetched whatever the page printed before it: a
  // value printed earlier that its address starts with - a site's address in a footer, a
  // homepage field - made data='...' and {data 'd'}...{/data} refuse it as a value.

  $site = 'SELF://regression';

?>

[{$site}][{pad data='SELF://regression/remote/?stamp&padInclude&as=self'}{$source}{/pad}][{data 'd'}SELF://regression/remote/?stamp&padInclude&as=self{/data}{d}{$source}{/d}]

{set $live = 1}{data}{if $live}SELF://regression/remote/?stamp&padInclude&as=self{else}SELF://regression/remote/?slow&padInclude{/if}{/data 'd'}[{d}{$source}{/d}]

[{pad data='SELF://regression/remote/?disposition&padInclude'}{$source}{/pad}]

{pad data='SELF://regression/remote/?stamp&padInclude&as=self'}{$source}{/pad}

<?php

  // The same document as a data= url, fetched twice with the ttl the tag gives.

  $stampUrl = $padHost . 'regression/remote/?stamp&padInclude&as=data';

?>

{stampKept}{$stamp}{/stampKept} {stampKept}{$stamp}{/stampKept} {pad data=$stampUrl, ttl=60}{$stamp}{/pad} {pad data=$stampUrl, ttl=60}{$stamp}{/pad}