Merge pull request #1 from hotline-emu/init

[WIP] Version 3.0

.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-dates-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(< B).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,79 @@
 # filter-dates-php
-A filtering implementation for verifying correct data and performing typical modifications to dates and times.
+
+[![Build Status](https://travis-ci.org/traderinteractive/filter-dates-php.svg?branch=master)](https://travis-ci.org/traderinteractive/filter-dates-php)
+[![Scrutinizer Code Quality](https://scrutinizer-ci.com/g/traderinteractive/filter-dates-php/badges/quality-score.png?b=master)](https://scrutinizer-ci.com/g/traderinteractive/filter-dates-php/?branch=master)
+[![Coverage Status](https://coveralls.io/repos/github/traderinteractive/filter-dates-php/badge.svg?branch=master)](https://coveralls.io/github/traderinteractive/filter-dates-php?branch=master)
+
+[![Latest Stable Version](https://poser.pugx.org/traderinteractive/filter-dates/v/stable)](https://packagist.org/packages/traderinteractive/filter-dates)
+[![Latest Unstable Version](https://poser.pugx.org/traderinteractive/filter-dates/v/unstable)](https://packagist.org/packages/traderinteractive/filter-dates)
+[![License](https://poser.pugx.org/traderinteractive/filter-dates/license)](https://packagist.org/packages/traderinteractive/filter-dates)
+
+[![Total Downloads](https://poser.pugx.org/traderinteractive/filter-dates/downloads)](https://packagist.org/packages/traderinteractive/filter-dates)
+[![Daily Downloads](https://poser.pugx.org/traderinteractive/filter-dates/d/daily)](https://packagist.org/packages/traderinteractive/filter-dates)
+[![Monthly Downloads](https://poser.pugx.org/traderinteractive/filter-dates/d/monthly)](https://packagist.org/packages/traderinteractive/filter-dates)
+
+A filtering implementation for verifying correct data and performing typical modifications to common date objects.
+
+## Requirements
+
+Requires PHP 7.0 or newer and uses composer to install further PHP dependencies.  See the [composer specification](composer.json) for more details.
+
+## Composer
+
+To add the library as a local, per-project dependency use [Composer](http://getcomposer.org)! Simply add a dependency on
+`traderinteractive/filter-dates` to your project's `composer.json` file such as:
+
+```sh
+composer require traderinteractive/filter-dates
+```
+
+### Functionality
+
+#### DateTime::filter
+
+This will filter the value as a `\DateTime` object. The value can be any string that conforms to [PHP's valid date/time formats](http://php.net/manual/en/datetime.formats.php)
+
+The following checks that `$value` is a date/time.
+
+```php
+$dateTime = \TraderInteractive\Filter\DateTime::filter('2014-02-04T11:55:00-0500');
+```
+
+#### DateTime::format
+
+This will filter a given `\DateTime' value to a string based on the given format.
+
+The following returns formatted string for a given `\DateTime` `$value`
+
+```php
+$formatted = \TraderInteractive\Filter\DateTime::format($value, 'Y-m-d H:i:s');
+```
+
+#### DateTimeZone::filter
+
+This will filter the value as a `\DateTimeZone` object. The value can be any [supported timezone name](http://php.net/manual/en/timezones.php)
+
+The following checks that `$value` is a timezone
+
+```php
+$timezone = \TraderInteractive\Filter\DateTimeZone::filter('America/New_York');
+```
+
+## Contact
+
+Developers may be contacted at:
+
+ * [Pull Requests](https://github.com/traderinteractive/filter-dates-php/pulls)
+ * [Issues](https://github.com/traderinteractive/filter-dates-php/issues)
+
+## Project Build
+
+With a checkout of the code get [Composer](http://getcomposer.org) in your PATH and run:
+
+```bash
+composer install
+./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,31 @@
+{
+    "name": "traderinteractive/filter-dates",
+    "description": "A filtering implementation for verifying dates",
+    "keywords": [
+        "utility",
+        "dates",
+        "date",
+        "datetime",
+        "datetimezone",
+        "timezone"
+    ],
+    "config": {
+        "sort-packages": true
+    },
+    "license": "MIT",
+    "require": {
+        "php": "^7.0",
+        "traderinteractive/exceptions": "^1.0"
+    },
+    "suggest": {
+        "ext-timezonedb": "The latest version of the timezone database"
+    },
+    "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/DateTime.php

@@ -0,0 +1,75 @@
+<?php
+
+namespace TraderInteractive\Filter;
+
+use DateTimeInterface;
+use DateTimeZone as DateTimeZoneStandard;
+use DateTime as DateTimeStandard;
+use TraderInteractive\Exceptions\FilterException;
+
+/**
+ * A collection of filters for filtering strings into \DateTime objects.
+ */
+class DateTime
+{
+    /**
+     * Filters the given value into a \DateTime object.
+     *
+     * @param mixed                $value     The value to be filtered.
+     * @param boolean $allowNull              True to allow nulls through, and false (default) if nulls should
+     *                                        not be allowed.
+     * @param DateTimeZoneStandard $timezone  A \DateTimeZone object representing the timezone of $value.
+     *                                        If $timezone is omitted, the current timezone will be used.
+     *
+     * @return DateTimeStandard|null
+     *
+     * @throws FilterException if the value did not pass validation.
+     */
+    public static function filter($value, bool $allowNull = false, DateTimeZoneStandard $timezone = null)
+    {
+        if (self::valueIsNullAndValid($allowNull, $value)) {
+            return null;
+        }
+
+        if ($value instanceof DateTimeStandard) {
+            return $value;
+        }
+
+        if (is_int($value) || ctype_digit($value)) {
+            $value = "@{$value}";
+        }
+
+        if (!is_string($value) || trim($value) == '') {
+            throw new FilterException('$value is not a non-empty string');
+        }
+
+        return new DateTimeStandard($value, $timezone);
+    }
+
+    /**
+     * Filters the give \DateTime object to a formatted string.
+     *
+     * @param DateTimeInterface $dateTime The date to be formatted.
+     * @param string            $format   The format of the outputted date string.
+     *
+     * @return string
+     *
+     * @throws \InvalidArgumentException Thrown if $format is not a string
+     */
+    public static function format(DateTimeInterface $dateTime, string $format = 'c') : string
+    {
+        if (empty(trim($format))) {
+            throw new \InvalidArgumentException('$format is not a non-empty string');
+        }
+
+        return $dateTime->format($format);
+    }
+
+    private static function valueIsNullAndValid(bool $allowNull, $value = null) : bool
+    {
+        if ($allowNull === false && $value === null) {
+            throw new FilterException('Value failed filtering, $allowNull is set to false');
+        }
+        return $allowNull === true && $value === null;
+    }
+}

src/Filter/DateTimeZone.php

@@ -0,0 +1,50 @@
+<?php
+
+namespace TraderInteractive\Filter;
+
+use TraderInteractive\Exceptions\FilterException;
+
+/**
+ * A collection of filters for filtering strings into \DateTimeZone objects.
+ */
+class DateTimeZone
+{
+    /**
+     * Filters the given value into a \DateTimeZone object.
+     *
+     * @param mixed   $value     The value to be filtered.
+     * @param boolean $allowNull True to allow nulls through, and false (default) if nulls should not be allowed.
+     *
+     * @return \DateTimeZone|null
+     *
+     * @throws FilterException if the value did not pass validation.
+     */
+    public static function filter($value, bool $allowNull = false)
+    {
+        if (self::valueIsNullAndValid($allowNull, $value)) {
+            return null;
+        }
+
+        if ($value instanceof \DateTimeZone) {
+            return $value;
+        }
+
+        if (!is_string($value) || trim($value) == '') {
+            throw new FilterException('$value not a non-empty string');
+        }
+
+        try {
+            return new \DateTimeZone($value);
+        } catch (\Exception $e) {
+            throw new FilterException($e->getMessage(), $e->getCode(), $e);
+        }
+    }
+
+    private static function valueIsNullAndValid(bool $allowNull, $value = null) : bool
+    {
+        if ($allowNull === false && $value === null) {
+            throw new FilterException('Value failed filtering, $allowNull is set to false');
+        }
+        return $allowNull === true && $value === null;
+    }
+}