From ca046d67926a9f9100e1d8f769097446cd04a5dd Mon Sep 17 00:00:00 2001 From: Chris Kankiewicz Date: Sun, 9 Jul 2017 12:20:31 -0700 Subject: [PATCH] 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 | 2 + FirstFriday.php | 58 -------------- LICENSE | 21 +++++ README.md | 150 +++++++++++++++++++++++++++++++----- composer.json | 14 ++-- phpunit.xml | 8 ++ src/PHX2600/FirstFriday.php | 73 ++++++++++++++++++ tests/FirstFridayTest.php | 54 +++++++++++++ 8 files changed, 296 insertions(+), 84 deletions(-) create mode 100644 .gitignore delete mode 100644 FirstFriday.php create mode 100644 LICENSE create mode 100644 phpunit.xml create mode 100644 src/PHX2600/FirstFriday.php create mode 100644 tests/FirstFridayTest.php diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..c55784d --- /dev/null +++ b/.gitignore @@ -0,0 +1,2 @@ +composer.lock +/vendor/ diff --git a/FirstFriday.php b/FirstFriday.php deleted file mode 100644 index 5875dff..0000000 --- a/FirstFriday.php +++ /dev/null @@ -1,58 +0,0 @@ - date('d', $thisFirstFriday)) { - // Calculate first Friday of next month - $nextFirstFriday = strtotime('first friday of next month'); - $firstFriday = $nextFirstFriday; - } else { - // Set the next first Friday - $firstFriday = $thisFirstFriday; - } - - // Return next first Friday timestamp - return $firstFriday; - - } - - /** - * Returns formatted string of the next first Friday - * - * @param $format PHP date format string - * @return string Formatted string of the next first Friday - * @access public - */ - public function getFormatted($format = "F j, Y") { - - // Return formatted date - return date($format, $this->getTimeStamp()); - - } - - } diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..11d4fb2 --- /dev/null +++ b/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. diff --git a/README.md b/README.md index b4f1aaa..c002772 100644 --- a/README.md +++ b/README.md @@ -1,24 +1,132 @@ FirstFriday.php =============== -Calculates the next, first Friday of the month. - -**Copyright (c) 2013 Chris Kankewicz ** - -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. \ No newline at end of file +[![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). diff --git a/composer.json b/composer.json index bfc35e0..30463b8 100644 --- a/composer.json +++ b/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" } } diff --git a/phpunit.xml b/phpunit.xml new file mode 100644 index 0000000..7c2cea1 --- /dev/null +++ b/phpunit.xml @@ -0,0 +1,8 @@ + + + + + tests/ + + + diff --git a/src/PHX2600/FirstFriday.php b/src/PHX2600/FirstFriday.php new file mode 100644 index 0000000..e138b85 --- /dev/null +++ b/src/PHX2600/FirstFriday.php @@ -0,0 +1,73 @@ +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); + } +} diff --git a/tests/FirstFridayTest.php b/tests/FirstFridayTest.php new file mode 100644 index 0000000..91bf17e --- /dev/null +++ b/tests/FirstFridayTest.php @@ -0,0 +1,54 @@ +firstFriday = $firstFriday = new FirstFriday('America/Phoenix'); + } + + public function test_it_returns_an_instance_of_carbon() + { + $this->assertInstanceOf(Carbon::class, $this->firstFriday->next()); + $this->assertInstanceOf(Carbon::class, $this->firstFriday->previous()); + } + + public function test_it_can_calculate_the_next_first_friday() + { + $firstFriday = $this->firstFriday->overrideToday( + Carbon::create(2017, 7, 1, 0, 0, 0, 'America/Phoenix') + )->next(); + + $this->assertEquals('2017-07-07', $firstFriday->toDateString()); + } + + public function test_it_can_calculate_the_next_first_friday_if_today_is_a_first_friday() + { + $firstFriday = $this->firstFriday->overrideToday( + Carbon::create(2017, 7, 7, 0, 0, 0, 'America/Phoenix') + )->next(); + + $this->assertEquals('2017-07-07', $firstFriday->toDateString()); + } + + public function test_it_can_calculate_the_previous_first_friday() + { + $firstFriday = $this->firstFriday->overrideToday( + Carbon::create(2017, 7, 1, 0, 0, 0, 'America/Phoenix') + )->previous(); + + $this->assertEquals('2017-06-02', $firstFriday->toDateString()); + } + + public function test_it_can_calculate_the_previous_first_friday_if_today_is_a_first_friday() + { + $firstFriday = $this->firstFriday->overrideToday( + Carbon::create(2017, 7, 7, 0, 0, 0, 'America/Phoenix') + )->previous(); + + $this->assertEquals('2017-06-02', $firstFriday->toDateString()); + } +}