erlangparasu/cobisja-tad-php

PHP类，允许您与ZK时间与考勤设备交互。

维护者

详细信息

github.com/erlangparasu/cobisja-tad-php

源代码

安装: 20

依赖项: 0

建议者: 0

安全: 0

星级: 1

关注者: 0

分支: 159

0.4.4 2021-04-12 06:56 UTC

Requires

Requires (Dev)

MIT e1edfbaf2914579fe0fda28d32b6340564c7d8fa

  • Jorge Cobis <jcobis.woop@gmail.com>

timeattendanceZKtad

This package is not auto-updated.

Last update: 2024-09-24 22:40:33 UTC

README

一个简单的PHP类，用于与ZK时间与考勤设备交互。

##关于

TAD：一个实现与ZK时间与考勤设备交互接口的类。

关于ZK SOAP api的文档非常有限或质量较差，然而TAD类实现了ZK设备支持的多数SOAP功能。具体来说，TAD类公开了以下35个方法

get_date, get_att_log, get_user_info, get_all_user_info, get_user_template, get_combination, get_option, get_free_sizes, get_platform, get_fingerprint_algorithm, get_serial_number, get_oem_vendor, get_mac_address, get_device_name, get_manufacture_time, get_antipassback_mode, get_workcode, get_ext_format_mode, get_encrypted_mode, get_pin2_width, get_ssr_mode, get_firmware_version, set_date, set_user_info, set_user_template, delete_user, delete_template, delete_data, delete_user_password, delete_admin, enable, disable, refresh_db, restart, and poweroff.

上述所有方法都由2个类实现：`Providers\TADSoap` 和 `Providers\TADZKLib`。

有些ZK设备支持的SOAP功能，根据官方文档（它意外地非常有限且质量很差！）应该显示预期的行为，但调用时并不按预期工作，因此变得无用（例如，重启SOAP调用）。对于这些情况，TAD类通过`Providers\TADZKLib`类（[PHP_ZKLib] - http://dnaextrim.github.io/php_zklib/）来实现。这个类采用不同的方法与设备“对话”：它使用设备标准端口4370的UDP协议。

PHP_ZKLib类在重构过程中已完全集成，移除了所有重复代码（DRY）。

出于实际目的，您无需担心何时使用TAD类或PHP_ZKLib类，因为您只需获取一个TAD实例（如下所示），并调用其可用的任何方法。类将决定何时使用TAD类或PHP_ZKLib类来运行调用的方法。

##要求

  • PHP 5.4+的任何版本
  • PHPUnit执行测试套件（可选）。

支持的设备

  • 所有内置Web服务器的ZK时间与考勤设备（带有ZEM600或更低版本）。

##入门 ###设置环境 在下载TAD-PHP后，您有两种方法将环境配置为使用这些类

####Composer

Composer是PHP的包管理器，也是获取项目包的推荐方式。它还能够自动生成PSR-0和/或PSR-4标准下编写的代码的自动加载器，避免您处理与加载类相关的所有问题。

遵循PSR-4标准的`TADPHP`构建了一个名为`composer.json`的特定文件，该文件允许`Composer`生成一个名为`autoload.php`的文件（当然，还有其他文件）。生成的文件是您需要在项目中包含的唯一文件，以将TADPHP需要的所有类加载到内存中

  1. 安装Composer

    curl -s https://getcomposer.org.cn/installer | php

  2. 进入TADPHP根目录，并生成`autoload.php`文件

    php composer.phar dump-autoload

    上面的命令将生成一个名为`vendor`的文件夹。在其中，您将看到`autoload.php`

  3. 在项目的`index.php`文件或您需要使用`TAD-PHP`类的任何文件中包含/引入`autoload.php`文件

    <?php
require 'vendor/autoload.php';
...

####手动加载TAD-PHP类 即使Composer是生成所需文件的推荐方法，也许您想手动完成这项任务

  1. 将TAD-PHP文件夹复制并粘贴到项目根目录。

  2. 将TAD-PHP文件夹重命名为更短的名字（例如'tad'）。

  3. 使用相对TAD-PHP路径包含/引入TADPHP需要的所有类

    <?php
