LiveReferralFigures
\Benecaster\License\LiveReferralFigures
The live referral figures from the license server, for the Refer a Friend page and benecaster_get_live_referral_balance(). Add-on code should call that function rather than this class. The class is otherwise internal: its other callers are the plugin’s own referral REST endpoint and the license validation run.
Why it exists: a referral balance is never shown stale. The balance the daily validation run stores can be a day old, stays stale for as long as the license server is unreachable, and reads 0 when a server lookup fails, which cannot be told apart from “no credit”. This class does not fail open. When fetch() returns null, show no balance at all and link to the podcaster’s account page instead. Never fall back to the cached figure.
A successful answer is reused for five minutes (REUSE_SECONDS), so reloading the page stays under the license server’s rate limit. The figure can therefore be up to five minutes old. Failures are not cached: the next call asks again. The reused answer belongs to this site only.
It calls the license server only from wp-admin, cron, or an admin REST request by a user who can manage options, and never on a front-end request. Elsewhere it serves a reused answer or null.
A fresh answer also refreshes the saved copies of the link, code, balance, sign-up count and email preference that the benecaster_get_referral_* functions and
read, each only when the answer carries it with the right type.
The balance is per customer, so any connected show’s token gives the same figure.
Constructor Dependencies
| Type | Description |
|---|---|
\Benecaster\License\LicenseClient |
Makes the license server call. Defaulted. |
\Benecaster\License\ShowTokenRepository |
Finds a connected show's token to authenticate with. Defaulted. |
Methods
| Method | Visibility | Since | Description |
|---|---|---|---|
fetch(): ?array |
Public | — | The live figures as credit_balance_cents (int), referral_conversion_count (?int), referral_link (?string), referral_code (?string), notify_referral_updates (?bool) and fetched_at (unix time), or null when there is no answer to give: no connected show, any refusal or transport failure, a malformed body, or a front-end request with nothing reusable. null means show no balance. A balance that is not a non-negative integer is refused rather than coerced. |
forget(): void |
— | — | Static. Deletes the reused answer. The license validation run calls it when the license is declared invalid, so a lapsed license does not keep showing a balance. It does not touch the saved copies of the figures. |
Constants
| Name | Value | Description |
|---|---|---|
REUSE_SECONDS |
300 |
Seconds a successful answer is reused (five minutes). |
TRANSIENT |
'benecaster_live_referral_figures' |
The transient that holds the reused answer. |
Notes
The call-out check is is_admin(), wp_doing_cron(), or a REST request from a user who can manage options. is_admin() is also true for requests to admin-ajax.php, including ones made from a front-end page, so an AJAX handler can trigger the license server call.
The five-minute reuse and the saved-copy refresh apply only to a successful answer. A refusal, a transport failure or a malformed body returns null and changes neither the reused answer nor the saved copies.