Cwh Laravel Package

Product Decisions This Supports

• Build vs. buy for log shipping. Adopting phpnexus/cwh replaces a bespoke Monolog handler (typically 200–400 LOC of batching, retry, credential refresh, sequence-token ordering, and 256 KB event truncation logic) with a maintained MIT dependency. This is a "buy" decision with essentially zero licence cost and low switching cost — the handler is instantiated in config/logging.php, so backing it out is a config change plus a deploy.
• Centralized observability on AWS without a new vendor. It lets Laravel's existing Monolog stack write directly to CloudWatch Logs via a monolog channel, so we get cross-service log search and Logs Insights querying without procuring Datadog/Papertrail or standing up an ELK cluster. This directly supports roadmap items around incident response and on-call runbooks.
• Feature work: multi-tenant / per-environment log streams. The handler's log group and stream naming can be driven from config, which lets us map stream names to environment, service, or tenant — useful for support workflows where we need to pull one customer's request trail without a data warehouse.
• IAM-first security posture. It authenticates through the AWS SDK credential chain (instance profile / ECS task role), so we can ship CloudWatch logging without introducing long-lived access keys into .env or CI secrets — a compliance and audit talking point.
• Migration off deprecated forks. phpnexus/cwh is the maintained lineage of maxbanton/cwh, which stalled on Monolog 3 / modern PHP. This is a low-drama dependency upgrade that unblocks framework upgrades (Laravel 10/11 ship Monolog 3), and is best framed as "keeping the lights on" hygiene rather than a new capability.

When to Consider This Package

Adopt when:

• The workload genuinely runs on AWS (EC2, ECS/Fargate, Lambda, Elastic Beanstalk) and CloudWatch is already the org's log sink of record.
• We're on a modern Laravel (10/11+) with Monolog 3, and the original maxbanton/cwh is not an option.
• We want a code-level handler rather than infrastructure-level shipping — i.e. we can't or won't mandate the CloudWatch agent, FireLens, or Fluent Bit sidecars.
• Log volume is modest-to-moderate (roughly single-digit GB/month) and latency tolerance is generous, so synchronous/batched PutLogEvents calls are acceptable.
• The team is comfortable pinning a small, low-star dependency and owning a fork if the maintainer goes quiet.

Look elsewhere when:

• Containers are the deployment target. For ECS/EKS, stdout + FireLens/aws-for-fluent-bit is the better architecture: no app-side coupling, no credential handling, no blocking on log I/O, and it survives app crashes. This package becomes redundant.
• Log volume is high. CloudWatch ingestion is ~$0.50/GB plus storage and Logs Insights scan costs; at scale, a sampled/aggregated approach or a cheaper sink (S3 + Athena, Better Stack) wins. Also watch for the classic feedback loop where CloudWatch errors get logged back to CloudWatch.
• Request-path latency is tight. A synchronous handler on the hot path is a tail-latency risk; if we can't tolerate it and can't batch/queue it, prefer an async sidecar.
• You need more than logs. No metrics, no traces, no alerting, no UI. If the real requirement is product analytics or APM, this is the wrong lever — reach for OpenTelemetry or a full observability vendor.
• Governance is strict. 39 stars and a single-maintainer fork lineage is a supply-chain review flag; if the org requires a supported vendor or an SLA, use the CloudWatch agent (AWS-supported) instead.

How to Pitch It (Stakeholders)

To executives: We can get centralized, searchable application logs on AWS for effectively zero licence spend by adding a small MIT-licensed library to our existing Laravel logging config. It uses our existing AWS permissions rather than new API keys, needs no new vendor contract, and is removable in one deploy if we change direction. The trade-off is that it's a community-maintained package (not AWS-supported), so we should treat it as a tactical solution and revisit if log volume or compliance requirements grow.

To engineering: phpnexus/cwh gives us a Monolog handler that ships to CloudWatch Logs through the AWS SDK credential chain, so we just add a cloudwatch channel in config/logging.php and point LOG_STACK at it alongside our existing channels. It's the maintained successor to the unmaintained maxbanton/cwh and is Monolog 3 compatible. Two engineering guardrails: pin the version and note the fork lineage in our dependency register, and don't put it on a latency-critical path unless we batch or queue the writes. If we containerize later, we should plan to retire it in favour of stdout + FireLens — cheaper, more resilient, and less code to own.