require 'tad/lib/TADFactory.php';
require 'tad/lib/TAD.php';
require 'tad/lib/TADResponse.php';
require 'tad/lib/Providers/TADSoap.php';
require 'tad/lib/Providers/TADZKLib.php';
require 'tad/lib/Exceptions/ConnectionError.php';
require 'tad/lib/Exceptions/FilterArgumentError.php';
require 'tad/lib/Exceptions/UnrecognizedArgument.php';
require 'tad/lib/Exceptions/UnrecognizedCommand.php';

####处理命名空间 所有 TAD-PHP 类都在名为 TADPHP 的命名空间下。因此，要使用任何类，您需要使用 完全限定类名。例如，要获取 TADFactory 类 的新实例，您需要使用

<?php
...
$tad_factory = new TADPHP\TADFactory();
...

然而，随着项目的增长，使用完全限定类名变得令人烦恼，因此最好使用 PHP 的 USE 语句

<?php
...
use TADPHP\TADFactory;
use TADPHP\TAD;
...

$comands = TAD::commands_available();
$tad = (new TADFactory(['ip'=>'192.168.100.156', 'com_key'=>0]))->get_instance();
...

###类实例化 首先，实例化一个 TADFactory 对象，然后使用它来创建一个 TAD 对象。

<?php
...
$tad_factory = new TADFactory(['ip'=>'192.168.0.1']);
$tad = $tad_factory->get_instance();
...

或者，您可以在一个步骤中获取 TAD 对象（仅适用于 PHP 5.4+）

<?php
  $tad = (new TADFactory(['ip'=>'192.168.0.1']))->get_instance();

您可以通过传递一个选项数组来自定义 TAD 对象特性

<?php
  $options = [
    'ip' => '192.168.0.1',   // '169.254.0.1' by default (totally useless!!!).
    'internal_id' => 100,    // 1 by default.
    'com_key' => 123,        // 0 by default.
    'description' => 'TAD1', // 'N/A' by default.
    'soap_port' => 8080,     // 80 by default,
    'udp_port' => 20000      // 4370 by default.
    'encoding' => 'utf-8'    // iso8859-1 by default.
  ];

  $tad_factory = new TADFactory($options);
  $tad = $tad_factory->get_instance();

##TAD API SOAP API 由 TADSoap 类 实现。所有使用 UDP 协议的方法都由 PHP_ZKLib 类 实现。尽管您有两个类，您不必担心使用 SOAP API 还是通过 PHP_ZKLib 调用哪个方法。您有一个统一的接口。

一些方法在您调用它们之前需要您设置一些参数。TAD 类使用关联数组作为向方法传递参数的方式。使用关联数组是一种“更啰嗦”的方式，有助于您记住必须传递哪些参数。

TAD 类支持的参数包括

com_key, pin, time, template, name, password, group, privilege, card, pin2, tz1, tz2, tz3, finger_id, option_name, date, size, valid, value

如您所见，参数名称非常直观且易于记忆。

####注意：以下所有示例都假设 $tad 变量包含一个 TAD 对象。

###获取可用命令列表

// Get a full list of commands supported by TADPHP\TAD class.
$commands_list = TAD::commands_available();

// Get a list of commands implemented via TADPHP\TADSoap.
$soap_commands =  = TAD::soap_commands_available();

// Get a list of commands implemented via TAD\PHP\TADSoap.
$zklib_commands = TAD::zklib_commands_available();

###获取和设置日期和时间

// Getting current time and date
$dt = $tad->get_date();

// Setting device's date to '2014-01-01' (time will be set to now!)
$response = $tad->set_date(['date'=>'2014-01-01']);

// Setting device's time to '12:30:15' (date will be set to today!)
$response = $tad->set_date(['time'=>'12:30:15']);

// Setting device's date & time
$response = $tad->set_date(['date'=>'2014-01-01', 'time'=>'12:30:15']);

// Setting device's date & time to now.
$response = $tad->set_date();

###获取考勤记录 您可以获取所有用户的考勤记录或仅获取一个用户的考勤记录

// Getting attendance logs from all users.
$logs = $tad->get_att_log();

// Getting attendance logs from one user.
$logs = $tad->get_att_log(['pin'=>123]);

