Cleanup project and improve error handling

This commit looks bigger than it is. Most of the changes are cosmetic,
although the function body has changed to better simulate the error
conditions and messages of the built-in function found in PHP >=5.5.

Other changes are listed below:
 - Add LICENSE.md file
 - Update phpunit development dependency
 - Update tests to check for proper error handling
 - Update tests to check for the conditions of PR #1
 - Add docblocks compatible with the built-in function
 - Minor changes to git and travis configurations

.gitattributes

@@ -0,0 +1,5 @@
+/tests              export-ignore
+/.gitattributes     export-ignore
+/.gitignore         export-ignore
+/.travis.yml        export-ignore
+/phpunit.xml.dist   export-ignore

.gitignore

@@ -1,3 +1,4 @@
+build/
 nbproject/
 vendor/
 composer.lock

.travis.yml

@@ -3,10 +3,13 @@ php:
   - 5.3
   - 5.4
   - 5.5
+# This triggers builds to run on the new TravisCI infrastructure.
+# See: http://docs.travis-ci.com/user/workers/container-based-infrastructure/
+sudo: false
 before_install:
-  - composer self-update --no-interaction --ansi
+  - travis_retry composer self-update
   - composer config notify-on-install false
 install:
-  - composer install --dev --no-progress --no-interaction --ansi --prefer-source
+  - travis_retry composer install --no-interaction --prefer-source
 script:
-  - vendor/bin/phpunit --configuration phpunit.dist.xml
+  - vendor/bin/phpunit

LICENSE.md

@@ -0,0 +1,21 @@
+# The MIT License (MIT)
+
+Copyright (c) 2015 Ryan Chouinard <rchouinard@gmail.com>
+
+> Permission is hereby granted, free of charge, to any person obtaining a copy
+> of this software and associated documentation files (the "Software"), to deal
+> in the Software without restriction, including without limitation the rights
+> to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+> copies of the Software, and to permit persons to whom the Software is
+> furnished to do so, subject to the following conditions:
+>
+> The above copyright notice and this permission notice shall be included in
+> all copies or substantial portions of the Software.
+>
+> THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+> IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+> FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+> AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+> LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+> OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+> THE SOFTWARE.

composer.json

@@ -11,13 +11,16 @@
     ],
     "minimum-stability": "stable",
     "require": {
-        "php": ">=5.3",
+        "php": ">=5.3.3",
         "ext-hash": "*"
     },
     "require-dev": {
-        "phpunit/phpunit": "3.7.*"
+        "phpunit/phpunit": "^4.8"
     },
     "autoload": {
         "files": ["src/hash_pbkdf2_compat.php"]
+    },
+    "scripts": {
+        "test": "phpunit"
     }
 }

phpunit.xml.dist

@@ -0,0 +1,20 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<phpunit bootstrap="vendor/autoload.php" verbose="true" colors="true">
+    <testsuites>
+        <testsuite name="hash_pbkdf2-compat Test Suite">
+            <directory>tests/</directory>
+        </testsuite>
+    </testsuites>
+    <filter>
+        <whitelist>
+            <directory suffix=".php">src/</directory>
+        </whitelist>
+    </filter>
+    <logging>
+        <log type="tap" target="build/report.tap" />
+        <log type="junit" target="build/report.junit.xml" />
+        <log type="coverage-html" target="build/coverage" charset="UTF-8" yui="true" highlight="true" />
+        <log type="coverage-text" target="build/coverage.txt" />
+        <log type="coverage-clover" target="build/logs/clover.xml" />
+    </logging>
+</phpunit>

src/hash_pbkdf2.php

@@ -1,42 +1,77 @@
 <?php
