Merge af7d314 into 54177af

.coveralls.yml

@@ -0,0 +1,3 @@
+service_name: travis-ci
+coverage_clover: clover.xml
+json_path: coveralls-upload.json

.gitattributes

@@ -0,0 +1,13 @@
+# Enforce Unix newlines
+* text=lf
+
+# Exclude unused files
+# see: https://redd.it/2jzp6k
+/tests              export-ignore
+/.github            export-ignore
+/.gitattributes     export-ignore
+/.gitignore         export-ignore
+/.*.yml             export-ignore
+/phpcs.xml          export-ignore
+/phpunit.xml.dist   export-ignore
+/README.md          export-ignore

.github/CODEOWNERS

@@ -0,0 +1 @@
+* @traderinteractive/opensource

.github/CONTRIBUTING.md

@@ -0,0 +1,24 @@
+# Contribution Guidelines
+We welcome you to report [issues](/../../issues) or submit [pull requests](/../../pulls).  While the below guidelines are necessary to get code merged, you can
+submit pull requests that do not adhere to them and we will try to take care of them in our spare time.  We are a smallish group of developers,
+though, so if you can make sure the build is passing 100%, that would be very useful.
+
+We recommend including details of your particular usecase(s) with any issues or pull requests.  We love to hear how our libraries are being used
+and we can get things merged in quicker when we understand its expected usage.
+
+## Pull Requests
+Code changes should be sent through [GitHub Pull Requests](/../../pulls).  Before submitting the pull request, make sure that phpunit reports success
+by running:
+```sh
+./vendor/bin/phpunit
+```
+And there are not coding standard violations by running
+```sh
+./vendor/bin/phpcs
+```
+
+## Builds
+Our [Travis build](https://travis-ci.org/traderinteractive/filter-ints-php) executes [PHPUnit](http://www.phpunit.de) and uses [Coveralls](https://coveralls.io/) to enforce code coverage.
+While the build does not strictly enforce 100% code coverage, it will not allow coverage to drop below its current percentage.
+[Scrutinizer](https://scrutinizer-ci.com/) is used to ensure code quality and enforce the [coding standard](http://www.php-fig.org/psr/psr-2/).
+

.github/ISSUE_TEMPLATE.md

@@ -0,0 +1,6 @@
+## Expected Behavior
+
+## Actual Behavior
+
+## Steps to reproduce the behavior
+

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,9 @@
+Fixes # .
+
+#### What does this PR do?
+
+#### Checklist
+- [  ] Pull request contains a clear definition of changes
+- [  ] Tests (either unit, integration, or acceptance) written and passing
+- [  ] Relevant documentation produced and/or updated
+

.gitignore

@@ -0,0 +1,5 @@
+/coverage/
+/vendor/
+/clover.xml
+phpunit.xml
+composer.lock

.scrutinizer.yml

@@ -0,0 +1,22 @@
+filter:
+    excluded_paths:
+        - 'vendor/*'
+before_commands:
+    - 'composer install'
+tools:
+    php_analyzer: true
+    php_mess_detector: true
+    php_code_sniffer:
+        config:
+            standard: PSR2
+    sensiolabs_security_checker: true
+    php_loc:
+        excluded_dirs:
+            - vendor
+    php_pdepend: true
+    php_sim: true
+build_failure_conditions:
+    - 'elements.rating(< A).exists'
+    - 'issues.label("coding-style").exists'
+    - 'issues.severity(>= MAJOR).exists'
+    - 'project.metric("scrutinizer.quality", < 9)'

.travis.yml

@@ -0,0 +1,18 @@
+sudo: false
+language: php
+php:
+  - 7.0
+  - 7.1
+  - 7.2
+  - nightly
+env:
+  - PREFER_LOWEST="--prefer-lowest --prefer-stable"
+  - PREFER_LOWEST=""
+matrix:
+  fast_finish: true
+  allow_failures:
+    - php: nightly
+before_script:
+  - composer update $PREFER_LOWEST
+script: ./vendor/bin/phpunit --coverage-clover clover.xml
+after_success: ./vendor/bin/coveralls -v

LICENSE

@@ -0,0 +1,20 @@
+The MIT License (MIT)
+
+Copyright (c) 2017 Trader Interactive
+
+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.

README.md

@@ -1,2 +1,72 @@
 # filter-ints-php
-A filtering implementation for verifying correct data and performing typical modifications to integers.
+
+A filtering implementation for verifying correct data and performing typical modifications to data.
+
+[![Build Status](https://travis-ci.org/traderinteractive/filter-ints-php.svg?branch=master)](https://travis-ci.org/traderinteractive/filter-ints-php)
+[![Scrutinizer Code Quality](https://scrutinizer-ci.com/g/traderinteractive/filter-ints-php/badges/quality-score.png?b=master)](https://scrutinizer-ci.com/g/traderinteractive/filter-ints-php/?branch=master)
+[![Coverage Status](https://coveralls.io/repos/github/traderinteractive/filter-ints-php/badge.svg?branch=master)](https://coveralls.io/github/traderinteractive/filter-ints-php?branch=master)
+
+[![Latest Stable Version](https://poser.pugx.org/traderinteractive/filter-ints/v/stable)](https://packagist.org/packages/traderinteractive/filter-ints)
+[![Latest Unstable Version](https://poser.pugx.org/traderinteractive/filter-ints/v/unstable)](https://packagist.org/packages/traderinteractive/filter-ints)
+[![License](https://poser.pugx.org/traderinteractive/filter-ints/license)](https://packagist.org/packages/traderinteractive/filter-ints)
+
+[![Total Downloads](https://poser.pugx.org/traderinteractive/filter-ints/downloads)](https://packagist.org/packages/traderinteractive/filter-ints)
+[![Daily Downloads](https://poser.pugx.org/traderinteractive/filter-ints/d/daily)](https://packagist.org/packages/traderinteractive/filter-ints)
+[![Monthly Downloads](https://poser.pugx.org/traderinteractive/filter-ints/d/monthly)](https://packagist.org/packages/traderinteractive/filter-ints)
+
+## Features
+
+TO DO
+
+## Example
+
+TO DO
+
+## Composer
+
+To add the library as a local, per-project dependency use [Composer](http://getcomposer.org)! Simply add a dependency on
+`traderinteractive/filter-ints` to your project's `composer.json` file such as:
+
+```sh
+composer require traderinteractive/filter-ints
+```
+
+## Documentation
+
+TO DO
+
+#### Specification
+
+TODO
+
+#### Ints/UnsignedInt::filter
+Aliased in the filterer as `int` or `uint`, respectively, these filters verify that the arguments are of the proper numeric type and
+allow for bounds checking.  The second parameter to each of them can be set to `true` to allow null values through without an error (they will
+stay null and not get converted to false).  The next two parameters are the min and max bounds and can be used to limit the domain of allowed
+numbers.
+
+Non-numeric strings will fail validation, and numeric strings will be cast.
+
+The following checks that `$value` is an integer between 1 and 100 inclusive, and returns the integer (after casting it if it was a string).
+```php
+$value = \TraderInteractive\Filter\UnsignedInt::filter($value, false, 1, 100);
+```
+
+
+## Contact
+
+Developers may be contacted at:
+
+ * [Pull Requests](https://github.com/traderinteractive/filter-ints-php/pulls)
+ * [Issues](https://github.com/traderinteractive/filter-ints-php/issues)
+
+## Project Build
+
+With a checkout of the code get [Composer](http://getcomposer.org) in your PATH and run:
+
+```bash
+./vendor/bin/phpcs
+./vendor/bin/phpunit
+```
+
+For more information on our build process, read through out our [Contribution Guidelines](CONTRIBUTING.md).

composer.json

@@ -0,0 +1,27 @@
+{
+    "name": "traderinteractive/filter-ints",
+    "description": "A filtering implementation for verifying correct data and performing typical modifications to data",
+    "keywords": [
+        "integer",
+        "ints",
+        "int",
+        "unsigned",
+        "uint"
+    ],
+    "config": {
+        "sort-packages": true
+    },
+    "license": "MIT",
+    "require": {
+        "php": "^7.0",
+        "traderinteractive/exceptions": "^1.0"
+    },
+    "require-dev": {
+        "php-coveralls/php-coveralls": "^1.0",
+        "phpunit/phpunit": "^6.0",
+        "squizlabs/php_codesniffer": "^3.2"
+    },
+    "autoload": {
+        "psr-4": { "TraderInteractive\\": "src/" }
+    }
+}

phpcs.xml

@@ -0,0 +1,8 @@
+<?xml version="1.0"?>
+<ruleset name="PHP_CodeSniffer">
+    <file>.</file>
+    <exclude-pattern>*/vendor/*</exclude-pattern>
+    <arg name="colors"/>
+    <arg value="p"/>
+    <rule ref="PSR2"/>
+</ruleset>

phpunit.xml.dist

@@ -0,0 +1,10 @@
+<phpunit colors="true" forceCoversAnnotation="true">
+    <testsuite name="Unit Tests">
+        <directory>./tests</directory>
+    </testsuite>
+    <filter>
+        <whitelist>
+            <directory>src</directory>
+        </whitelist>
+    </filter>
+</phpunit>

src/Filter/Ints.php

@@ -0,0 +1,92 @@
+<?php
+
+namespace TraderInteractive\Filter;
+
+use TraderInteractive\Exceptions\FilterException;
+
+/**
+ * A collection of filters for integers.
+ */
+final class Ints
+{
+    /**
+     * Filters $value to an integer strictly.
+     *
+     * $value must be an int or contain all digits, optionally prepended by a '+' or '-' and optionally surrounded by
+     * whitespace to pass the filter.
+     *
+     * The return value is the int, as expected by the \TraderInteractive\Filterer class.
+     *
+     * @param string|int $value     the value to make an integer
+     * @param bool       $allowNull Set to true if NULL values are allowed. The filtered result of a NULL value is NULL
+     * @param int        $minValue  The minimum acceptable value
+     * @param int        $maxValue  The maximum acceptable value
+     *
+     * @return int|null The filtered value
+     *
+     * @throws FilterException if $value string length is zero
+     * @throws FilterException if $value does not contain all digits, optionally prepended by a '+' or '-' and
+     *                         optionally surrounded by whitespace
+     * @throws FilterException if $value was greater than a max int of PHP_INT_MAX
+     * @throws FilterException if $value was less than a min int of ~PHP_INT_MAX
+     * @throws FilterException if $value is not a string
+     * @throws FilterException if $value is less than $minValue
+     * @throws FilterException if $value is greater than $maxValue
+     */
+    public static function filter($value, bool $allowNull = false, int $minValue = null, int $maxValue = PHP_INT_MAX)
+    {
+        if ($allowNull === true && $value === null) {
+            return null;
+        }
+
+        $valueInt = null;
+        if (is_int($value)) {
+            $valueInt = $value;
+        } elseif (is_string($value)) {
+            $value = trim($value);
+
+            if (strlen($value) === 0) {
+                throw new FilterException('$value string length is zero');
+            }
+
+            $stringToCheckDigits = $value;
+
+            if ($value[0] === '-' || $value[0] === '+') {
+                $stringToCheckDigits = substr($value, 1);
+            }
+
+            if (!ctype_digit($stringToCheckDigits)) {
+                throw new FilterException(
+                    "{$value} does not contain all digits, optionally prepended by a '+' or '-' and optionally "
+                    . "surrounded by whitespace"
+                );
+            }
+
+            $phpIntMin = ~PHP_INT_MAX;
+
+            $casted = (int)$value;
+
+            if ($casted === PHP_INT_MAX && $value !== (string)PHP_INT_MAX) {
+                throw new FilterException("{$value} was greater than a max int of " . PHP_INT_MAX);
+            }
+
+            if ($casted === $phpIntMin && $value !== (string)$phpIntMin) {
+                throw new FilterException("{$value} was less than a min int of {$phpIntMin}");
+            }
+
+            $valueInt = $casted;
+        } else {
+            throw new FilterException('"' . var_export($value, true) . '" $value is not a string');
+        }
+
+        if ($minValue !== null && $valueInt < $minValue) {
+            throw new FilterException("{$valueInt} is less than {$minValue}");
+        }
+
+        if ($valueInt > $maxValue) {
+            throw new FilterException("{$valueInt} is greater than {$maxValue}");
+        }
+
+        return $valueInt;
+    }
+}

src/Filter/UnsignedInt.php

@@ -0,0 +1,37 @@
+<?php
+
+namespace TraderInteractive\Filter;
+
+use TraderInteractive\Exceptions\FilterException;
+
+/**
+ * A collection of filters for unsigned integers.
+ */
+final class UnsignedInt
+{
+    /**
+     * Filters $value to an unsigned integer strictly.
+     *
+     * @see \TraderInteractive\Filter\Ints::filter()
+     *
+     * @param mixed $value     The value to be checked.
+     * @param bool  $allowNull Indicates if the value can be null.
+     * @param int   $minValue  Indicates the minimum acceptable value.
+     * @param int   $maxValue  Indicates the maximum acceptable value.
+     *
+     * @return int|null
+     *
+     * @throws \InvalidArgumentException if minvalue is not greater or equal to zero.
+     * @throws FilterException on failure to filter.
+     */
+    public static function filter($value, bool $allowNull = false, int $minValue = null, int $maxValue = PHP_INT_MAX)
+    {
+        if ($minValue === null) {
+            $minValue = 0;
+        } elseif (is_int($minValue) && $minValue < 0) {
+            throw new \InvalidArgumentException("{$minValue} was not greater or equal to zero");
+        }
+
+        return Ints::filter($value, $allowNull, $minValue, $maxValue);
+    }
+}