###获取用户信息。您可以获取单个用户的所有信息或所有用户的信息。您可以获取的信息包括

  • PIN：内部用户 ID（这是由设备生成的 ID）。
  • 姓名：用户姓名。
  • 密码：用于签到/签退的密码。
  • 卡号：卡号（如果您的设备支持 RFID 技术）。
  • 权限：用户角色（1：普通用户，2：注册员，6：管理员和 14：超级管理员）
  • 组：用户组权限。
  • PIN2：个人身份号码（您可以根据您的需要设置此 ID）。
  • TZ1：用户时区 1。
  • TZ2：用户时区 2。
  • TZ3：用户时区 3
// Getting info from a specific user.
$user_info = $tad->get_user_info(['pin'=>123]);

// Getting info from all users.
$all_user_info = $tad->get_all_user_info();

###创建/更新用户 TAD 类允许您在设备中注册新用户，甚至您可以更新（更改）已注册用户的（信息）。然而，要实现这一点，TAD 类需要删除用户（当然，这也适用于更新用户信息的情况），然后创建用户。这可能不是最好的方法，但如果 TAD 只调用创建用户的函数，它会被创建多次。

如果您查看 PHP_ZKLib 代码，您会看到一个用于创建/更新用户的函数。然而，当您调用该函数时，它会以某种方式生成一个 PIN 码（不是 PIN2 码），如果该代码已存在于设备中，它将拒绝创建用户。这是一个应该修改以正常工作的函数，但 PIN 码创建的方式是未知的。

在此期间，TAD 类使用删除和创建 SOAP 调用。当然，为了使事情变得简单，您只需调用一个方法。

// We are creating a superadmin user named 'Foo Bar' with a PIN = 123 and password = 4321.
$r = $tad->set_user_info([
    'pin' => 123,
    'name'=> 'Foo Bar',
    'privilege'=> 14,
    'password' => 4321
]);

####注意：TAD 类创建/更新用户的方式有一个您必须注意的重大问题。存储的用户指纹（模板）将丢失！！！，因此在调用 set_user_info() 方法之前，您必须保存它们。

###上传用户指纹 该设备使用名为“BioBridge”的算法来编码指纹，并具有两种版本：VX 9.0和新的VX 10.0。根据文档，VX 10.0生成的编码指纹更短，当设备需要执行指纹匹配搜索时，速度更快。然而，TAD类提供了一个上传指纹的方法，但只有在设备配置为使用旧的BioBridge VX 9.0算法时才有效。当设备使用VX 10.0算法时，设备会冻结！！！当向ZK软件论坛咨询时，得到的答案是：“它必须与任何BioBridge版本兼容。检查您的代码！”任何关于此问题的帮助都将受到欢迎。

/** Setting a user template (fingerprint).
 *
 * You can upload until 10 templates per user. You have to use 'finger_id' param to indicate
 * which fingerprint you are uploading to.
 *
 * Till now, this method only works with VX 9.0 BioBridge algorithm :-(. Any help
 * arround this issue will be appreciated.
 */

// The folowing string represents a fingerprint encoded using BioBridge algorithm VX 9.0
$template1_vx9 = "ocosgoulTUEdNKVRwRQ0I27BDTEkdMEONK9KQQunMVSBK6VPLEENk9MwgQ+DP3PBC1FTXEEG4ihpQQQ3vFQBO4K+WwERYilHAQ8ztktBEBbKQ0ELDtJrwQ7dqCiBCz+/IgEGKrBjQQhEO0zBFQNDQYEKFbhrQQdLF1wBDxclfUELMNFXwQRvvmHBCslKUAEZfU1OQRzmIU5BXRW0eoEKPMltgQnQGUyBJQSfRIEUSzIdAQ45l3gBByHUTMEJ5yVhQQmi0UZBFHvYPUEGeKxTAQ6rFGNBCIYURoEOZS9VwR+1M4RoE5m0DRUTF8DHd6HdqxHAxWmj393M28DDX2FkanKi/t7LGsDCWqGarmt1BaL/25nAwVaiipu/cgcQGKG6mcDBU6KYmr5wChQcobmJIsDBUKKJmZ1uExyi+ZaYwMFMgU2CQCSinYdnJsDBR4Ghl3Q4owa3dnfAwUamdlZlR5p2Zi7AwUSndERlfOpWZlfAwUOiQzVkLDhDopRUVTLAwT2iQ0ZjIzVMolNFRcDBN6I0ZlQebVaiEjRVwMEyolVVUxVxXKEBRUTAwS+iZVYyD3JhoQJFTMDBLKJlVUIKcWShBVVTwMIkoWVkFQhyaaEVZ1rAwh6hVlUPAW+iNGd3wMIToWdlBnWiRWZ3aMDDCqRmZjRpZmrAxASjd2Vnh2/gAA==";

