Download the PHP package 1monitor/sdk-php without Composer

1Monitor SDK for PHP

Official PHP SDK for 1Monitor — ping your cron jobs, queue workers and scheduled tasks so you find out when they stop running.

Sending a ping never throws and never blocks for long. Monitoring must not be the thing that takes your job down. See The no-throw guarantee.

Requirements

PHP 8.1 or newer.

Install

Quickstart

Create a monitor in 1Monitor, copy its ping token, and call the SDK from the job you want watched.

That single call is enough for a heartbeat monitor: 1Monitor alerts you when the pings stop arriving.

Measuring how long a run takes

If you also want to know that a job finished, and how long it took, wrap the work in a start/finish pair. 1Monitor pairs them into a run, records its duration, and can alert on runs that fail or overrun.

Put the pingFail before the rethrow, not in a finally, so a crash still closes the run — and so the exception keeps propagating exactly as it would without the SDK.

Saying why it failed

ping, pingSuccess and pingFail optionally carry the job's exit code and output, so the alert can tell you what went wrong instead of just that something did:

The exit code travels as ?exit_code=N; a non-zero value marks the ping as failed even on a bare ping(). The output travels as the request body and is capped at 10 KB (Client::MAX_OUTPUT_BYTES) — the SDK truncates longer output before sending, because that is all the server would keep anyway.

1Monitor sweeps common credential shapes (tokens, API keys, private keys) out of ping output before storing it, but that is a safety net, not permission: send your job's diagnostic output, not its environment or its config.

Tagging pings with the deployed version

Every ping can carry the version of the code that sent it — a release number or the deployed commit SHA — so 1Monitor can tell which deploy a run belongs to. Pass it per call:

or once, on the client, so every ping carries it without touching the call sites:

A version passed to a call overrides the client's. It travels as ?version=…, after the exit code if there is one.

The version is trimmed and must then be 1–64 printable ASCII characters without whitespace — a SemVer string or a full 40-character SHA both fit. Anything else is dropped rather than thrown, the same way the server would drop it: the ping goes out without it (or with the client's version, when a call's own is the one dropped), and the SDK logs the dropped value at debug level. An empty or blank version means none and is not logged.

From a cron job

The same pattern as a standalone script, wired into your crontab:

Keep the token in the environment rather than in the source — it is a credential: anyone holding it can ping your monitor.

The four calls

Each returns bool: true when 1Monitor accepted the ping, false when it did not.

exitCode, output and version are optional and named. A ping with output is sent as a POST with the output as the body; without one it stays a GET. pingStart carries no exit code or output — the job has not produced a result yet — but does carry a version. Exit codes outside 0–255 are ignored by the server.

Options

Every constructor option is optional and named:

Maximum time a ping can hold up your job: timeout + backoff sleeps — about 6.5 s with the defaults (5 s of network time, plus 0.5 s and 1 s between the three attempts).

Why timeout is a budget, not a per-attempt limit

timeout is an overall deadline for time spent on the wire. Attempts draw it down as they run, and no retry starts once the budget is gone.

That is deliberate. If timeout only limited single attempts, three attempts against a hanging endpoint would block for 3 × 5 s plus backoff — around 16.5 s of your job's runtime spent on monitoring. The shared budget keeps the worst case flat no matter how many retries you allow.

Guzzle clients vs. other PSR-18 clients

The SDK drives a Guzzle client — the default, or any injected one — through Guzzle's own request API rather than its PSR-18 adapter, because the adapter supports neither per-request timeouts nor redirects. With Guzzle you therefore get the full guarantees: each attempt's socket timeout is the remaining budget (so the 6.5 s worst case above holds), and redirects are followed.

Guzzle receives these as per-request options, so they take precedence over whatever the injected client was configured with. A Guzzle client follows at most 5 redirects per attempt and, when baseUrl is https, refuses a redirect to http so the token is never sent in clear text.

With a non-Guzzle PSR-18 client, two things are yours to handle:

• Socket timeouts — PSR-18 has no per-request options, so configure them on the client. The SDK still refuses to start a retry once the budget is spent, but it cannot cut short an attempt already in flight; a hanging endpoint can then hold the job for one full attempt beyond the budget.
• Redirects — followed only if your client follows them. A 3xx reaching the SDK counts as a failed ping and is not retried, so point baseUrl directly at the ping endpoint over https.

What gets retried

Only connection failures and 5xx responses. A 4xx is a decision, not a hiccup — a wrong token stays wrong, and a 429 means you are already sending too much — so those fail immediately. Backoff is roughly 0.5 s, then 1 s.

Ping constraints

If a monitor requires a specific HTTP method or header, inject an HTTP client configured with them — any PSR-18 client works, Guzzle shown here:

First-class options for this may be added later.

The no-throw guarantee

The SDK exists to tell you when a job stopped working. It must never be the reason a job stops working.

So delivering a ping never throws. A DNS failure, a dead network, a TLS error, an unreachable 1Monitor, a 404 from a deleted monitor, a 429, a 500 — all of them return false. Nothing propagates into your job.

Failures are reported to the PSR-3 logger you pass in, at error level. The context carries:

The ping token is a credential and is deliberately kept out of the log: the exception object itself is not passed on, because HTTP clients embed the request URL in it, and the token is redacted from the message. Without a logger, failures are dropped silently.

The only exceptions the SDK throws are your own mistakes, caught early and loudly:

Both implement OneMonitor\Sdk\Exception\Exception, so catch (OneMonitor\Sdk\Exception\Exception $e) catches everything this package throws.

Testing code that pings

Client is final. Type-hint against OneMonitor\Sdk\ClientInterface instead and substitute a test double in your own tests:

The interface declares the same four methods as Client.

Security

• The ping token is a credential. Keep it in the environment or a secret store, never in source. It never reaches the SDK's log output.
• Use https. The default base URL is https, TLS certificates are verified, and a Guzzle client will not follow a redirect that downgrades to http. An http base URL is accepted for local or self-hosted setups; the token then travels in clear text.
• Output is sent as is. Send diagnostic output, not the job's environment or configuration. 1Monitor sweeps common credential shapes out of stored output, but treat that as a safety net.
• Reporting. Vulnerabilities go through the private process in SECURITY.md, not the public issue tracker.

Versioning

This package is at 0.x, and Composer treats 0.x minors as breaking. Require it as:

The version is deliberately below 1.0.0: the SDK's stability promise cannot exceed that of the ping API it wraps, which is not yet formally versioned. 1.0.0 follows once it is.

Changes are recorded in CHANGELOG.md.

Scope

Ping only. Management operations — creating, listing or pausing monitors, reading alerts — are not covered; there is no public management API yet. They will be added to this same package when there is, which is why it is named sdk-php and not ping-client.

Contributing

Bug reports and feature requests are welcome in GitHub Issues. Security issues follow a separate process — see SECURITY.md.

See CONTRIBUTING.md for the development setup, the checks CI runs, and the design constraints a change must respect.

License

MIT — see LICENSE.