Major overhaul to the entire script

  - Now using Carbon for all date manipulation
  - Return a Carbon instance representing the next (or previous) date
  - Added tests!
  - Added detaild documentation in the README

.gitignore

@@ -0,0 +1,2 @@
+composer.lock
+/vendor/

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2017 PHX2600 [https://www.phx2600.org]
+
+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,24 +1,132 @@
 FirstFriday.php
 ===============
 
-Calculates the next, first Friday of the month.
-
-**Copyright (c) 2013 Chris Kankewicz <[email protected]>**
-
-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.
+[![Latest Stable Version](https://img.shields.io/packagist/v/PHX2600/FirstFriday.svg)](https://packagist.org/packages/PHX2600/FirstFriday)
+[![Total Downloads](https://img.shields.io/packagist/dt/PHX2600/FirstFriday.svg)](https://packagist.org/packages/PHX2600/FirstFriday)
+[![Author](https://img.shields.io/badge/author-Chris%20Kankiewicz-blue.svg)](https://www.ChrisKankiewicz.com)
+[![License](https://img.shields.io/packagist/l/PHX2600/FirstFriday.svg)](https://packagist.org/packages/PHX2600/FirstFriday)
+[![Build Status](https://img.shields.io/travis/PHX2600/FirstFriday.svg)](https://travis-ci.org/PHX2600/FirstFriday)
+
+Introduction
+------------
+
+Calculates the next and previous, first Friday of the month.
+
+Like this project? Keep me caffeinated by [making a donation](https://paypal.me/ChrisKankiewicz).
+
+Requirements
+------------
+
+  - [PHP](https://php.net) >= 5.6
+
+Install with Composer
+---------------------
+
+```bash
+composer require phx2600/firstfriday
+```
+
+Usage
+-----
+
+First, import FirstFriday:
+
+```php
+use PHX2600/FirstFriday;
+```
+
+Then instantiate the class:
+
+```php
+$firstFriday = new FirstFriday($timezone);
+```
+
+Where `$timezone` is a String representation of a timezone to be used for date
+calculations. For example `America/Phoenix`, `Antarctica/Troll` or `UTC`.  See
+http://bit.ly/php-tzs for a full list of available timezones.
+
+Once your class is instantiated you can get the next first Friday of the month
+via the `next()` method:
+
+```php
+$nextFirstFriday = $firstFriday->next();
+```
+
+or the previous first Friday via the `previous()` method:
+
+```php
+$previousFirstFriday = $firstfriday->previous();
+```
+
+Both the `next()` and the `previous()` methods return an instance of
+[Carbon](http://carbon.nesbot.com/). This makes date calculations and returning
+specific date information easy. For example:
+
+**Return a pre-formatted date string:**
+
+```php
+$nextFirstFriday->toDateString();           // 1975-12-25
+$nextFirstFriday->toFormattedDateString();  // Dec 25, 1975
+$nextFirstFriday->toDateTimeString();       // 1975-12-25 14:15:16
+$nextFirstFriday->toDayDateTimeString();    // Thu, Dec 25, 1975 2:15 PM
+```
+
+**Return a custom formatted string:**
+
+```php
+$nextFirstFriday->format('l jS \\of F Y h:i:s A');  // Thursday 25th of December 1975 02:15:16 PM
+```
+
+**Get the time until the next first Friday in human a human readable format:**
+
+```php
+$nextFirstFriday->diffForHumans();  // Something like '1 week from now' or '1 month from now'
+```
+
+**Cabon also provides a number of convinient comparison functions, for example:**
+
+```php
+// The following return boolean true or false
+$firstFriday->isToday();
+$firstFriday->isYesterday();
+$firstFriday->isTomorrow();
+$firstFriday->isFuture();
+$firstFriday->isPast();
+```
+
+See the [Carbon documentation](http://carbon.nesbot.com/docs/) for more details.
+
+---
+
+You may also override the value used as "today" in the date calculations. This
+will allow you to make calculations as if today were another day. This can be
+accomplished by passing an instance of Carbon as the second parameter when
+instantiating the FirstFriday class:
+
+```php
+$today = Carbon::create(2017, 7, 1, 0, 0, 0, 'America/Phoenix');
+$firstFriday = new FirstFriday('America/Phoenix', $today);
+```
+
+or fluently:
+
+```php
+$firstFriday = new FirstFriday('America/Phoenix');
+$today = Carbon::create(2017, 7, 1, 0, 0, 0, 'America/Phoenix');
+
+$firstFriday->overrideToday($today)->next();
+```
+
+**NOTE:** Be sure to set the timezone of the `$today` parameter to the same
+timezone passed to the `$timezone` argument of the FirstFriday class to ensure
+consistency in date calculations. Failing to do so may cause unexpected results.
+
+Troubleshooting
+---------------
+
+Please report bugs to the [GitHub Issue Tracker](https://github.com/PHX2600/FirstFriday/issues).
+
+Copyright
+---------
+
+This project is liscensed under the [MIT License](https://github.com/PHX2600/FirstFriday/blob/master/LICENSE).

composer.json

@@ -11,14 +11,18 @@
         }
     ],
     "support": {
-        "email": "chris@chriskankiewicz.com"
+        "issues": "https://github.com/PHX2600/FirstFriday/issues"
     },
     "require": {
-        "php" : ">=5.3.0"
+        "php" : ">=5.6.0",
+        "nesbot/carbon": "^1.22"
     },
     "autoload": {
-        "classmap": [
-            "FirstFriday.php"
-        ]
+        "psr-4": {
+            "PHX2600\\": "src/PHX2600/"
+        }
+    },
+    "require-dev": {
+        "phpunit/phpunit": "^5.7"
     }
 }

phpunit.xml

@@ -0,0 +1,8 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<phpunit bootstrap="vendor/autoload.php" colors="true">
+    <testsuites>
+        <testsuite name="PHX2600\FirstFriday Test Suite">
+            <directory suffix="Test.php">tests/</directory>
+        </testsuite>
+    </testsuites>
+</phpunit>

src/PHX2600/FirstFriday.php

@@ -0,0 +1,73 @@
+<?php
+
+namespace PHX2600;
+
+use Carbon\Carbon;
+
+class FirstFriday
+{
+    /** @var string Timezone for date calculations */
+    protected $timezone;
+
+    /** @var Carbon instance to be used for "today" in date calculations */
+    protected $today;
+
+    /**
+     * FirstFriday constructor method; runs on object creation.
+     *
+     * @param string $timezone String representation of a timezone to be used
+     *                         for date calculations. See: http://bit.ly/php-tzs
+     * @param Carbon $today Carbon instance representing the value to be used
+     *                      for "today" in date calculations
+     */
+    public function __construct($timezone, Carbon $today = null)
+    {
+        $this->timezone = $timezone;
+        $this->today = isset($today) ? $today : Carbon::today($this->timezone);
+    }
+
+    /**
+     * Calculate the next first Friday of the month.
+     *
+     * @return Carbon instance representing the next first Friday
+     */
+    public function next()
+    {
+        $firstFriday = new Carbon('first friday of this month', $this->timezone);
+
+        if ($this->today->gt($firstFriday)) {
+            return new Carbon('first friday of next month', $this->timezone);
+        }
+
+        return $firstFriday;
+    }
+
+    /**
+     * Calculate the previous first Friday of the month.
+     *
+     * @return Carbon instance representing the previous first Friday
+     */
+    public function previous()
+    {
+        $firstFriday = new Carbon('first friday of this month', $this->timezone);
+
+        if ($this->today->lte($firstFriday)) {
+            return new Carbon('first friday of last month', $this->timezone);
+        }
+
+        return $firstFriday;
+    }
+
+    /**
+     * Override the value to be used for "today" in date calculations.
+     *
+     * @param Carbon $today Carbon instance representing the value to be used
+     *                      for "today" in date calculations
+     *
+     * @return PHX2600\FirstFriday
+     */
+    public function overrideToday(Carbon $today)
+    {
+        return new static($this->timezone, $today);
+    }
+}