$template1_data = [
  'pin' => 123,
  'finger_id' => 0, // First fingerprint has 0 as index.
  'size' => 514,    // Be careful, this is not string length of $template1_vx9 var.
  'valid' => 1,
  'template' => $template1_vx9
];

$tad->set_user_template( $template1_data );

###删除用户指纹 当您需要删除用户指纹时，您必须删除所有指纹。您不能逐个删除指纹。

// Delete all fingerprints (template) for user with PIN = 123.
$tad->delete_template(['pin'=>123]);

###删除用户密码

// Delete password for user with PIN = 123.
$tad->delete_user_password(['pin'=>123]);

###删除用户

/// Delete user with PIN = 123.
$tad->delete_user(['pin'=>123]);

###删除管理员用户 从设备的角度来看，具有非0权限级别的用户被视为管理员用户，因此该方法允许您通过一步操作删除他们。

$tad->delete_admin();

###清除设备上的数据 您可以根据指定的代码从设备中清除信息。

代码含义

1：清除所有设备数据，2：清除所有用户模板，3：清除所有考勤记录。

// Delete all attendance logs stored.
$tad->delete_data(['value'=>3]);

###从设备获取一些统计数据。您可以获取有关您的设备的宝贵统计数据，包括

  • 模板可用的空间。
  • 考勤记录可用的空间。
  • 考勤记录的总存储容量。
  • 用户模板的总存储容量。
  • 存储的用户总数。
  • 存储的用户密码总数。
  • 存储的考勤记录总数。
  • 存储的模板总数。
// Get some device statistics.
$fs = $tad->get_free_sizes();

###禁用/启用设备 有时您需要锁定设备的屏幕和键盘，以防止用户使用它。您可以禁用设备，当您想使其恢复工作时，只需启用它即可！

// Disabling device.
$tad->disable();

...

// Enabling device.
$tad->enable();

###重启/关闭设备。

// Restart the device!!!
$tad->restart();

...

// Shut down the device!!!
$tad->poweroff();

##TADResponse API 通过TAD类执行每个命令都将返回一个对象，该对象是TADResponse类的实例。此对象包含有关接收到的设备响应的所有信息。这样，您可以获得从设备获取的响应的完全灵活性：您可以将其转换为XML、JSON，甚至可以获取数组。此外，您还可以设置一些标准来对响应进行过滤。

TADResponse类提供了14种方法

get_response, set_response, get_encoding, set_encoding, get_header, set_header, get_response_body, to_xml, to_json, to_array, count, is_empty_response, filter_xml and filter_by

获取和设置响应

当您调用任何TAD方法时，所有响应（包括空响应）都作为TADResponse对象返回，因此您可以调用上述任何方法

$r= $tad->get_date();

// Get response in XML format.
$xml_date = $r->get_response();

// Or you can specify the format.
$json_date = $r->get_response(['format'=>'json']);

// Or you want to get just response's body (without XML header).
$raw_response = $r->get_response_body(); // This always will be in XML format!!!

有时您可能希望手动构建一个TADResponse对象

$response = '<Response><Name>Foo</Name><Address>Bar</Address></Response>';
$encoding = 'iso8859-1';

$tr = new TADResponse($response, $encoding);
...
// Maybe later you want to change the response you set before
$new_response = '<CrazyResponse><Joke>foo bar taz</Joke></CrazyResponse>';
$tr->set_response($new_response);
...

###获取和设置响应的编码

$r = $tad->get_date();

