README

A comprehensive PHP package for integrating ZKTeco biometric and access control devices. Works as both a standalone PHP library and as a Laravel package.

Features

✅ Standalone PHP usage - no framework required
✅ Laravel package integration with service container and Facade
✅ Support for multiple device services (Attendance, User, Face Recognition, etc.)
✅ Service provider for automatic package registration
✅ Comprehensive exception handling
✅ Clean, maintainable architecture

Installation

Install the package via Composer. This package supports both raw PHP and Laravel with the same install.

composer require zillur-web/zkteco-php-sdk

If you use this package in a raw PHP project, you do not need Laravel; just use ZktecoFactory.
If you use this package in a Laravel project, use the same package, and then use Laravel-specific features such as the service provider and facade.

You do not need separate package installations. The same package works for both raw PHP and Laravel.

Raw PHP Usage

Use this package in a raw PHP script without Laravel.

require __DIR__ . '/vendor/autoload.php';

use ZillurWeb\ZktecoPhpSDK\ZktecoFactory;

$zkteco = ZktecoFactory::make('192.168.1.201', 4370, false, 25);
$zkteco->connect();
$attendance = $zkteco->getAttendance();
$zkteco->disconnect();

Single Device Configuration

$config = [
    'host' => '192.168.1.201',
    'port' => 4370,
    'should_ping' => false,
    'timeout' => 25,
    'password' => 0,
];

$zkteco = ZktecoFactory::makeFromConfig($config);
$zkteco->connect();
$attendance = $zkteco->getAttendance();
$zkteco->disconnect();

Multiple Device Configuration

$devices = [
    'office' => [
        'host' => '192.168.1.201',
        'port' => 4370,
        'should_ping' => false,
        'timeout' => 25,
        'password' => 0,
    ],
    'factory' => [
        'host' => '192.168.1.202',
        'port' => 4370,
        'should_ping' => false,
        'timeout' => 25,
        'password' => 0,
    ],
];

foreach ($devices as $name => $deviceConfig) {
    $zkteco = ZktecoFactory::makeFromConfig($deviceConfig);
    $zkteco->connect();
    $records = $zkteco->getAttendance();

    // Process or store records for this device
    echo "Device: $name - " . count($records) . " records\n";

    $zkteco->disconnect();
}

Usage

Standalone PHP

Use the factory class to create ZKTeco instances without Laravel:

use ZillurWeb\ZktecoPhpSDK\ZktecoFactory;

// Create a new instance
$zkteco = ZktecoFactory::make('192.168.1.201', 4370, false, 25);

// Or with config array
$zkteco = ZktecoFactory::makeFromConfig([
    'host' => '192.168.1.201',
    'port' => 4370,
    'should_ping' => false,
    'timeout' => 25,
]);

// Use the various services
$attendance = $zkteco->getAttendance();
$users = $zkteco->getUser();

Laravel

The package automatically registers in Laravel. You can use it in three ways:

1. Using the Facade (Recommended)

use ZillurWeb\ZktecoPhpSDK\Facades\Zkteco;

// Create instance
$zkteco = Zkteco::make('192.168.1.201', 4370);

// Use services
$attendance = $zkteco->getAttendance();

2. Using Service Container

// In your controller or service
public function __construct(ZKTeco $zkteco)
{
    $this->zkteco = $zkteco;
}

public function getAttendance()
{
    return $this->zkteco->getAttendance();
}

3. Using the Factory

use ZillurWeb\ZktecoPhpSDK\ZktecoFactory;

$factory = app('zkteco');
$zkteco = $factory->make('192.168.1.201');

Available Services

The package includes the following services:

Attendance - Manage attendance records
User - User management and operations
Face - Face recognition features
Fingerprint - Fingerprint management
Device - Device management
Connect - Device connectivity
Ping - Device health checks
Time - Time synchronization
Os - Operating system info
Version - Version information
SerialNumber - Device serial numbers
Vendor - Vendor information
Platform - Platform information
Ssr - SSR operations
Pin - PIN management
WorkCode - Work code management
Util - Utility functions

Public ZKTeco Library Methods

Use these methods on a ZillurWeb\ZktecoPhpSDK\Library\ZKTeco instance.

