jmrashed / zkteco

ZKTeco Package For Laravel. This package provides seamless integration with ZKTeco devices within Laravel applications, enabling communication with attendance devices such as fingerprint, face recognition, or RFID using UDP protocol.https://packagist.org/packages/jmrashed/zkteco
https://packagist.org/packages/jmrashed/zkteco
MIT License
17 stars 6 forks source link
jmrashed laravel-package sdk zkteco zkteco-device

Packagist Downloads GitHub stars GitHub forks License Latest Stable Version GitHub issues GitHub closed issues GitHub pull requests GitHub closed pull requests

This Laravel package provides convenient functions for interacting with ZKTeco devices, allowing seamless communication with attendance devices (such as fingerprint, face recognition, or RFID) using UDP protocol. It simplifies the process of reading and writing data directly to these devices from a web server without the need for additional programs.

With this package, you can easily perform various activities with ZKTeco devices, such as retrieving attendance logs, setting user data, enabling or disabling device functions, and more, all within your Laravel application.

Designed as a class-based library, you can simply create an object of the provided class and utilize its functions to interact with ZKTeco devices effortlessly.

Key features include:

Experience streamlined communication and management of ZKTeco devices directly from your Laravel application with this ZKTeco Laravel package.

The jmrashed/zkteco package provides easy to use functions to ZKTeco Device activities.

Prerequisites

Installation

To use the ZKTeco library, you need to include it in your PHP project. You can install it via Composer:

composer require jmrashed/zkteco

Enabling PHP Sockets

This guide outlines the steps to enable PHP sockets on your server. Sockets are essential for establishing communication channels between different processes or computers over a network.

Prerequisites

Steps

  1. Check PHP Installation: Verify that PHP is installed on your server by running php -v in your terminal or command prompt.

  2. Enable Sockets Extension: Edit the php.ini file to enable the sockets extension. Find the following line:

;extension=sockets

Remove the semicolon at the beginning of the line to uncomment it:

    extension=sockets
  1. Restart Web Server: After editing php.ini, restart your web server to apply the changes. Use the appropriate command based on your server software (e.g., Apache, Nginx).

  2. Verify Installation: Create a PHP file (e.g., test.php) with the following contents:

    <?php
    if (function_exists('socket_create')) {
        echo "Sockets extension is enabled.";
    } else {
        echo "Sockets extension is not enabled.";
    }

    Access this file through your web browser to verify that the sockets extension is enabled.

  3. Firewall Configuration (if necessary): If you're using a firewall, ensure it allows connections on the socket port (default: 80).

  4. Test Socket Communication: Implement socket communication logic in your PHP scripts to test the functionality. See the provided PHP example for creating a socket connection.

Example Usage

Include the steps outlined in this guide in your server setup documentation to ensure proper configuration and enable PHP sockets for your applications.

Usage of ZKTeco

  1. The provided PHP code snippet seems to demonstrate the usage of the ZKTeco library, specifically for interacting with ZKTeco devices, likely for biometric attendance or access control systems. Let's elaborate on the code:

Calling ZKTeco Methods

1. Connect to Device

// Connect to the ZKTeco device
// Returns a boolean indicating whether the connection was successful
$connected = $zk->connect();

2. Disconnect from Device

// Disconnect from the ZKTeco device
// Returns a boolean indicating whether the disconnection was successful
$disconnected = $zk->disconnect();

3. Enable Device

// Enable the ZKTeco device
// Returns a boolean or mixed value indicating whether the device was enabled
// Note: This method should be called after reading/writing any device information
$enabled = $zk->enableDevice();

Note: It's important to call the enableDevice() method after any read or write operation on the device.

4. Disable Device

// Disable the ZKTeco device
// Returns a boolean or mixed value indicating whether the device was disabled
// Note: This method should be called before reading or writing any device information
$disabled = $zk->disableDevice();

5. Device Version

// Get the firmware version of the ZKTeco device
// Returns a boolean or mixed value containing the device version information
$version = $zk->version();

6. Device OS Version

// Get the operating system version of the ZKTeco device
// Returns a boolean or mixed value containing the device OS version information
$osVersion = $zk->osVersion(); 

7. Power Off

// Turn off the ZKTeco device
// Returns a boolean or mixed value indicating whether the device shutdown was successful
$shutdown = $zk->shutdown();

8. Restart

// Restart the ZKTeco device
// Returns a boolean or mixed value indicating whether the device restart was successful
$restart = $zk->restart();

9. Sleep

// Put the ZKTeco device into sleep mode
// Returns a boolean or mixed value indicating whether the device entered sleep mode
$sleep = $zk->sleep();

10. Resume

// Resume the ZKTeco device from sleep mode
// Returns a boolean or mixed value indicating whether the device resumed from sleep mode
$resume = $zk->resume();

