Merge branch 'develop'

README.md

@@ -28,12 +28,86 @@ For practical purposes, you don't have to be worried about when to use TAD class
 * All ZK Time & Attendance devices with web server built-in (with ZEM600 or less).
 
 ##Getting started
+###Setting up the environment
+After download TAD-PHP, you have 2 ways to get your enviroment configured to use the classes:
+
+####Composer
+
+[Composer](https://getcomposer.org) is the PHP's package manager and is the recommended way to get packages for your projects. It's also able to build automatically ***autoloaders*** if you wrote down your code using PSR-0 and/or PSR-4 standards, avoiding you headaches about everything related to loading classes.
+
+**TADPHP** is built follows PSR-4 standard and comes with a specific file named **composer.json** that allows **Composer** to generate a file named **autoload.php** (beside others files of course). This files generated is the only one you need to include in your project to get all classes required by TADPHP loaded in memory:
+
+1. Install Composer:
+	```
+    curl -s https://getcomposer.org/installer | php
+
+	```
+
+2. Get inside TADPHP root folder and generate the **autoload.php** file:
+	```
+    php composer.phar dump-autoload
+    ```
+    The command above will generate a folder called **vendor**. Inside of it, you'll see the **autoload.php**
+
+3. Require/Include **autoload.php** file in the **index.php** of your project or whatever file you need to use **TAD-PHP** classes:
+	```php
+    <?php
+    require 'vendor/autoload.php';
+    ...
+
+    ```
+
+####Loading TAD-PHP classes by hand
+Even if Composer it's the preferred method to generate the files needed to get all classes loaded, maybe you want to do the task by hand:
+
+1. Copy and paste TAD-PHP folder in your project root.
+2. Rename TAD-PHP folder to use a shorter name (for example 'tad').
+3. Require/Include all classes required by TAD-PHP using the relative TAD-PHP path
+	```php
+    <?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';
+    ```
+
+####Handling namespaces
+All TAD-PHP classes are under the namespace named **TADPHP**. So, to use any class you need to use the **Fully qualified class name**. For example, to get a new instance of **TADFactory class** you need to use:
+
+```php
+<?php
+...
+$tad_factory = new TADPHP\TADFactory();
+...
+```
+
+However, as your project grows up using fully qualified class names becomes annoying, so it's better to use PHP **USE** sentence:
+
+```php
+<?php
+...
+use TADPHP\TADFactory;
+use TADPHP\TAD;
+...
+
+$comands = TAD::commands_available();
+$tad = (new TADFactory(['ip'=>'192.168.100.156', 'com_key'=>0]))->get_instance();
+...
+```
+
 ###Class instantiation
 First, instantiate a TADFactory object, then use it to create a TAD object.
 ```php
 <?php
-  $tad_factory = new TADFactory(['ip'=>'192.168.0.1']);
-  $tad = $tad_factory->get_instance();
+...
+$tad_factory = new TADFactory(['ip'=>'192.168.0.1']);
+$tad = $tad_factory->get_instance();
+...
 ```
 Or you can get a TAD object in one single step (valid only in PHP 5.4+):
 ```php
@@ -407,6 +481,11 @@ Feel free to contribute!!!. Welcome aboard!!!
 
 ##Misc
 ###Version history
+***0.4.2** (Saturday, 17th January 2015)
+
+* Improved directions to get TAD-PHP running.
+* Some minor documentation changes.
+
 **0.4.1** (Friday, 16th January 2015)
 
 * Enhanced **TADZKLib class** by adding 14 new methods to get operating information about the device.

lib/Providers/TADSoap.php

@@ -29,17 +29,17 @@
 
 use TADPHP\TADResponse;
 
-
+/**
+ * TADSoap: class that allows to interact with a Time & Attendance device using SOAP.
+ */
 class TADSoap
 {
     const XML_FAIL_RESPONSE = 'Fail!';
     const XML_SUCCESS_RESPONSE = 'Succeed!';
     const SOAP_VERSION = SOAP_1_1;
 
     /**
-     * SOAP commands array supported by the class.
-     *
-     * @var array
+     * @var array SOAP commands array supported by the class.
      */
     static private $soap_commands_available = [
         'get_date'            => '<GetDate><ArgComKey>%com_key%</ArgComKey></GetDate>',
@@ -59,16 +59,12 @@ class TADSoap
     ];
 
     /**
-     * Holds a <code>\SoapClient</code> instance.
-     *
-     * @var object
+     * @var SOAPClient Holds a <code>\SoapClient</code> instance.
      */
     private $soap_client;
 
     /**
-     * Options array required by <code>SoapClient</code> class.
-     *
-     * @var array
+     * @var array Options array required by <code>SoapClient</code> class.
      */
     private $soap_client_options;
 
@@ -212,6 +208,13 @@ function($item) {
         return $parsed_command;
     }
 
+    /**
+     * Build an XML header.
+     *
+     * @param string $xml XML string which header will be added to.
+     * @param string $encoding encoding
+     * @return string full XML string (Header + Body).
+     */
     public static function normalize_xml_string($xml, $encoding = 'utf-8')
     {
         $xml ='<?xml version="1.0" encoding="' . $encoding . '" standalone="no"?>' . $xml;

lib/Providers/TADZKLib.php

@@ -73,15 +73,39 @@ class TADZKLib
     const XML_FAIL_RESPONSE    = 'Fail!';
     const XML_SUCCESS_RESPONSE = 'Successfully!';
 
+    /**
+     * @var string Device's ip address.
+     */
     private $ip;
+
+    /**
+     * @var int Device's UDP port.
+     */
     private $port;
+
+    /**
+     * @var TADZKlib holds a class instance.
+     */
     private $zkclient;
 
+    /**
+     * @var string device's response (low level format).
+     */
     private $data_recv = '';
+
+    /**
+     * @var int session id associated to UDP transaction.
+     */
     private $session_id = 0;
 
+    /**
+     * @var boolean tells if result was successfully (<code>true</code>) or fail (<code>false</code>).
+     */
     private $result;
 
+    /**
+     * @var array commands set supported by <code>TADZKLib</code> class.
+     */
     static private $zklib_commands = [
         'get_platform' => [
             'command_id' => self::CMD_DEVICE,

lib/TAD.php

@@ -37,7 +37,7 @@
  * TAD: Time & Attendance Device is a class that implements some function presents in time and attendance device.
  *
  *
- * For developing purposes, it' been used Fingertec Q2i device (that it's been using were I work).
+ * For developing purposes, it's been used Fingertec Q2i device (that it's been using were I work).
  *
  * Methods exposed by TAD class have been tested using Q2i deviced only , that has a Linux 2.6.21 kernel (ZEM-600).
  * However, it's possible that TAD class works with similar devices, since most of them use the same SOAP API from
@@ -52,7 +52,7 @@
  * PHP_ZKLib class it's been fully integrated, after a refactoring process to take out all duplicated code (DRY)
  *
  * TAD Class has been tested as far as I could. If you check the test code coverage you'll notice that it does not
- * reach 100%. The reason is that it was not possible to write test fot PHP_ZKLib class. I have to admit that
+ * reach 100%. The reason is that it was not possible to write some tests fof PHP_ZKLib class. I have to admit that
  * I not have fully understanding about what it's done by some methods. I could not find technical information
  * about UDP protocol for ZK devices.
  *
@@ -62,6 +62,12 @@
  *
  * To get a TAD instance, call <code><b>get_instance()</b></code> method from <code><b>TADFactory</b></code> class.
  *
+ * Please note that all device's responses are handled by TAD through <b><code>TADResponse</code></b> class. For
+ * that reason all responses are returned embedded in <code>TADResponse</code> object.
+ *
+ * You can get responses in XML, JSON or Array using the respective methods exposed by <code>TADResponse</code> class.
+ * (<code>to_xml(), to_json(), to_array(), get_reponse()</code>)
+ *
  * Some examples:
  *
  * - Get a TAD instance for device with ip = '192.168.100.156':
@@ -79,36 +85,20 @@
  * $r = $b1->set_date(['date'=>'2014-12-31', 'time'=>'23:59:59']); // method executed via PHP_ZKLib.
  * </code>
  *
- * All device responses are in XML format. When you need to get them in a different format you can use
- * some utilitites (helpers) methods exposed by TAD class:
- *
- * Some examples:
+ * All device responses are <code>TADResponse</code> objects. You can transform them as shown below:
  *
  * Get an array with logs of user with pin = 99999999:
  * <code>
- * $logs = TADHelpers::xml_to_array($b1->get_att_log(['pin'=>'99999999']);
+ * $logs = $b1->get_att_log(['pin'=>'99999999'])->to_array();
  * </code>
  *
  * If you want to filter logs by date:
  * <code>
  * $logs = $b1->get_att_log(['pin'=>'99999999']);
- * $logs = TADHelpers::filter_xml_by_date($logs, ['start_date'=>'2014-11-27', 'end_date'=>'2014-12-02']);
+ * $logs = $logs->filter_by_date(['start_date'=>'2014-11-27', 'end_date'=>'2014-12-02']);
  * </code>
  *
- * To get wich commands are available to run via TADSoap class and wich ones are run via PHP_ZKLib you have the
- * following 2 static methods <code><b>soap_commands_available</b></code> and
- * <code><b>zklib_commands_available</b></code>
- *
- * TAD class Limitations:
- *
- * <li>
- * <code>set_user_template</code> method only works using BioBridge VX 9.0 algorithm (with VX 10, the device freezes!!!)
- * </li>.
- * <li><code>set_user_info</code> methos works properly only if the user you create don't exist previously</li>.
- * <li>
- * If you want to edit user info, you have to delete the user first, then you have to create it using
- * <code>set_user_info</code>.
- * </li>
+ * For more information see README.md
  *
  * @author Jorge Cobis - email: [email protected] / twitter: @cobisja
  */