Laravel Db Session Helper Laravel Package

Getting Started

• Install the package with Composer and publish any config/migrations if the package provides them. Since this is a 0.0.x release, pin the version in composer.json and review the changelog before upgrading.
• Look first at the package’s service provider, config file, and any model trait or base model it expects. The public surface is small: you will primarily interact with the isOnline and isOffline query scopes and whatever attribute/accessor determines the current state.
• The first use case is filtering records by connectivity state — for example, listing online devices, users, or sessions:

  $online = YourModel::isOnline()->get();
  $offline = YourModel::isOffline()->get();
  

• Upgrade to v0.0.2 before relying on the scopes. This release fixes incorrect scope application and fixes a bug that affected non-SQLite database environments, so MySQL/PostgreSQL users should retest their queries after upgrading.

Implementation Patterns

• Use the scopes as query constraints rather than loading all records and filtering in PHP:

  $onlineCount = YourModel::isOnline()->count();
  
  $offlineDevices = YourModel::isOffline()
      ->where('tenant_id', $tenantId)
      ->paginate(50);
  

• Compose the scopes with existing query logic. They should behave like normal Eloquent scopes, so they can be combined with where, relationships, withCount, and pagination. Verify composition after upgrading, because this release changes how the scopes are applied.
• For dashboards or status badges, keep a single source of truth by reusing the same scope logic:

  $isOnline = YourModel::isOnline()->whereKey($model->getKey())->exists();
  

  Avoid duplicating the online/offline threshold logic in controllers or Blade templates.
• If the package uses a heartbeat or last_seen_at-style column, schedule the update from a console command or middleware. The online/offline scopes are only as accurate as the data written to that column.
• For API resources, expose the state consistently:

  return [
      'id' => $this->id,
      'online' => $this->isOnline(), // or the package’s equivalent accessor
  ];
  

  Confirm whether the package exposes an attribute/accessor in addition to the scopes; if not, derive it from the same column or method used by the scopes.
• In tests, use database-agnostic assertions. If your test suite runs SQLite but production runs MySQL/PostgreSQL, add at least one integration test against the production-like driver. The v0.0.2 fix specifically targets non-SQLite environments, so SQLite-only coverage would not have caught the previous bug.

Gotchas and Tips

• Database portability: The v0.0.2 release fixes a bug in non-SQLite environments. If you are on MySQL, PostgreSQL, or another driver, upgrade and re-run any tests or reports that depend on isOnline/isOffline. If you are on SQLite, still verify scope behavior — the second fix affects scope application generally.
• Scope correctness: The release notes state that isOnline and isOffline “weren’t applied right.” Audit existing queries after upgrading. In particular, check queries that combine the scopes with orWhere, relationship constraints, or global scopes, since scope grouping bugs often surface there.
• Pre-1.0 API stability: At 0.0.2, treat the package as early-stage. Pin the exact version, read release notes before updating, and avoid spreading package-specific calls throughout the codebase. Wrap scope usage in repository methods or model query helpers so future API changes are contained.
• Timezone and threshold configuration: Online/offline logic usually depends on a time window. Confirm whether the package uses the application timezone, the database timezone, or UTC, and make sure your heartbeat writer uses the same convention. A mismatch can make every record appear offline.
• Boolean and null states: Check how the package treats records that have never reported a heartbeat. A null timestamp may fall into neither scope or into the offline scope depending on the implementation. Decide explicitly whether “never seen” should count as offline in your UI and queries.
• Debugging: When a scope returns unexpected results, inspect the generated SQL with ->toSql() and ->getBindings() before assuming the package is wrong. Also check for global scopes, soft deletes, and tenant scopes that may be interacting with the package scopes.
• Extension points: If the package exposes config for the timestamp column, threshold, or model trait, prefer configuring those over overriding package internals. If you need custom behavior, extend the model or add a local scope rather than modifying vendor code.