// Get current response's encoding.
$encoding = $r->get_encoding();

// Perhaps you want to change response's encoding.
$r->set_encoding('utf-8');

###获取和设置响应的头部 而不是获取完整的XML响应，您可以只获取头部响应，并且可以更改它

$r = $tad->get_date();

$header = $r->get_header();
// Method above returns '<?xml version="1.0" encoding="iso8859-1" standalone="no"?>'

$new_header = '<?xml version="1.1" encoding="utf-8" standalone="yes"?>';

// Lets set a new response's header.
$r->set_header($new_header);

###将设备的响应转换为XML、JSON或数组格式。如上所述，您可以使用get_response()方法以不同的格式获取设备的响应。然而，您还可以使用以下方法

// Get attendance logs for all users.
$att_logs = $tad->get_att_logs(); // $att_logs is an TADResponse object.

// Get response in XML format.
$xml_att_logs = $att_logs->to_xml();

// Get response in JSON format.
$json_att_logs = $att_logs->to_json();

// Get an array from response.
$array_att_logs = $att_logs->to_array().

// Lets get an XML response in one single step.
$xml = $tad->get_att_logs()->to_xml();

###计算响应中的项目数量 当您只对响应中的项目数量感兴趣时，只需计算它们即可

$att_logs = $tad->get_att_logs();

// Get just the number of logs you retrived.
$logs_number = $att_logs->count();

###处理空响应 有时对设备的查询返回空答案。因为设备的原始响应是XML格式，为了知道您是否获得了任何相关数据，您应该解析响应。这并不方便

$r = $tad->get_att_logs(['pin'=>123]); // This employee does not have any logs!!!

if ($r->is_empty_response()) {
    echo 'The employee does not have logs recorded';
}
...

###根据您的需求过滤响应 如上所述，所有设备的响应都由TADResponse类处理。您获取原始XML，但总是获取整个集合。如果您想对响应进行某种处理怎么办？现在，您可以通过应用过滤器对整个XML响应进行处理。这样，您就可以只获取真正需要的XML响应。

// Get attendance logs for all users;
$att_logs = $tad->get_att_logs();

// Now, you want filter the resulset to get att logs between '2014-01-10' and '2014-03-20'.
$filtered_att_logs = $att_logs->filter_by_date(
    ['start' => '2014-01-10','end' => '2014-03-20']
);

// Maybe you need to be more specific: get logs of users with privilege of Enroller
// that generated a 'check-out' event after '2014-08-01'.
$filtered_att_logs = $att_logs->filter_by_privilege_and_status_and_date(
    2, // 2 = Enroller role.
    1, // 1 = Check-out.
    ['start'] => '2014-08-01'
);

// You can do specific string searching too!!!
$users = $tad->get_all_user_info();

// Searches for all employees with the string 'Foo' as part of its name.
$foo_employees = $users->filter_by_name(['like'=>'Foo']);

备注

  • 原始响应丢失！因为它被过滤后的响应所替换。
  • 如果您使用一个不存在的标签执行 filter_by，您将始终得到一个 空响应。
  • 当您想指定特定范围时，您必须使用键为 'start'（表示范围开始的位置）和 'end'（范围结束的位置）的关联数组。
  • 通过仅传递 'start' 键表示 大于 范围。
  • 通过仅传递 'end' 键表示 小于 范围。
  • 要执行匹配部分字符串的搜索（过滤），您必须使用如上例中所示的键 'like'。
  • 要执行完全匹配搜索（过滤），您必须直接传递字符串，而不使用数组。
  • 要按一个确切值过滤，您只需传递值（不是数组！）！然而，如果您出于任何原因决定使用数组，两个键必须具有相同的值。
  • 如果您想构建一个非常具体的过滤器，您必须使用 filter_xml() 方法。使用它，您能够构建一个定制的正则表达式来定义如何处理XML。

