athwari/filament-zkteco-adms

Filament v5 plugin implementing the ZKTeco ADMS protocol for biometric attendance devices.

v1.0.1 2026-07-01 02:27 UTC

Requires

• php: ^8.2|^8.3|^8.4
• athwari/laravel-zkteco-adms: ^1.0
• filament/filament: ^5.0
• spatie/laravel-package-tools: ^1.16

Requires (Dev)

• laravel/pint: ^1.1
• orchestra/testbench: ^9.0|^10.0|^11.0
• pestphp/pest: ^1.0|^2.0|^3.0
• pestphp/pest-plugin-laravel: ^1.0|^2.0|^3.0
• phpstan/extension-installer: ^1.4
• phpstan/phpstan: ^1.10|^2.0
• phpunit/phpunit: ^10.5|^11.0
• rector/rector: ^1.0|^2.0

MIT

• laravel
• attendance
• biometric
• zkteco
• filament
• adms
• athwari

Published on Packagist.org on 2026-07-01 02:37 UTC

README

This Filament v5 plugin provides the admin UI for ZKTeco ADMS and owns tenancy behavior for the ZKTeco domain.

It is built on top of athwari/laravel-zkteco-adms (core backend logic) and adds:

• Filament resources, pages, and widgets
• Tenant-aware model behavior for devices and users
• Publishable tenant column migration for zkteco devices and users tables
• Tenant-scoped resource queries for attendance logs and device commands

Features

• Device, user, attendance log, and device command resources
• Dashboard and stats widgets
• Plugin-owned multi-tenancy settings via filament-zkteco-adms.multi_tenancy
• Plugin model overrides for zkteco-adms.models.device and zkteco-adms.models.user
• Normalized attendance reporting using occurred_at, while retaining the device-local recorded_at
• Publishable tenant migration with a generated timestamp

Installation

Install the core package and this plugin:

composer require athwari/laravel-zkteco-adms athwari/filament-zkteco-adms

Register the plugin in your Filament panel provider:

use Athwari\FilamentZktecoAdms\FilamentZktecoAdmsPlugin;
use Filament\Panel;

public function panel(Panel $panel): Panel
{
    return $panel
        // ...
        ->plugin(FilamentZktecoAdmsPlugin::make());
}

Configuration

Publish the plugin configuration file:

php artisan vendor:publish --tag="filament-zkteco-adms-config"

Main config keys in config/filament-zkteco-adms.php:

• timezone_options
• multi_tenancy.enabled
• multi_tenancy.tenant_model
• multi_tenancy.tenant_column
• multi_tenancy.tenant_relationship
• filament.navigation_group
• filament.navigation_sort

Publish the core and plugin migrations, then run them:

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

Migration timestamps are generated when the files are published. Publish the core migrations first so the ZKTeco tables exist before the plugin adds tenant columns.

Device Timezones

The device form uses a searchable timezone selector. By default, an empty timezone_options configuration exposes every timezone supported by the PHP runtime, including legacy aliases:

'timezone_options' => [],

Use an indexed list to restrict the selector while displaying the timezone identifiers unchanged, or an associative array to provide custom labels:

'timezone_options' => [
    'UTC',
    'Asia/Aden' => 'Yemen',
],

Invalid identifiers are ignored. If no configured identifier is valid, the selector falls back to the complete PHP runtime list. New devices default to zkteco-adms.default_timezone when available, then UTC, then the first configured option.

Usage

After registration, resources and pages are discovered automatically. By default, resource slugs are:

• zkteco/devices
• zkteco/users
• zkteco/attendance-logs
• zkteco/device-commands

The final URL depends on your panel path prefix.

Attendance reports, date filters, sorting, and dashboard statistics use the normalized occurred_at timestamp. The original recorded_at value remains visible as the device-local timestamp for backward compatibility.

Tenancy Ownership

Tenancy for the ZKTeco domain is owned by this plugin.

When multi_tenancy.enabled is true:

• ZktecoDevice and ZktecoUser models are auto-assigned to the active Filament tenant on create
• Attendance log and device command resources are scoped through each record's related device tenant
• Core config keys zkteco-adms.models.device and zkteco-adms.models.user are overridden to plugin models

Testing

Run the test suite with:

composer test

Additional useful scripts:

composer test-coverage
composer analyse
composer format

Architecture Boundary

• athwari/laravel-zkteco-adms: protocol, parsing, command and persistence core
• athwari/filament-zkteco-adms: Filament UI and tenancy ownership

Contributing

Please see CONTRIBUTING for details.

Security

Please review SECURITY if you discover a vulnerability in this package.

Credits

• Athwari
• All Contributors

License

The MIT License (MIT). Please see LICENSE.md for more information.