Xetaravel Counts Laravel Package

Technical Evaluation

Package: xetaio/xetaravel-counts — Laravel/Eloquent trait that attaches polymorphic, date-scoped counters (daily/monthly/yearly) to any model via a shared counts morph table.

Architecture fit

• Narrow, single-purpose package: one trait on the consuming model, one polymorphic relation, one table. It is an application-level counter store, not a metrics/analytics pipeline — no aggregation daemon, no time-series store, no rollup job.
• Good fit for engagement counters on content entities (views, downloads, likes, forum thread reads) where counters are read alongside the model and write volume is moderate.
• Poor fit for hot-path telemetry (per-request increments on high-QPS endpoints). Every increment is a synchronous SQL write to a single morph table; at scale this becomes a write-contention and index-bloat problem that the package does not solve for you.
• Coupling is shallow (trait + migration), so the exit cost if we later move to Redis/ClickHouse counters is low — a meaningful de-risking property for a small maintainer project.

Integration feasibility

• Low effort: composer require, publish and run the migration, add the trait, adopt the count helper methods. Expect under a day of engineering plus a backfill script if existing counters must be migrated.
• 3.0.0 is a framework-compatibility release only — no new counting capability, no API surface expansion described. That is the entire delta we have evidence for.

Technical risk

• Major-version cutoff is the dominant risk. A version bump whose sole stated change is "Update to Laravel 13" almost certainly tightens the illuminate/* constraint and drops older framework support. If our platform is not on Laravel 13, 3.0.0 is simply not installable, and the upgrade becomes a framework project, not a package upgrade.
• Single-maintainer, low-activity project. Bus factor of one, no commercial backing, GitHub-issues-only support. A major release delivered as a constraint bump suggests limited change-review surface.
• Unverified breaking surface. We have one line of release notes. We do not know whether the migration, table schema, trait method signatures, return types, or relationship names changed. A major semver bump permits all of these.
• Concurrency/idempotency. Counter increments are not described as atomic upserts; under concurrent writes we should assume drift is possible and verify.

Key questions

1. Does 3.0.0 retain support for Laravel 11/12, or is the constraint ^13.0 only? What is the minimum PHP version?
2. Are there schema or migration changes between 2.0.0 and 3.0.0? Is a data migration required, or is it additive?
3. Did any public trait methods, relationship names, or return types change?
4. Is the increment path atomic (upsert / increment), and is it wrapped in a transaction?
5. What is the test suite coverage, and does CI run against the Laravel 13 matrix?
6. Is there a tagged support window / security policy for the 2.x line?

Integration Approach

Stack fit

• Assumes Laravel 13 with its corresponding PHP floor (likely 8.3+). Confirm against our runtime before any planning; the package version and the framework version are now effectively the same decision.
• No cache, queue, or external service dependency — it fits any standard LAMP/Laravel deployment and does not alter our infrastructure profile.

Migration path

• Path A — already on / planning Laravel 13: adopt 3.0.0 directly. Diff the published migration against the 2.x version in a scratch branch before running php artisan migrate; treat any column or index change as a data-migration task with a rollback plan.
• Path B — on Laravel 11/12: pin ^2.0 and stay there. Do not attempt to force-install 3.0.0 with --ignore-platform-reqs; a compatibility shim for a package this small is more expensive than the framework upgrade it is signalling.
• Path C — greenfield: adopt 3.0.0 only if the Laravel 13 upgrade is already on the roadmap; otherwise start on 2.x to avoid coupling an unrelated feature to a framework migration.

Compatibility

• Build a two-row matrix (our app version → package major) and record it in the dependency register. This package is now a leading indicator of framework upgrade timing, which is worth tracking explicitly rather than discovering at composer update.
• Verify transitive constraints: nothing about this package should block other dependencies, but the Illuminate constraint will interact with anything else pinning the framework.

Sequencing

1. Framework upgrade to Laravel 13 on a branch, package held at 2.x.
2. Confirm the app is green on 13 with 2.x where possible (or accept the coupled jump).
3. Bump to 3.0.0, diff the migration, run package-level tests.
4. Staging deploy with a counter-integrity check (compare sampled counts pre/post).
5. Production rollout behind the normal migration gate; retain a 2.x rollback tag.

Operational Impact

Maintenance

• Very low steady-state cost: no config, no service provider surface to tune, no background workers.
• The real maintenance item is governance, not code: this package is single-maintainer and now gates our framework version. Budget for a fork-and-patch contingency — the codebase is small enough that a vendored fork is a realistic fallback rather than a rewrite.

Support

• Community-only: GitHub issues, no SLA, no security advisory process we can point to. Acceptable for a non-critical counter feature; unacceptable if counters ever become billing- or quota-bearing. Flag that boundary explicitly.

Scaling

• Read cost is a single indexed lookup per model; fine.
• Write cost is one row-upsert per increment per model per period. Growth is O(entities × periods) — unbounded over time unless the table is pruned or partitioned. Plan a retention job for daily rows and an index on (countable_type, countable_id, date).
• For high-traffic entities, do not call the increment inline on the request path — batch through the queue or a write-behind cache. This is a usage pattern, not a package feature; document it in the integration guide so the next team does not relearn it.

Failure modes

• Install failure — composer constraint conflict with the framework; surfaces immediately and loudly. Low severity, easy detection.
• Silent counter drift — non-atomic increments under concurrency; the counter is simply wrong with no error. Highest-severity failure mode because it is invisible. Add a periodic reconciliation check.
• Missing migration / trait misconfiguration — relation resolves to zero rather than throwing; produces plausible-looking but empty data. Guard with a smoke test asserting a known increment lands.
• Unbounded table growth — degradation is gradual (slower writes, larger backups) and therefore easy to defer until it is a page. Set the retention job up at launch, not later.
• Maintainer abandonment — no new release for the next framework major; we are pinned. Mitigated by the low exit cost noted above.

Ramp-up

• Hours for any Laravel developer: one trait, one migration, a handful of helper methods. No new mental model beyond "polymorphic counter table."
• The institutional knowledge worth writing down is short: the write-path batching guidance, the retention job, and the version-pinning rule against the framework.

Assessment basis: release 3.0.0 (framework compatibility bump to Laravel 13 only). All statements about constraint tightening, schema changes, and API stability are inferred from semver and should be confirmed against the package's composer.json and migration diff before committing to a path.