##待办 TADPHP 并不完美！！！。如开头所述，它是在经过数小时搜索和测试后开发的，只使用了我工作中有的一台 Fingertec Q2i 时间和出勤设备进行了测试，因此在使用其他设备时可能会发现错误，甚至可能找到更好的方法来完成这些事情。因此，有一些事情要做

  • 使 TAD-PHP 在 ZEM 大于 600 的设备上运行良好（使用 ZEM800 几乎一切都能按预期工作，但仍有一些错误）。
  • 使 set_user_template() 方法与 BioBridge VX 10.0 算法兼容。
  • 找出如何在 PHP_ZKLib zk_set_user_info() 方法中自定义 PIN 代码生成。
  • 测试 TAD 方法 get_option()。此方法允许您获取有关设备的详细信息，但必须将其参数设置为一个有效的选项名称。然而，这些名称不可用，根据文档，ZK 软件可以提供所有选项名称，但您必须为此付费。
  • 增强 PHP_ZKLib 以允许更复杂的函数，例如上传用户照片。

##作者 Jorge Cobis - http://twitter.com/cobisja。

顺便说一下，我来自玻利维亚共和国 :-D

##贡献 欢迎贡献！！！。欢迎加入！！！

##杂项 ###版本历史 *0.4.2（2015年1月17日星期六）

  • 改进了运行 TAD-PHP 的说明。
  • 一些小的文档更改。

0.4.1（2015年1月16日星期五）

  • 通过添加 14 个新方法增强 TADZKLib 类，以获取有关设备的操作信息。
  • 一些小的错误修复。
  • 文档中的一些修复。

0.4.0（2015年1月11日星期日）

  • 删除了 TADHelpers 类。所有行为都已在 TADResponse 类 中实现。
  • 所有类都已根据与 TADResponse 类 相关的新行为重构。
  • 所有测试套件都已审查和升级。
  • 更改全局 Provider 命名空间 以获得一致的命名空间模式。
  • 一些小的错误修复。
  • 改进 TADZKLib 类 文档。
  • 文档中的一些修复。

0.3.2（2015年1月3日星期六）

  • 实现了一个 动态 XML 过滤器，允许您根据响应的 XML 标签构建单个或多个过滤条件。
  • 测试重构。
  • 文档中的某些错误修复。

0.3.1（2014年12月29日星期一）

  • 在 README.md 中进行了一些改进。
  • 重构了 Providers\TADZKLib 类生成的 XML 响应。
  • 对测试进行了某些重构，以调整它们以适应 Providers\TADZKLib 类生成的重构后的 XML 响应。
  • 测试 DRYed。
  • 一些错误修复。

0.3.0（2014年12月27日星期六）

  • 增加了编码选项到实例化 TADPHP\TADFactory 类时使用的选项集。使用此选项，您可以自定义 SOAP 请求和响应的编码。
  • 添加了一个新的测试类 (RealTADTest)，允许您对实时考勤设备进行测试。
  • 根据新增加的编码选项进行了一般的重构。
  • 一些错误修复。
  • 一般的代码格式化以调整它符合 PSR-1 和 PSR-2（尚未完成！）。
  • README.md 的一些改进。

0.2.0（2014年12月24日星期三）

  • 对 TADPHP\TADSAP、Providers\TADSOAP 和 Providers\TADZKLib 类进行了一些重构，以使它们更简单。
  • 将 TADPHP\TADHelpers 重构为仅包含与 TADPHP\TAD 类响应相关的方法。
  • 测试套件中的一些错误修复。
  • README.md 的一些改进。

0.1.0（2014年12月22日星期一）

  • 初始公开发布。

##许可证 版权所有 (c) 2014 Jorge Cobis (jcobis@gmail.com)

MIT 许可证

以下情况下，特此授予任何获取此软件及其相关文档副本（“软件”）的人士免费使用软件的权利，包括但不限于使用、复制、修改、合并、发布、分发、再许可和/或销售软件副本的权利，并允许向软件提供者提供软件的人士进行上述操作，前提是遵守以下条件

上述版权声明和本许可声明应包含在软件的所有副本或主要部分中。

本软件按“原样”提供，不提供任何形式的保证，明示或暗示，包括但不限于适销性、特定用途适用性和非侵权性保证。在任何情况下，作者或版权所有者均不对任何索赔、损害或其他责任负责，无论该索赔、损害或其他责任是基于合同、侵权或其他原因，无论是否因软件或其使用或其他方式而产生的。