__construct(string $ip, int $port = 4370, bool $shouldPing = false, int $timeout = 25, $password = 0) - Create a new device client with connection settings.
setPing(bool $shouldPing = false, bool $silentPing = true): void - Enable or disable ping checks before connecting.
connect(): bool - Open a connection to the ZKTeco device.
disconnect(): bool - Close the connection to the device.
version() - Read the device firmware version.
osVersion() - Read the device operating system version.
platform() - Read the device platform details.
fmVersion() - Read the firmware module version.
workCode() - Get the configured work code data.
ssr() - Get the SSR (Self-Service Recorder) status/data.
pinWidth() - Read the device PIN width configuration.
faceFunctionOn() - Enable face recognition mode on the device.
serialNumber() - Read the device serial number.
vendorName() - Read the device vendor name.
deviceId() - Read the device ID.
deviceName() - Read the device name.
disableDevice() - Disable the device.
enableDevice() - Enable the device.
getDeviceData(string $key) - Read a device-specific data field.
setCustomData(string $key, $value) - Write custom data to the device.
getCustomData(string $key) - Read custom data previously stored on the device.
setPushCommKey($value) - Set the push communication key.
getPushCommKey() - Get the current push communication key.
getUsers(callable $callback = null): array - Fetch all user records from the device.
setUser(int $uid, $userid, string $name, $password, int $role = Util::LEVEL_USER, int $cardno = 0) - Add or update a user record.
clearAllUsers() - Delete all users from the device.
deleteUsers(callable $callback) - Remove users by callback filter.
clearAdminPriv() - Clear administrator privileges from current users.
removeUser(int $uid) - Remove a single user by UID.
getFingerprint(int $uid) - Read fingerprint data for a given UID.
setFingerprint(int $uid, array $fingerprint) - Write fingerprint data for a given UID.
removeFingerprint($uid, array $data) - Delete fingerprint records for a UID.
getAttendance(callable $callback = null): array - Read attendance log records.
clearAttendance() - Clear the attendance log on the device.
setTime($t) - Set device time.
getTime() - Read the current device time.
shutdown() - Power off the device.
restart() - Restart the device.
sleep() - Put the device into sleep mode.
resume() - Wake the device from sleep mode.
testVoice($index = 0) - Play a voice test sound on the device.
clearLCD() - Clear the device LCD display.
writeLCD($message = 'Welcome ZkTeco') - Write a message to the LCD display.
getMemoryInfo() - Read memory usage information from the device.
ping($throw = false) - Ping the device and optionally throw on failure.

Method Usage Examples

These examples show how to use the ZKTeco methods in raw PHP. Start by creating a device instance with ZktecoFactory, then call connect(), use the methods, and finally call disconnect().

Connection and ping

use ZillurWeb\ZktecoPhpSDK\ZktecoFactory;

$zkteco = ZktecoFactory::make('192.168.1.201', 4370, false, 25);
$zkteco->setPing(false); // optional, disable ping before connect
$connected = $zkteco->connect();

if (! $connected) {
    echo "Unable to connect to device.";
    exit(1);
}

if ($zkteco->ping()) {
    echo "Device is reachable." . PHP_EOL;
}

Read device info

$version = $zkteco->version();
os = $zkteco->osVersion();
$platform = $zkteco->platform();
$firmware = $zkteco->fmVersion();
$serial = $zkteco->serialNumber();
$vendor = $zkteco->vendorName();
$deviceId = $zkteco->deviceId();
$deviceName = $zkteco->deviceName();
$memoryInfo = $zkteco->getMemoryInfo();

print_r([
    'version' => $version,
    'os' => $os,
    'platform' => $platform,
    'firmware' => $firmware,
    'serial' => $serial,
    'vendor' => $vendor,
    'deviceId' => $deviceId,
    'deviceName' => $deviceName,
    'memoryInfo' => $memoryInfo,
]);

Custom device data

$deviceData = $zkteco->getDeviceData('some_key');
$zkteco->setCustomData('some_key', 'value');
$customValue = $zkteco->getCustomData('some_key');
$zkteco->setPushCommKey('my_push_key');
$pushKey = $zkteco->getPushCommKey();

User management

$users = $zkteco->getUsers();
foreach ($users as $user) {
    echo $user['name'] . " (" . $user['uid'] . ")" . PHP_EOL;
}

$zkteco->setUser(14, '14', 'John Doe', '1234', Util::LEVEL_USER, 0);
$zkteco->removeUser(14);
$zkteco->clearAdminPriv();
// deleteUsers requires a callback that returns true for each user to delete
$zkteco->deleteUsers(function ($user) {
    return $user['uid'] === 14;
});
$zkteco->clearAllUsers();