11. Voice Test

// Test the voice functionality of the ZKTeco device by saying "Thank you"
// Returns a boolean or mixed value indicating whether the voice test was successful
$voiceTest = $zk->testVoice();

12. Platform

// Get the platform information of the ZKTeco device
// Returns a boolean or mixed value containing the platform information
$platform = $zk->platform();

13. Firmware Version

// Get the firmware version of the ZKTeco device
// Returns a boolean or mixed value containing the firmware version information
$fmVersion = $zk->fmVersion();

14. Work Code

// Get the work code information of the ZKTeco device
// Returns a boolean or mixed value containing the work code information
$workCode = $zk->workCode(); 

15. Device Name

// Get the name of the ZKTeco device
// Returns a boolean or mixed value containing the device name information
$deviceName = $zk->deviceName(); 

16. Get Device Time

// Get the current time of the ZKTeco device
// Returns a boolean or mixed value containing the device time information
// Format: "Y-m-d H:i:s"
$deviceTime = $zk->getTime();

17. Set Device Time

// Set the time of the ZKTeco device
// Parameters:
// - string $t: Time string in format "Y-m-d H:i:s"
// Returns a boolean or mixed value indicating whether the device time was successfully set
$setTimeResult = $zk->setTime($timeString);

18. Get Users

// Get the list of users stored in the ZKTeco device
// Returns an array containing user information
$users = $zk->getUser();

19. Set Users

// Set a user in the ZKTeco device
// Parameters:
// - int $uid: Unique ID (max 65535)
// - int|string $userid: ID in DB (max length = 9, only numbers - depends device setting)
// - string $name: User name (max length = 24)
// - int|string $password: Password (max length = 8, only numbers - depends device setting)
// - int $role: User role (default Util::LEVEL_USER)
// - int $cardno: Card number (default 0, max length = 10, only numbers)
// Returns a boolean or mixed value indicating whether the user was successfully set
$setUserResult = $zk->setUser($uid, $userid, $name, $password, $role, $cardno);

20. Clear All Admin

// Remove all admin users from the ZKTeco device
// Returns a boolean or mixed value indicating whether all admin users were successfully removed
$clearedAdmin = $zk->clearAdmin();

21. Clear All Users

// Remove all users from the ZKTeco device
// Returns a boolean or mixed value indicating whether all users were successfully removed
$clearedUsers = $zk->clearUsers();

22. Remove A User

// Remove a user from the ZKTeco device by UID
// Parameters:
// - integer $uid: User ID to remove
// Returns a boolean or mixed value indicating whether the user was successfully removed
$removedUser = $zk->removeUser($uid);

23. Get Attendance Log

// Get the attendance log from the ZKTeco device
// Returns an array containing attendance log information
// Each entry in the array represents a single attendance record with fields: uid, id, state, timestamp, and type
$attendanceLog = $zk->getAttendance();

24. Get Todays Attendance Log

24.1 getTodaysRecords()

// Get the today attendance log from the ZKTeco device
// Returns an array containing attendance log information
// Each entry in the array represents a single attendance record with fields: uid, id, state, timestamp, and type
$attendanceLog = $zk->getTodaysRecords();

Sample Response Example

  array (
    'uid' => 33,
    'id' => '108',
    'state' => 1,
    'timestamp' => '2024-04-24 18:13:47',
    'type' => 1,
  )

24.2 Get today's Records

    public function zkteco()
    {
        $zk = new ZKTeco('192.168.1.201');
        $connected = $zk->connect();
        $attendanceLog = $zk->getAttendance();

        // Get today's date
        $todayDate = date('Y-m-d');

        // Filter attendance records for today
        $todayRecords = [];
        foreach ($attendanceLog as $record) {
            // Extract the date from the timestamp
            $recordDate = substr($record['timestamp'], 0, 10);

            // Check if the date matches today's date
            if ($recordDate === $todayDate) {
                $todayRecords[] = $record;
            }
        }

        // Now $todayRecords contains attendance records for today
        Log::alert($todayRecords); 
    }

24.3 Get Latest Attendance with Limit

// Get the 5 latest attendance records
$latestAttendance = $zk->getAttendance(5);

24.4 Clear Attendance Log

// Clear the attendance log from the ZKTeco device
// Returns a boolean or mixed value indicating whether the attendance log was successfully cleared
$clearedAttendance = $zk->clearAttendance();

Change log

Please see CHANGELOG for more information what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security

If you discover any security-related issues, please email jmrashed@gmail.com instead of using the issue tracker.

License

The MIT License (MIT). Please see License File for more information.

Conclusion

This guide covers various methods provided by the ZKTeco library in PHP for interacting with ZKTeco devices. You can use these methods to perform various operations such as device management, user management, attendance tracking, and more.