README

PHP library to interacts with ZK Time and Attendance Devices.

Library for connecting under the network using the UDP protocol and port 4370

See ZK communication protocol manual here

Installation

composer require andreracodex/php-zklib

Usage

Basic Connection

<?php
use ZKLib\ZKLib;

$zk = new ZKLib('192.168.1.100'); // Your device IP address

// Connect to device
if ($zk->connect()) {
    echo "Connected successfully";
    
    // Get device information
    echo "Device Version: " . $zk->version();
    echo "OS Version: " . $zk->osVersion();
    echo "Serial Number: " . $zk->serialNumber();
    
    // Set device time
    $zk->setTime(date('Y-m-d H:i:s'));
    
    // Disconnect
    $zk->disconnect();
} else {
    echo "Failed to connect";
}
?>

Get Attendance Records

<?php
$zk = new ZKLib('192.168.1.100');

if ($zk->connect()) {
    $zk->disableDevice();
    
    // Get all attendance records
    $attendance = $zk->getAttendance();
    
    foreach ($attendance as $record) {
        echo "User ID: " . $record['user_id'] . "\n";
        echo "Timestamp: " . $record['timestamp'] . "\n";
        echo "Status: " . $record['status'] . "\n";
    }
    
    $zk->enableDevice();
    $zk->disconnect();
}
?>

Get Users

<?php
$zk = new ZKLib('192.168.1.100');

if ($zk->connect()) {
    // Get all users
    $users = $zk->getUser();
    
    foreach ($users as $user) {
        echo "User ID: " . $user['uid'] . "\n";
        echo "Name: " . $user['name'] . "\n";
        echo "Privilege: " . $user['privilege'] . "\n";
    }
    
    $zk->disconnect();
}
?>

Laravel Integration

1. Install Package

composer require racodex/php-zklib

2. Create a Service Class

Create app/Services/ZKDeviceService.php:

<?php

namespace App\Services;

use ZKLib\ZKLib;

class ZKDeviceService
{
    protected $zk;
    protected $deviceIp;
    
    public function __construct($deviceIp)
    {
        $this->deviceIp = $deviceIp;
        $this->zk = new ZKLib($deviceIp);
    }
    
    public function connect()
    {
        return $this->zk->connect();
    }
    
    public function disconnect()
    {
        $this->zk->disconnect();
    }
    
    public function getAttendance()
    {
        if ($this->connect()) {
            $this->zk->disableDevice();
            $attendance = $this->zk->getAttendance();
            $this->zk->enableDevice();
            $this->disconnect();
            return $attendance;
        }
        return [];
    }
    
    public function getUsers()
    {
        if ($this->connect()) {
            $users = $this->zk->getUser();
            $this->disconnect();
            return $users;
        }
        return [];
    }
    
    public function getDeviceInfo()
    {
        if ($this->connect()) {
            $info = [
                'version' => $this->zk->version(),
                'os_version' => $this->zk->osVersion(),
                'platform' => $this->zk->platform(),
                'serial_number' => $this->zk->serialNumber(),
            ];
            $this->disconnect();
            return $info;
        }
        return [];
    }
}

3. Create a Controller

Create app/Http/Controllers/AttendanceController.php:

<?php

namespace App\Http\Controllers;

use App\Services\ZKDeviceService;
use App\Models\Attendance;

class AttendanceController extends Controller
{
    public function syncAttendance()
    {
        try {
            $zkService = new ZKDeviceService(config('services.zk.device_ip'));
            
            $records = $zkService->getAttendance();
            
            foreach ($records as $record) {
                Attendance::updateOrCreate(
                    [
                        'user_id' => $record['user_id'],
                        'timestamp' => $record['timestamp'],
                    ],
                    [
                        'status' => $record['status'] ?? 0,
                    ]
                );
            }
            
            return response()->json([
                'success' => true,
                'message' => 'Attendance synced successfully',
                'count' => count($records),
            ]);
        } catch (\Exception $e) {
            return response()->json([
                'success' => false,
                'message' => $e->getMessage(),
            ], 500);
        }
    }
    
    public function getUsers()
    {
        try {
            $zkService = new ZKDeviceService(config('services.zk.device_ip'));
            $users = $zkService->getUsers();
            
            return response()->json([
                'success' => true,
                'users' => $users,
            ]);
        } catch (\Exception $e) {
            return response()->json([
                'success' => false,
                'message' => $e->getMessage(),
            ], 500);
        }
    }
}

4. Add Configuration

Update config/services.php:

'zk' => [
    'device_ip' => env('ZK_DEVICE_IP', '192.168.1.100'),
],

Add to .env:

ZK_DEVICE_IP=192.168.1.100

5. Create Routes

Update routes/api.php:

<?php

use App\Http\Controllers\AttendanceController;

Route::post('/attendance/sync', [AttendanceController::class, 'syncAttendance']);
Route::get('/users', [AttendanceController::class, 'getUsers']);

6. Create Attendance Model (Optional)

php artisan make:model Attendance -m

Migration example (database/migrations/xxxx_create_attendances_table.php):

<?php

use Illuminate\Database\Migrations\Migration;
use Illuminate\Database\Schema\Blueprint;
use Illuminate\Support\Facades\Schema;

return new class extends Migration
{
    public function up()
    {
        Schema::create('attendances', function (Blueprint $table) {
            $table->id();
            $table->unsignedBigInteger('user_id');
            $table->timestamp('timestamp');
            $table->tinyInteger('status')->default(0);
            $table->timestamps();
            
            $table->unique(['user_id', 'timestamp']);
        });
    }
    
    public function down()
    {
        Schema::dropIfExists('attendances');
    }
};

7. Create a Queue Job (For Background Processing)

php artisan make:job SyncAttendanceJob

Update app/Jobs/SyncAttendanceJob.php:

<?php

namespace App\Jobs;

use App\Services\ZKDeviceService;
use App\Models\Attendance;
use Illuminate\Bus\Queueable;
use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Foundation\Bus\Dispatchable;
use Illuminate\Queue\InteractsWithQueue;
use Illuminate\Queue\SerializesModels;

class SyncAttendanceJob implements ShouldQueue
{
    use Dispatchable, InteractsWithQueue, Queueable, SerializesModels;
    
    public function handle()
    {
        $zkService = new ZKDeviceService(config('services.zk.device_ip'));
        
        $records = $zkService->getAttendance();
        
        foreach ($records as $record) {
            Attendance::updateOrCreate(
                [
                    'user_id' => $record['user_id'],
                    'timestamp' => $record['timestamp'],
                ],
                [
                    'status' => $record['status'] ?? 0,
                ]
            );
        }
    }
}

Support & Donations

If you found this library helpful and would like to support its development:

Your support helps maintain and improve this library. Thank you!

andreracodex / php-zklib

Maintainers

Details