+/**
+ * This file is part of Rych\hash_pbkdf2-compat
+ *
+ * (c) Ryan Chouinard <rchouinard@gmail.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
 
 namespace Rych;
 
-function hash_pbkdf2($algo, $password, $salt, $iterations, $length = 0, $raw_output = false)
-{
-    // Prep input arguments
-    $algo       = (string)  isset($algo) ? $algo : null;
-    $password   = (string)  isset($password) ? $password : null;
-    $salt       = (string)  isset($salt) ? $salt : null;
-    $iterations = (integer) isset($iterations) ? $iterations : null;
-    $length     = (integer) $length;
-    $raw_output = (boolean) $raw_output;
-
+/**
+ * @param   string  $algo       Name of selected hashing algorithm (i.e. md5,
+ *                              sha256, haval160,4, etc..) See hash_algos() for
+ *                              a list of supported algorithms.
+ * @param   string  $password   The password to use for the derivation.
+ * @param   string  $salt       The salt to use for the derivation. This value
+ *                              should be generated randomly.
+ * @param   integer $iterations The number of internal iterations to perform for
+ *                              the derivation.
+ * @param   integer $length     The length of the output string. If raw_output
+ *                              is TRUE this corresponds to the byte-length of
+ *                              the derived key, if raw_output is FALSE this
+ *                              corresponds to twice the byte-length of the
+ *                              derived key (as every byte of the key is
+ *                              returned as two hexits).
+ *                              
+ *                              If 0 is passed, the entire output of the
+ *                              supplied algorithm is used.
+ * @param   boolean $raw_output When set to TRUE, outputs raw binary data.
+ *                              FALSE outputs lowercase hexits.
+ * @return  string              Returns a string containing the derived key as
+ *                              lowercase hexits unless raw_output is set to
+ *                              TRUE in which case the raw binary representation
+ *                              of the derived key is returned.
+ */
+function hash_pbkdf2($algo = null, $password = null, $salt = null, $iterations = null, $length = 0, $raw_output = false)
+{    
     // Recreate \hash_pbkdf2() error conditions
     $num_args = func_num_args();
     if ($num_args < 4) {
-        trigger_error(sprintf('\%s() expects at least 4 parameters, %d given', __FUNCTION__, $num_args), E_USER_WARNING);
+        trigger_error(sprintf('%s() expects at least 4 parameters, %d given', __FUNCTION__, $num_args), E_USER_WARNING);
         return null;
     }
 
     if (!in_array($algo, hash_algos())) {
-        trigger_error(sprintf('Unknown hashing algorithm: %s', $algo), E_USER_WARNING);
+        trigger_error(sprintf('%s(): Unknown hashing algorithm: %s', __FUNCTION__, $algo), E_USER_WARNING);
         return false;
     }
 
+    if (!is_integer($iterations)) {
+        trigger_error(sprintf('%s() expects parameter 4 to be long, %s given', __FUNCTION__, gettype($iterations)), E_USER_WARNING);
+        return null;
+    }
+
     if ($iterations <= 0) {
-        trigger_error(sprintf('Iterations must be a positive integer: %d', $iterations), E_USER_WARNING);
+        trigger_error(sprintf('%s(): Iterations must be a positive integer: %d', __FUNCTION__, $iterations), E_USER_WARNING);
         return false;
     }
 
+    if (!is_integer($length)) {
+        trigger_error(sprintf('%s() expects parameter 5 to be long, %s given', __FUNCTION__, gettype($length)), E_USER_WARNING);
+        return null;
+    }
+
     if ($length < 0) {
-        trigger_error(sprintf('Length must be greater than or equal to 0: %d', $length), E_USER_WARNING);
+        trigger_error(sprintf('%s(): Length must be greater than or equal to 0: %d', __FUNCTION__,  $length), E_USER_WARNING);
         return false;
     }
 
     $salt_len = strlen($salt);
     if ($salt_len > PHP_INT_MAX - 4) {
-        trigger_error(sprintf('Supplied salt is too long, max of PHP_INT_MAX - 4 bytes: %d supplied', $salt_len), E_USER_WARNING);
+        trigger_error(sprintf('%s(): Supplied salt is too long, max of PHP_INT_MAX - 4 bytes: %d supplied', __FUNCTION__, $salt_len), E_USER_WARNING);
         return false;
     }
 
@@ -62,4 +97,3 @@ function hash_pbkdf2($algo, $password, $salt, $iterations, $length = 0, $raw_out
     // of that decision, but it's emulated here for full compatibility.
     return substr(($raw_output) ? $output : bin2hex($output), 0, $length);
 }
-

src/hash_pbkdf2_compat.php

@@ -1,11 +1,47 @@
 <?php
+/**
+ * This file is part of Rych\hash_pbkdf2-compat
+ *
+ * (c) Ryan Chouinard <rchouinard@gmail.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
 
+// @codeCoverageIgnoreStart
 require __DIR__ . '/hash_pbkdf2.php';
 
 if (!function_exists('\hash_pbkdf2')) {
-    function hash_pbkdf2($algo, $password, $salt, $iterations, $length = 0, $raw_output = false)
-    {
-        return \Rych\hash_pbkdf2($algo, $password, $salt, $iterations, $length, $raw_output);
-    }
+
+/**
+ * @param   string  $algo       Name of selected hashing algorithm (i.e. md5,
+ *                              sha256, haval160,4, etc..) See hash_algos() for
+ *                              a list of supported algorithms.
+ * @param   string  $password   The password to use for the derivation.
+ * @param   string  $salt       The salt to use for the derivation. This value
+ *                              should be generated randomly.
+ * @param   integer $iterations The number of internal iterations to perform for
+ *                              the derivation.
+ * @param   integer $length     The length of the output string. If raw_output
+ *                              is TRUE this corresponds to the byte-length of
+ *                              the derived key, if raw_output is FALSE this
+ *                              corresponds to twice the byte-length of the
+ *                              derived key (as every byte of the key is
+ *                              returned as two hexits).
+ *                              
+ *                              If 0 is passed, the entire output of the
+ *                              supplied algorithm is used.
+ * @param   boolean $raw_output When set to TRUE, outputs raw binary data.
+ *                              FALSE outputs lowercase hexits.
+ * @return  string              Returns a string containing the derived key as
+ *                              lowercase hexits unless raw_output is set to
+ *                              TRUE in which case the raw binary representation
+ *                              of the derived key is returned.
+ */
+function hash_pbkdf2($algo = null, $password = null, $salt = null, $iterations = null, $length = 0, $raw_output = false)
+{
+    return \Rych\hash_pbkdf2($algo, $password, $salt, $iterations, $length, $raw_output);
 }
 
+}
+// @codeCoverageIgnoreEnd