metalback/tad-php

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

维护者

详情

github.com/metalback/tad-php

源代码

安装次数： 7,458

依赖: 1

建议者: 0

安全性: 0

星级: 1

关注者: 3

分支: 159

0.4.2 2015-01-17 17:37 UTC

Requires

  • php: >=5.3.0

Requires (Dev)

MIT f7108b76e0583131c716e8614a31f63999876229

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

timeattendanceZKtad

This package is auto-updated.

Last update: 2024-09-29 05:02:31 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标准编写代码，它可以避免您处理与加载类相关的一切问题。

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

  1. 安装Composer

    curl -s https://getcomposer.org/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 Software 可以提供所有选项名称，但你必须付费。
  • 增强 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 响应。
  • 测试实现了DRY（Don't Repeat Yourself）原则。
  • 一些错误修复。

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 许可证

特此授予任何获得本软件及其相关文档文件（“软件”）副本的任何人，在不受限制的情况下处理软件的权利，包括但不限于使用、复制、修改、合并、发布、分发、再许可和/或出售软件副本的权利，并允许向软件提供的人这样做，前提是遵守以下条件

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

软件按“原样”提供，不提供任何明示或暗示的保证，包括但不限于适销性、针对特定目的的适用性和非侵权性保证。在任何情况下，作者或版权所有者均不对任何索赔、损害或其他责任承担责任，无论是否因合同、侵权或其他行为而产生，无论是否与软件或其使用或其他交易有关。