Release 3.0.52

Implemented enhancements

• Let the host name the surface it is serving (#93) — the beacon can now be told the application area and the action a process dispatched, through setSurface($area, $action).

  Until this, the only thing separating a cron from a shopper's page render was PHP_SAPI, and that answers a different question. Magento's own cron entry point refuses to run under the CLI SAPI, so an installation running cron over HTTP is a web-SAPI process doing a full sync — indistinguishable, on the reporting side, from a page render.

  Instance state, beside the user agent rather than on a bucket: a bucket exists only once an API key has been seen, and the dispatch happens whether or not one ever is. First non-empty wins, per token and independently, so a valid area survives an action that does not pass.

  The action can be attacker-controlled, so the rule that bounds it is the substance of the change rather than a detail of it. A value is rejected whole, never repaired — stripping the bytes that failed yields something nobody sent, and possibly a route that exists. Length is measured on the raw bytes and before the charset test. The charset is ASCII-only, which also keeps one malformed byte from costing the entire report: json_encode() returns false on malformed UTF-8 and a body that is not a string is dropped. The pattern ends at \z rather than $, because PHP's $ also matches immediately before a final newline. And a token must carry at least one character that is not a separator, so an unrouted request — which composes the bare delimiters — names nothing and is refused.

• Keep construction detail out of what the package ships (#94) — comment only, no behaviour. Docblocks that explained a rule by describing how the far end is built now explain it on this library's own terms, which is where every one of those rules actually stands.

Note for extension authors

setSurface() does nothing until a host calls it. An extension that never does produces the envelope it produced before, key for key. Guard the call with method_exists(): an app/code installation pairs whichever library is on disk with whichever extension is on disk, so a composer constraint decides nothing there.