Php Sdk Laravel Package

Product Decisions This Supports

• Build vs. buy for "did the job actually run?" observability. The expensive failure mode in a PHP estate is almost never a loud exception — it's the nightly invoice batch, dunning run, or payout job that silently never fired and surfaces as a support ticket the next morning. Building that in-house means a dashboard, alert routing, escalation policy, history retention, and on-call ergonomics. This package collapses the buy side to composer require plus a monitor UUID per job, so the real decision becomes "which jobs are worth a per-monitor fee" instead of "who loses two sprints to build a heartbeat service." That reframing is the product value: it turns an engineering capacity question into a small, priced line item.

• Producing a canonical inventory of scheduled work as a roadmap artifact. Adoption forces the question every team defers: what actually runs on a schedule? php artisan schedule:list, bin/console debug:scheduler, crontab, and systemd timers each enumerate entries that must be either mapped to a monitor UUID or deliberately excluded. That mapping table is valuable independently of the vendor — it surfaces orphaned crons, duplicated jobs, tasks nobody owns, and jobs whose only documentation is a person's memory. Treat the inventory, not the alerts, as the first deliverable.

• Tiering scheduled work by business impact, which sets both alert policy and uptime claims. Not every job warrants a page at 3am. Using the mapping exercise to rank jobs by revenue exposure (billing, renewals, payouts, customer-facing notifications, nightly ETL) yields a defensible tiering that feeds on-call rotation design and any customer-facing SLA language. This is a product decision the package merely makes cheap to execute.

• Consolidating on one vendor across a mixed PHP estate. Laravel (auto-discovered provider, ->monitor(uuid) on the schedule, queue-job middleware), Symfony (bundle, console event subscriber, Messenger middleware), and plain PHP (CronMonitorClient::create() or a vendor/bin/cron-monitor start|success|fail shell wrapper) all ship in a single MIT SDK. For a shop running a Laravel app alongside a legacy Symfony console app and a few raw cron scripts, that's one integration and one alerting surface instead of three — a genuine reduction in operational surface area.

• Designing the trial-to-activation path in our own product. vendor/bin/cron-monitor signup <email> --accept-terms creates the account and writes the first token into the git-ignored env file, with no key pasted onto a command line or into shell history. That is a strong template for our own onboarding: remove the "go to a dashboard, create an API key, copy it back" step that is where most self-serve evaluations die. Worth studying even if we never adopt the service.

• Security and compliance sign-off as a design constraint. Credentials are env-only by contract; the client never throws and never retries beyond one attempt with a 5-second timeout, so a monitoring outage can never fail a business job. "Observability must not become an availability risk" is the sentence that gets SRE and security to approve in days rather than quarters — and it is a posture worth writing into our own internal library standards.

• Deployment topology and environment strategy. The endpoint key supports staging and self-hosted targets, with allow_insecure_endpoint off in production. That lets us decide per environment whether production heartbeats go to a hosted SaaS or an internal instance — a decision that should be made deliberately at adoption, not discovered later.

When to Consider This Package

Adopt when:

• The stack is PHP 8.2+ with ext-curl (or a bindable PSR-18 client), running Laravel 10/11, Symfony, or plain cron/systemd-invoked scripts.
• The dominant risk is silent non-execution, not latency, throughput, or per-step performance. Heartbeat monitoring answers exactly three questions — did it start, did it finish, did it fail — and nothing more. If that's the gap, this closes it.
• The team has no APM/tracing budget and no appetite to stand up and operate Healthchecks or Cronitor infrastructure itself.
• You want a pilot with near-zero commitment: free-tier access, MIT client, and a codebase thin enough that removal is an afternoon's work.
• The estate is PHP-only, or non-PHP services are already covered by something else.
• Someone can own the operational discipline — configuring dead-man's-switch alerts on the service side and keeping monitor names in sync with job names — not just the code merge.

Look elsewhere when:

• You need distributed tracing, metrics, log aggregation, or per-step timing. This complements Sentry or Horizon; it does not replace them, and running both means two alerting surfaces and duplicated noise.
• An incumbent already covers cron monitoring (Sentry Crons, Cronitor, Healthchecks.io). Two heartbeat tools is strictly worse than one — pick a winner and standardize.
• Procurement or legal won't accept a commercial dependency on a very small vendor. Note the distinction precisely: the SDK is MIT and forkable, but the service is the dependency, and self-hosting the endpoint reintroduces the build cost we were avoiding.
• The estate is polyglot and would need per-language SDKs of uneven maturity. That's a platform-level decision, not a per-repo one.
• Jobs are sub-minute or extremely high-frequency, where ping volume and per-monitor pricing dominate the value delivered.
• The team cannot guarantee the rename discipline: monitors reconcile by name, so a renamed job silently creates a second monitor while the original goes stale and starts alerting. If that reconciliation won't live in the code-review checklist, this tool generates false alarms faster than real ones.
• Nobody will test the alerting path. Fail-open is the right engineering posture, but it means a broken network path or a mistyped UUID produces silence rather than an error — and "monitoring is installed" quietly becomes a false assurance.

How to Pitch It (Stakeholders)

For executives. This is cheap insurance against the failure class that reaches us as a customer complaint instead of an alert — the report that never generated, the renewal that never billed, the payout that never ran. Integration is hours, not a sprint. We operate no additional infrastructure. The client is deliberately incapable of breaking a job: it never throws, never retries beyond once, and hard-stops at five seconds, so a monitoring outage cannot become an availability incident. The commercial exposure is a small vendor, but the client code is MIT and thin enough to replace with a direct HTTP call if we ever want out — and the monitor definitions live in our config, so they're portable. Recommendation: map our scheduled jobs, start on the free tier against three revenue-critical jobs, measure alert quality and signal-to-noise for one quarter, and only then decide on broader coverage and a paid tier. The inventory we produce along the way is useful regardless of the outcome.

For engineering. One composer require. Laravel auto-discovers the service provider and gives you ->monitor(uuid) on the schedule plus a queue-job middleware; Symfony gives you a bundle with a PHP attribute or a YAML command map and a Messenger middleware; plain PHP gets CronMonitorClient::create() or a shell wrapper around the artisan-style CLI. Pings fire from schedule:run and the consumer, not from manual runs, so local work doesn't pollute history. Failure bodies carry exit codes or the exception class, message, and file:line, which shortens triage. Credentials live only in env or the secret store — never in committed files, command lines, or CI logs — and the signup CLI writes the token into the git-ignored env file for you. Three constraints to encode in the runbook from day one: PHP 8.2 is a hard floor; the monitors map must be read through config() and never env() at the call site, or it breaks under config:cache; and in Laravel, omit the CRON_MONITOR_API_KEY line entirely rather than leaving it empty, because an empty value is transmitted as an empty bearer token. Land one non-critical job first behind a UUID env var so the monitor is a no-op where unset, verify in staging that success, failure, and absence of a run all behave correctly on the service side, confirm the on-call channel actually receives both a forced failure and a skipped run, then expand one tier per PR with the monitor-name convention fixed in advance.