Filament Zkteco Adms Laravel Package

Getting Started

1. Require the matching underlying package version:

   composer require athwari/laravel-zkteco-adms:^1.0.1
   

   The Filament package relies on normalized timestamps and migration stubs from athwari/laravel-zkteco-adms v1.0.1+.

2. Publish and run the migrations explicitly:

   php artisan vendor:publish --tag=filament-zkteco-adms-migrations
   php artisan migrate
   

   Automatic migration loading has been removed, so publishing is now part of installation and upgrade.

3. Configure the device timezone selector and confirm your application timezone. If no valid device timezone is configured, the selector falls back to the PHP runtime timezone.

4. First use case: open the attendance reporting/dashboard area, verify devices have sensible timezones, then build or inspect reports using occurred_at rather than recorded_at.

Implementation Patterns

• Use occurred_at for all reporting logic. Attendance tables, filters, sorts, dashboard statistics, and date-range queries should use the normalized occurred_at timestamp. This gives consistent ordering and aggregation across devices and timezones.

• Display recorded_at as source data. Keep recorded_at visible where operators need the original device-local timestamp for audit or troubleshooting, but do not use it as the primary reporting axis.

• Publish migrations per environment and per tenant. Add the migration publish step to deployment and tenant-provisioning workflows. For tenant setups, publish the migration stub during tenant creation so the tenant migration timestamp is generated at publish time.

• Use the searchable timezone selector during device setup. Let admins choose the device timezone from the configurable selector. This is especially useful for multi-site deployments where devices may run in different local timezones.

• Keep reporting widgets consistent. In Filament resources and dashboard widgets, standardize on occurred_at for:

  • table sorting
  • date filters
  • attendance summaries
  • late/early calculations
  • dashboard statistics

• Treat the migration stub as the extension point. If you need to customize attendance storage or tenant behavior, publish the stub and modify the published migration rather than relying on package-loaded migrations.

Gotchas and Tips

• Upgrading requires a migration publish step. Since automatic migration loading is gone, existing deployments that depended on it must publish filament-zkteco-adms-migrations and run migrations. Missing this step can leave the app without expected tables or columns.

• Do not mix occurred_at and recorded_at in reports. Use occurred_at for sorting, filtering, and statistics. recorded_at is device-local and can produce misleading ordering or totals across timezones.

• Check the underlying package version. The Filament package requires athwari/laravel-zkteco-adms v1.0.1 or newer. Older versions may not provide normalized timestamps or the expected migration stubs.

• Tenant migrations need deliberate publishing. The tenant migration timestamp is generated when published. Include publishing in tenant provisioning rather than copying migration files manually, which can produce stale or inconsistent timestamps.

• Timezone fallback can hide missing configuration. If the device timezone selector is unset or invalid, the package falls back to the PHP runtime timezone. Confirm both the device timezone and Laravel app.timezone are correct in production.

• Test bootstrap support includes .php.stub migrations. If you maintain tests around migrations from either ZKTeco package, ensure your test bootstrap handles .php.stub migration files, especially for tenant or package migration publishing tests.

• Debug timestamp issues at the source. When attendance looks shifted, first verify the device timezone, then inspect both occurred_at and recorded_at. occurred_at should drive reporting; recorded_at explains what the device originally sent.