Xetaravel Counts Laravel Package

Getting Started

• Check Laravel compatibility first. Version 3.0.0 is a Laravel 13 compatibility release. If the application is on Laravel 12 or older, stay on the 2.x line until the app is upgraded.

• Install with Composer:

  composer require xetaio/xetaravel-counts
  

• Publish and run any package migrations/config if the package provides them:

  php artisan vendor:publish --provider="Xetaio\Counts\CountsServiceProvider"
  php artisan migrate
  

  Confirm the actual provider name from the package README or composer.json before running this.

• First place to look: the package README and src/ directory for the counter trait, service/facade, config file, and migration stubs. The first practical use case is attaching the package’s counter behavior to an Eloquent model, then incrementing and reading a count from a controller, listener, or tinker session.

• Since 3.0.0 only updates Laravel support, existing 2.x usage should mostly carry over. Validate the same flows after upgrading rather than expecting new APIs.

Implementation Patterns

• Attach counters to models via the package trait. Use the provided trait on models that need counts, then increment/decrement through the package API rather than manually writing update(['count' => ...]).
• Use atomic increments for hot paths. For view counts, likes, downloads, or similar events, prefer the package’s increment helpers or atomic DB operations. Avoid read-modify-write patterns that lose updates under concurrency.
• Wrap multi-step count changes in transactions. If a count change is tied to creating a record, awarding a like, or recording an event, keep the count update and the source record in the same transaction where consistency matters.
• Record counts from events/listeners. A clean integration is to dispatch a domain event such as PostViewed and let a listener increment the counter. This keeps controllers thin and makes retries/queueing easier.
• Queue high-volume counting. For traffic-heavy counters, increment in a queued job or use a buffered/cached counter that is periodically flushed to the database.
• Eager load counts for listings. If counts are stored as relationships or aggregate values, eager load them to avoid N+1 queries on index pages.
• Add tests around increments. Use RefreshDatabase and assert that the count changes by the expected amount, including repeated increments and decrements.
• Use morph maps if counters are polymorphic. If the package supports counting multiple model types, configure Laravel’s morph map so stored model types remain stable if class namespaces change.

Gotchas and Tips

• 3.0.0 is a breaking compatibility change for older Laravel versions. It targets Laravel 13. Applications on Laravel 12 or earlier should pin ^2.0 and defer the upgrade until the framework upgrade is complete.
• No new feature surface is advertised in this release. Treat 3.0.0 as a compatibility bump: upgrade Composer constraints, run the full test suite, and verify migrations/config still publish correctly.
• Check the PHP requirement. Laravel 13 typically raises the minimum PHP version; confirm the package’s composer.json before upgrading in CI or production.
• Counter drift is the main long-term risk. Provide a rebuild/recalculate command or internal job that recomputes counts from source events when counters become inconsistent.
• Make increments idempotent where retries are possible. Queued listeners and webhook-driven counts can double-count if the same event is processed twice. Use unique event IDs or a processed-events table when needed.
• Verify service provider discovery. If counts do not change, check package auto-discovery, config caching, and whether the model actually uses the package trait.
• Watch config quirks. Table names, database connection, morph aliases, and cache stores may be configurable. Publish the config and review it instead of assuming defaults.
• Debug with a minimal path. In tinker, attach the trait to a test model, call the increment method, and confirm both the returned value and the database row. If that works, move outward to listeners, middleware, and controllers.
• Extension points to inspect: custom counter keys, overridable models/repositories, package events, and config-driven table/connection settings. These are the safest places to customize without forking.