Fingerprint operations

$fingerprint = $zkteco->getFingerprint(14);
print_r($fingerprint);

$zkteco->setFingerprint(14, [0 => $fingerprintTemplate]);
$zkteco->removeFingerprint(14, [0]);

Attendance operations

$attendance = $zkteco->getAttendance();
foreach ($attendance as $record) {
    echo $record['employee_id'] . " - " . $record['timestamp'] . PHP_EOL;
}

$zkteco->clearAttendance();

Device control

$zkteco->setTime(date('Y-m-d H:i:s'));
$currentTime = $zkteco->getTime();

$zkteco->testVoice(0);
$zkteco->writeLCD('Welcome ZKTeco');
$zkteco->clearLCD();

$zkteco->sleep();
$zkteco->resume();
$zkteco->restart();
$zkteco->shutdown();

Feature control and device mode

$zkteco->faceFunctionOn();
$zkteco->disableDevice();
$zkteco->enableDevice();

Clean up

$zkteco->disconnect();

Configuration

For Laravel

Publish the package configuration file:

php artisan vendor:publish --provider="ZillurWeb\\ZktecoPhpSDK\\ZktecoPhpServiceProvider"

This creates config/zkteco.php where you can configure device settings:

return [
    'default' => env('ZKTECO_DEFAULT', 'default'),
    
    'devices' => [
        'default' => [
            'host' => env('ZKTECO_HOST', '192.168.1.201'),
            'port' => env('ZKTECO_PORT', 4370),
            'should_ping' => env('ZKTECO_SHOULD_PING', false),
            'timeout' => env('ZKTECO_TIMEOUT', 25),
            'password' => env('ZKTECO_PASSWORD', 0),
        ],
    ],
];

Update your .env file:

ZKTECO_HOST=192.168.1.201
ZKTECO_PORT=4370
ZKTECO_SHOULD_PING=false
ZKTECO_TIMEOUT=25
ZKTECO_PASSWORD=0

For Standalone PHP

Create a config array and pass it to the factory:

$config = [
    'host' => '192.168.1.201',
    'port' => 4370,
    'should_ping' => false,
    'timeout' => 25,
    'password' => 0,
];

$zkteco = ZktecoFactory::makeFromConfig($config);

Examples

Get Device Attendance Records

use ZillurWeb\ZktecoPhpSDK\ZktecoFactory;

$zkteco = ZktecoFactory::make('192.168.1.201', 4370, false, 25);
$zkteco->connect();
$attendance = $zkteco->getAttendance();

foreach ($attendance as $record) {
    echo $record['employee_id'] . " - " . $record['timestamp'] . PHP_EOL;
}

$zkteco->disconnect();

Get User List

use ZillurWeb\ZktecoPhpSDK\ZktecoFactory;

$zkteco = ZktecoFactory::make('192.168.1.201', 4370, false, 25);
$zkteco->connect();
$users = $zkteco->getUsers();

foreach ($users as $user) {
    echo $user['name'] . " (" . $user['uid'] . ")" . PHP_EOL;
}

$zkteco->disconnect();

Get Fingerprint Data

use ZillurWeb\ZktecoPhpSDK\ZktecoFactory;

$zkteco = ZktecoFactory::make('192.168.1.201', 4370, false, 25);
$zkteco->connect();
$fingerprint = $zkteco->getFingerprint(14);

print_r($fingerprint);

$zkteco->disconnect();

Device Information

use ZillurWeb\ZktecoPhpSDK\ZktecoFactory;

$zkteco = ZktecoFactory::make('192.168.1.201', 4370, false, 25);
$zkteco->connect();
$version = $zkteco->version();
$serialNumber = $zkteco->serialNumber();
$vendor = $zkteco->vendorName();

echo "Device: $vendor, Version: $version, Serial: $serialNumber" . PHP_EOL;

$zkteco->disconnect();

Testing

Run the test suite with:

composer test

Generate coverage report:

composer run test-coverage

License

This package is open-sourced software licensed under the MIT license.

Support

For issues, questions, or contributions, please:

Check the Contributing Guidelines
Open an issue on GitHub
Submit a pull request

Changelog

See CHANGELOG.md for release information.

zillur-web / zkteco-php-sdk

Maintainers

Package info

Statistics

Security