Some values differ per machine and must not stand in the code: the database password, an API key, a debug switch. padEnv reads them from the server's environment or from a .env file beside the code, so the same application runs unchanged on a laptop and on the production server, and the secrets never reach git. The cache keeps what is slow to make from one request to the next, and a rate limit counts how often a visitor tries.

Environment values

padEnv ( 'KEY', $default ) looks in three places and answers the first that has the key: the real environment of the server (getenv, $_ENV, $_SERVER - what Apache's SetEnv or PHP-FPM's env[...] sets), then the .env in the application's root - apps/shop/.env - then _common's .env for an application that runs with _common, then .env in the PAD home. Without the key it answers the default - a closure as the default is called. This manual has a .env of its own:

MANUAL_SITE_NAME="PAD manual"
MANUAL_PAGE_SIZE=20
MANUAL_DEBUG=false

<?php

  // apps/manual/.env holds MANUAL_SITE_NAME,
  // MANUAL_PAGE_SIZE and MANUAL_DEBUG.

  $site  = padEnv ( 'MANUAL_SITE_NAME', 'My site' );
  $rows  = padEnv ( 'MANUAL_PAGE_SIZE', 25 );
  $debug = padEnv ( 'MANUAL_DEBUG', TRUE ) ? 'on' : 'off';
  $maps  = padEnv ( 'MANUAL_MAPS_KEY', 'not set' );

?>

<ul>
  <li>Site: {$site}</li>
  <li>Rows a page: {$rows}</li>
  <li>Debugging: {$debug}</li>
  <li>Maps key: {$maps}</li>
</ul>

The engine loads its library before it reads any configuration, so the place a secret is needed first can ask for it - _config/config.php:

$padSqlPassword = padEnv ( 'padSqlPassword' );
$padSqlUser     = padEnv ( 'padSqlUser', 'shop' );

The .env file

# a comment
APP_NAME=Shop                     a bare value, trimmed - # after a space starts a comment
export DB_HOST=localhost          export in front, as a shell script writes it
GREETING="Hello\nWorld"           double quotes: \n \r \t \" \\ \$ and ${OTHER}
PATTERN='${not} \n expanded'      single quotes: the text exactly as written
DEBUG=false                       true, false, null and empty are TRUE, FALSE, NULL and ''
NOTE="two
lines"                            a quoted value may run over several lines

• A quoted value is always text: "false" is the word, not FALSE.
• ${OTHER} is OTHER from the real environment, else as set earlier in the same file, else empty; it works in bare values too.
• A key written twice: the later line wins, as in a shell.
• A line that is none of these is an error naming the file and the line number - never the line itself, which may hold the secret.
• A key that starts with HTTP_ is never read from the real environment: those are the headers of the request, which the client sends.
• No URL reaches apps/ - the web server serves www/ only - so an application's .env is not served. The repository's .gitignore keeps the .env of the PAD home out of git; keep an application's out the same way when it holds a real secret.
• Each file is read once per request, the first time a key is asked for.

The cache

A slow query, a remote service, a computed report: padRemember ( $key, $ttl, $callback ) answers what is kept under the key, or runs the callback, keeps its answer for $ttl seconds and answers that. padCachePut, padCacheGet, padCacheHas and padCacheForget do the same by hand.

<?php

  // The first request of the next ten minutes runs the callback;
  // the others get what it left in the cache, without asking the
  // source again.

  $rates = padRemember ( 'manual-rates', 600, function () {
    return [ [ 'code' => 'EUR', 'rate' => '1.00' ],
             [ 'code' => 'USD', 'rate' => '1.08' ],
             [ 'code' => 'GBP', 'rate' => '0.86' ] ];
  } );

  padCachePut ( 'manual-notice',
                'Maintenance on Sunday night',
                3600 );

  $notice  = padCacheGet ( 'manual-notice', 'No notice' );
  $nothing = padCacheGet ( 'manual-nothing-kept',
                           'Nothing kept under this key' );

?>

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

• The ttl is a number of seconds - 3600 when padCachePut is not told - or NULL for ever, a DateTimeInterface (until then) or a DateInterval. A ttl of 0 or less keeps nothing.
• The cache keeps arrays and scalars - strings, numbers, TRUE, FALSE, NULL - nested as deep as they go. A value that holds an object is an error: it would not come back as it went in.
• A kept NULL counts: a callback that found nothing is not asked again until the entry expires. A closure as the default of padCacheGet is called.
• Each application has its own entries, files under DATA/cache/app/<application>/, one per key; padCacheFlush () removes them all. A file is written beside its place and then renamed over it, so a request reads the old value or the new one, never half of one.
• When what a key holds changes - a product saved, a price updated - the page that changes it calls padCacheForget, and the next request makes it again.

Rate limits

padRateLimit ( $key, $maxAttempts, $decaySeconds ) counts a hit and answers TRUE while the key stays within the limit - five attempts a minute - and FALSE over it. The first hit starts a window of $decaySeconds; when it ends, the key starts from nothing again. A login form, a contact form, an expensive search: key it on the visitor, or on the account that is tried.

<?php

  // Five login attempts a minute. A page of your own keys it on
  // the visitor - 'login:' . $_SERVER ['REMOTE_ADDR'] - this
  // example on a key of its own, so every reader of this page
  // starts from nothing.

  $key   = 'login:' . padRandomString ( 8 );
  $tries = [];

  for ( $try = 1; $try <= 7; $try++ ) {
    $allowed  = padRateLimit ( $key, 5, 60 );
    $tries [] = [ 'try'    => $try,
                  'answer' => $allowed ? 'allowed' : 'too many' ];
  }

  $left    = padRateLimitRemaining ( $key, 5 );
  $minutes = ceil ( padRateLimitAvailableIn ( $key ) / 60 );

  padRateLimitClear ( $key );

?>

<ul>
  {tries}<li>Attempt {$try}: {$answer}</li>{/tries}
</ul>
<p>{$left} attempts left - try again in {$minutes} minute.</p>

• padRateLimitRemaining ( $key, $maxAttempts ) - the hits left in the window; padRateLimitAvailableIn ( $key ) - the seconds until it ends, 0 when no window runs; padRateLimitClear ( $key ) - after a login that succeeded.
• A hit over the limit is not counted; the window ends when it would have anyway.
• Requests that come at once are each counted: they take turns on a lock while they count.
• Rate limits are kept with the cache - padCacheFlush () clears them too - and a rate limit and a cache key of the same name are two entries.