PHPackages                             zillur-web/zkteco-php-sdk - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Utility & Helpers](/categories/utility)
4. /
5. zillur-web/zkteco-php-sdk

ActiveLibrary[Utility & Helpers](/categories/utility)

zillur-web/zkteco-php-sdk
=========================

ZKTeco PHP SDK for Laravel - A Laravel package for ZKTeco device integration

v1.0.0(today)00MITPHPPHP ^7.4 || ^8.0

Since Jun 19Pushed todayCompare

[ Source](https://github.com/zillur-web/zkteco-php-sdk)[ Packagist](https://packagist.org/packages/zillur-web/zkteco-php-sdk)[ RSS](/packages/zillur-web-zkteco-php-sdk/feed)WikiDiscussions main Synced today

READMEChangelogDependencies (2)Versions (2)Used By (0)

ZKTeco PHP SDK for Laravel & Standalone PHP
===============================================

[](#zkteco-php-sdk-for-laravel--standalone-php)

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
--------

[](#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
------------

[](#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
-------------

[](#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

[](#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

[](#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
-----

[](#usage)

### Standalone PHP

[](#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

[](#laravel)

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

#### 1. Using the Facade (Recommended)

[](#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

[](#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

[](#3-using-the-factory)

```
use ZillurWeb\ZktecoPhpSDK\ZktecoFactory;

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

Available Services
------------------

[](#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
-----------------------------

[](#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
---------------------

[](#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

[](#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

[](#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

[](#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

[](#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-operations)

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

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

### Attendance operations

[](#attendance-operations)

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

$zkteco->clearAttendance();
```

### Device control

[](#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

[](#feature-control-and-device-mode)

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

### Clean up

[](#clean-up)

```
$zkteco->disconnect();
```

Configuration
-------------

[](#configuration)

### For Laravel

[](#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

[](#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
--------

[](#examples)

### Get Device Attendance Records

[](#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

[](#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

[](#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

[](#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
-------

[](#testing)

Run the test suite with:

```
composer test
```

Generate coverage report:

```
composer run test-coverage
```

License
-------

[](#license)

This package is open-sourced software licensed under the [MIT license](LICENSE.md).

Support
-------

[](#support)

For issues, questions, or contributions, please:

1. Check the [Contributing Guidelines](CONTRIBUTING.md)
2. Open an issue on GitHub
3. Submit a pull request

Changelog
---------

[](#changelog)

See [CHANGELOG.md](CHANGELOG.md) for release information.

###  Health Score

37

—

LowBetter than 81% of packages

Maintenance100

Actively maintained with recent releases

Popularity0

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity38

Early-stage or recently created project

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Unknown

Total

1

Last Release

0d ago

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/76123185?v=4)[Zillur Rahman](/maintainers/zillur-web)[@zillur-web](https://github.com/zillur-web)

---

Top Contributors

[![zillur-web](https://avatars.githubusercontent.com/u/76123185?v=4)](https://github.com/zillur-web "zillur-web (1 commits)")

###  Code Quality

TestsPHPUnit

Code StyleLaravel Pint

### Embed Badge

![Health badge](/badges/zillur-web-zkteco-php-sdk/health.svg)

```
[![Health](https://phpackages.com/badges/zillur-web-zkteco-php-sdk/health.svg)](https://phpackages.com/packages/zillur-web-zkteco-php-sdk)
```

###  Alternatives

[minime/annotations

The KISS PHP annotations library

229386.3k38](/packages/minime-annotations)[phpcfdi/cfdi-sat-scraper

Web Scraping para extraer facturas electrónicas desde la página del SAT

9322.4k](/packages/phpcfdi-cfdi-sat-scraper)[mehedi-iitdu/core-component-repository

My awesome package

1552.4k](/packages/mehedi-iitdu-core-component-repository)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)