Skip to content

Commit

Permalink
Fixed up readme (cleared test now mock) and added a few gotchas.
Browse files Browse the repository at this point in the history
  • Loading branch information
@briannesbitt
briannesbitt committed Sep 9, 2013
1 parent ca70fce commit 06f0b8a
Show file tree
Hide file tree
Showing 5 changed files with 138 additions and 96 deletions.
7 changes: 7 additions & 0 deletions history.md
View file
Original file line number Diff line number Diff line change
@@ -1,3 +1,10 @@
1.4.0 / 2013-09-08
==================
* Corrected various PHPdocs
* formatLocalized() is now more OS independent
* Improved diff methods
* Test now can be mocked using a relative term

1.3.0 / 2013-08-21
==================

Expand Down
46 changes: 32 additions & 14 deletions readme.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -177,13 +177,13 @@ To accompany `now()`, a few other static instantiation helpers exist to create w

```php
$now = Carbon::now();
echo $now; // 2013-09-05 23:38:31
echo $now; // 2013-09-08 22:36:32
$today = Carbon::today();
echo $today; // 2013-09-05 00:00:00
echo $today; // 2013-09-08 00:00:00
$tomorrow = Carbon::tomorrow('Europe/London');
echo $tomorrow; // 2013-09-07 00:00:00
echo $tomorrow; // 2013-09-10 00:00:00
$yesterday = Carbon::yesterday();
echo $yesterday; // 2013-09-04 00:00:00
echo $yesterday; // 2013-09-07 00:00:00
```

The next group of static helpers are the `createXXX()` helpers. Most of the static `create` functions allow you to provide as many or as few arguments as you want and will provide default values for all others. Generally default values are the current date, time or timezone. Higher values will wrap appropriately but invalid values will throw an `InvalidArgumentException` with an informative message. The message is obtained from an [DateTime::getLastErrors()](http://php.net/manual/en/datetime.getlasterrors.php) call.
Expand Down Expand Up @@ -261,7 +261,7 @@ echo Carbon::parse('now'); // 2001-05-21 12:00:00
var_dump(Carbon::hasTestNow()); // bool(true)
Carbon::setTestNow(); // clear the mock
var_dump(Carbon::hasTestNow()); // bool(false)
echo Carbon::now(); // 2013-09-05 23:38:31
echo Carbon::now(); // 2013-09-08 22:36:32
```

A more meaning full example:
Expand Down Expand Up @@ -301,12 +301,27 @@ Relative phrases are also mocked according to the given "now" instance.
```php
$knownDate = Carbon::create(2001, 5, 21, 12); // create testing date
Carbon::setTestNow($knownDate); // set the mock
echo new Carbon('tomorrow'); // 2001-05-22 12:00:00
echo new Carbon('yesterday'); // 2001-05-20 12:00:00
echo new Carbon('next wednesday'); // 2001-05-23 12:00:00
echo new Carbon('last friday'); // 2001-05-18 12:00:00
echo new Carbon('this thursday'); // 2001-05-24 12:00:00
```
echo new Carbon('tomorrow'); // 2001-05-22 00:00:00
echo new Carbon('yesterday'); // 2001-05-20 00:00:00
echo new Carbon('next wednesday'); // 2001-05-23 00:00:00
echo new Carbon('last friday'); // 2001-05-18 00:00:00
echo new Carbon('this thursday'); // 2001-05-24 00:00:00
Carbon::setTestNow(); // always clear it !
```

The list of words that are considered to be relative modifiers are:
- this
- next
- last
- tomorrow
- yesterday
- +
- -
- first
- last
- ago

Be aware that similar to the next(), previous() and modify() methods some of these relative modifiers will set the time to 00:00:00.

<a name="api-getters"/>
### Getters
Expand All @@ -328,7 +343,7 @@ var_dump($dt->dayOfYear); // int(248)
var_dump($dt->weekOfYear); // int(36)
var_dump($dt->daysInMonth); // int(30)
var_dump($dt->timestamp); // int(1346901971)
var_dump(Carbon::createFromDate(1975, 5, 21)->age); // int(25) calculated vs now in the same tz
var_dump(Carbon::createFromDate(1975, 5, 21)->age); // int(38) calculated vs now in the same tz
var_dump($dt->quarter); // int(3)

// Returns an int of seconds difference from UTC (+/- sign included)
Expand Down Expand Up @@ -426,7 +441,7 @@ Unfortunately the base class DateTime does not have any localization support. T

```php
setlocale(LC_TIME, 'German');
echo $dt->formatLocalized('%A %d %B %Y'); // Thursday 25 December 1975
echo $dt->formatLocalized('%A %d %B %Y'); // Donnerstag 25 Dezember 1975
setlocale(LC_TIME, '');
echo $dt->formatLocalized('%A %d %B %Y'); // Thursday 25 December 1975
```
Expand Down Expand Up @@ -458,11 +473,14 @@ echo $dt->toW3CString();
Simple comparison is offered up via the following functions. Remember that the comparison is done in the UTC timezone so things aren't always as they seem.

```php
echo Carbon::now()->tzName; // America/Toronto
$first = Carbon::create(2012, 9, 5, 23, 26, 11);
$second = Carbon::create(2012, 9, 5, 20, 26, 11, 'America/Vancouver');

echo $first->toDateTimeString(); // 2012-09-05 23:26:11
echo $first->tzName; // America/Toronto
echo $second->toDateTimeString(); // 2012-09-05 20:26:11
echo $second->tzName; // America/Vancouver

var_dump($first->eq($second)); // bool(true)
var_dump($first->ne($second)); // bool(false)
Expand Down Expand Up @@ -637,7 +655,7 @@ echo Carbon::now()->addSeconds(5)->diffForHumans(); // 5 seconds from
<a name="api-modifiers"/>
### Modifiers

These group of methods perform helpful modifications to the current instance. Most of them are self explanatory from their names... or at least should be. You'll also notice that the startOfXXX() methods set the time to 00:00:00 and the endOfXXX() methods set the time to 23:59:59.
These group of methods perform helpful modifications to the current instance. Most of them are self explanatory from their names... or at least should be. You'll also notice that the startOfXXX(), next() and previous() methods set the time to 00:00:00 and the endOfXXX() methods set the time to 23:59:59.

```php
$dt = Carbon::create(2012, 1, 31, 12, 0, 0);
Expand Down
20 changes: 19 additions & 1 deletion readme.src.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -316,8 +316,23 @@ Relative phrases are also mocked according to the given "now" instance.
{{testaid8::exec(echo new Carbon('next wednesday');/*pad(54)*/)}} // {{testaid8_eval}}
{{testaid9::exec(echo new Carbon('last friday');/*pad(54)*/)}} // {{testaid9_eval}}
{{testaid10::exec(echo new Carbon('this thursday');/*pad(54)*/)}} // {{testaid10_eval}}
{{::exec(Carbon::setTestNow();/*pad(54)*/)}} // always clear it !
```

The list of words that are considered to be relative modifiers are:
- this
- next
- last
- tomorrow
- yesterday
- +
- -
- first
- last
- ago

Be aware that similar to the next(), previous() and modify() methods some of these relative modifiers will set the time to 00:00:00.

<a name="api-getters"/>
### Getters

Expand Down Expand Up @@ -472,11 +487,14 @@ echo $dt->toW3CString();
Simple comparison is offered up via the following functions. Remember that the comparison is done in the UTC timezone so things aren't always as they seem.

```php
{{comparetz::exec(echo Carbon::now()->tzName;/*pad(50)*/)}} // {{comparetz_eval}}
{{::lint($first = Carbon::create(2012, 9, 5, 23, 26, 11);)}}
{{::lint($second = Carbon::create(2012, 9, 5, 20, 26, 11, 'America/Vancouver');)}}

{{compare1::exec(echo $first->toDateTimeString();/*pad(50)*/)}} // {{compare1_eval}}
{{compare1tz::exec(echo $first->tzName;/*pad(50)*/)}} // {{compare1tz_eval}}
{{compare2::exec(echo $second->toDateTimeString();/*pad(50)*/)}} // {{compare2_eval}}
{{compare2tz::exec(echo $second->tzName;/*pad(50)*/)}} // {{compare2tz_eval}}

{{compare3::exec(var_dump($first->eq($second));/*pad(50)*/)}} // {{compare3_eval}}
{{compare4::exec(var_dump($first->ne($second));/*pad(50)*/)}} // {{compare4_eval}}
Expand Down Expand Up @@ -653,7 +671,7 @@ This method will add a phrase after the difference value relative to the instanc
<a name="api-modifiers"/>
### Modifiers

These group of methods perform helpful modifications to the current instance. Most of them are self explanatory from their names... or at least should be. You'll also notice that the startOfXXX() methods set the time to 00:00:00 and the endOfXXX() methods set the time to 23:59:59.
These group of methods perform helpful modifications to the current instance. Most of them are self explanatory from their names... or at least should be. You'll also notice that the startOfXXX(), next() and previous() methods set the time to 00:00:00 and the endOfXXX() methods set the time to 23:59:59.

```php
{{::lint($dt = Carbon::create(2012, 1, 31, 12, 0, 0);/*pad(40)*/)}}
Expand Down
87 changes: 43 additions & 44 deletions src/Carbon/Carbon.php
View file
Original file line number Diff line number Diff line change
Expand Up @@ -77,16 +77,16 @@ class Carbon extends DateTime
* @var array
*/
private static $relativeKeywords = array(
'this',
'next',
'last',
'tomorrow',
'yesterday',
'+',
'-',
'first',
'last',
'ago'
'this',
'next',
'last',
'tomorrow',
'yesterday',
'+',
'-',
'first',
'last',
'ago'
);

/**
Expand Down Expand Up @@ -146,11 +146,11 @@ public function __construct($time = null, $tz = null)
// If the class has a test now set and we are trying to create a now()
// instance then override as required
if (static::hasTestNow() && (empty($time) || $time === 'now' || self::hasRelativeKeywords($time))) {
if (self::hasRelativeKeywords($time)) {
$time = static::getRelativeTest($time)->toDateTimeString();
} else {
$time = static::getTestNow()->toDateTimeString();
}
if (self::hasRelativeKeywords($time)) {
$time = static::getRelativeTest($time)->toDateTimeString();
} else {
$time = static::getTestNow()->toDateTimeString();
}
$tz = static::getTestNow()->tz;
}

Expand Down Expand Up @@ -736,33 +736,32 @@ public static function hasTestNow()
return static::getTestNow() !== null;
}

/**
* Determine if there is a relative keyword in the time string, this is to
* create dates relative to now for test instances. e.g.: next tuesday
*
* @return boolean true if there is a keyword, otherwise false
*/
public static function hasRelativeKeywords($time) {
foreach(self::$relativeKeywords as $keyword) {
if (stripos($time, $keyword) !== false) {
return true;
}
}
return false;
}

/**
* Gets a Carbon instance relative to the current test instance.
* e.g.: last thursday, tomorrow
*
* @return Carbon relative to the current instance used for testing
*/
public static function getRelativeTest($time) {
$testNow = static::getTestNow();
$instance = new static();
$instance->modify($time);
return $instance;
}
/**
* Determine if there is a relative keyword in the time string, this is to
* create dates relative to now for test instances. e.g.: next tuesday
*
* @return boolean true if there is a keyword, otherwise false
*/
public static function hasRelativeKeywords($time) {
foreach(self::$relativeKeywords as $keyword) {
if (stripos($time, $keyword) !== false) {
return true;
}
}
return false;
}

/**
* Gets a Carbon instance relative to the current test instance.
* e.g.: last thursday, tomorrow
*
* @return Carbon relative to the current instance used for testing
*/
public static function getRelativeTest($time) {
$instance = new static();
$instance->modify($time);
return $instance;
}

///////////////////////////////////////////////////////////////////
/////////////////////// STRING FORMATTING /////////////////////////
Expand All @@ -778,12 +777,12 @@ public static function getRelativeTest($time) {
*/
public function formatLocalized($format)
{
// Check for Windows to find and replace the %e
// Check for Windows to find and replace the %e
// modifier correctly
if (strtoupper(substr(PHP_OS, 0, 3)) == 'WIN') {
$format = preg_replace('#(?<!%)((?:%%)*)%e#', '\1%#d', $format);
}

return strftime($format, $this->timestamp);
}

Expand Down
74 changes: 37 additions & 37 deletions tests/TestingAidsTest.php
View file
Original file line number Diff line number Diff line change
Expand Up @@ -58,47 +58,47 @@ public function testParseWithTestValueSet()
$this->assertEquals($notNow, Carbon::parse(''));
$this->assertEquals($notNow, Carbon::parse('now'));
}
public function testParseRelativeWithTestValueSet()

public function testParseRelativeWithTestValueSet()
{
$notNow = Carbon::parse('2013-09-01 05:15:05');
Carbon::setTestNow($notNow);

$this->assertEquals('2013-09-01 05:10:05', Carbon::parse('5 minutes ago')->toDateTimeString());

$this->assertEquals('2013-08-25 05:15:05', Carbon::parse('1 week ago')->toDateTimeString());
$this->assertEquals('2013-09-02', Carbon::parse('tomorrow')->toDateString());
$this->assertEquals('2013-08-31', Carbon::parse('yesterday')->toDateString());
$this->assertEquals('2013-09-02', Carbon::parse('+1 day')->toDateString());
$this->assertEquals('2013-08-31', Carbon::parse('-1 day')->toDateString());
$this->assertEquals('2013-09-02', Carbon::parse('next monday')->toDateString());
$this->assertEquals('2013-09-03', Carbon::parse('next tuesday')->toDateString());
$this->assertEquals('2013-09-04', Carbon::parse('next wednesday')->toDateString());
$this->assertEquals('2013-09-05', Carbon::parse('next thursday')->toDateString());
$this->assertEquals('2013-09-06', Carbon::parse('next friday')->toDateString());
$this->assertEquals('2013-09-07', Carbon::parse('next saturday')->toDateString());
$this->assertEquals('2013-09-08', Carbon::parse('next sunday')->toDateString());
$this->assertEquals('2013-08-26', Carbon::parse('last monday')->toDateString());
$this->assertEquals('2013-08-27', Carbon::parse('last tuesday')->toDateString());
$this->assertEquals('2013-08-28', Carbon::parse('last wednesday')->toDateString());
$this->assertEquals('2013-08-29', Carbon::parse('last thursday')->toDateString());
$this->assertEquals('2013-08-30', Carbon::parse('last friday')->toDateString());
$this->assertEquals('2013-08-31', Carbon::parse('last saturday')->toDateString());
$this->assertEquals('2013-08-25', Carbon::parse('last sunday')->toDateString());
$this->assertEquals('2013-09-02', Carbon::parse('this monday')->toDateString());
$this->assertEquals('2013-09-03', Carbon::parse('this tuesday')->toDateString());
$this->assertEquals('2013-09-04', Carbon::parse('this wednesday')->toDateString());
$this->assertEquals('2013-09-05', Carbon::parse('this thursday')->toDateString());
$this->assertEquals('2013-09-06', Carbon::parse('this friday')->toDateString());
$this->assertEquals('2013-09-07', Carbon::parse('this saturday')->toDateString());
$this->assertEquals('2013-09-01', Carbon::parse('this sunday')->toDateString());
$this->assertEquals('2013-10-01', Carbon::parse('first day of next month')->toDateString());
$this->assertEquals('2013-09-30', Carbon::parse('last day of this month')->toDateString());

$this->assertEquals('2013-09-02 00:00:00', Carbon::parse('tomorrow')->toDateTimeString());
$this->assertEquals('2013-08-31 00:00:00', Carbon::parse('yesterday')->toDateTimeString());

$this->assertEquals('2013-09-02 05:15:05', Carbon::parse('+1 day')->toDateTimeString());
$this->assertEquals('2013-08-31 05:15:05', Carbon::parse('-1 day')->toDateTimeString());

$this->assertEquals('2013-09-02 00:00:00', Carbon::parse('next monday')->toDateTimeString());
$this->assertEquals('2013-09-03 00:00:00', Carbon::parse('next tuesday')->toDateTimeString());
$this->assertEquals('2013-09-04 00:00:00', Carbon::parse('next wednesday')->toDateTimeString());
$this->assertEquals('2013-09-05 00:00:00', Carbon::parse('next thursday')->toDateTimeString());
$this->assertEquals('2013-09-06 00:00:00', Carbon::parse('next friday')->toDateTimeString());
$this->assertEquals('2013-09-07 00:00:00', Carbon::parse('next saturday')->toDateTimeString());
$this->assertEquals('2013-09-08 00:00:00', Carbon::parse('next sunday')->toDateTimeString());

$this->assertEquals('2013-08-26 00:00:00', Carbon::parse('last monday')->toDateTimeString());
$this->assertEquals('2013-08-27 00:00:00', Carbon::parse('last tuesday')->toDateTimeString());
$this->assertEquals('2013-08-28 00:00:00', Carbon::parse('last wednesday')->toDateTimeString());
$this->assertEquals('2013-08-29 00:00:00', Carbon::parse('last thursday')->toDateTimeString());
$this->assertEquals('2013-08-30 00:00:00', Carbon::parse('last friday')->toDateTimeString());
$this->assertEquals('2013-08-31 00:00:00', Carbon::parse('last saturday')->toDateTimeString());
$this->assertEquals('2013-08-25 00:00:00', Carbon::parse('last sunday')->toDateTimeString());

$this->assertEquals('2013-09-02 00:00:00', Carbon::parse('this monday')->toDateTimeString());
$this->assertEquals('2013-09-03 00:00:00', Carbon::parse('this tuesday')->toDateTimeString());
$this->assertEquals('2013-09-04 00:00:00', Carbon::parse('this wednesday')->toDateTimeString());
$this->assertEquals('2013-09-05 00:00:00', Carbon::parse('this thursday')->toDateTimeString());
$this->assertEquals('2013-09-06 00:00:00', Carbon::parse('this friday')->toDateTimeString());
$this->assertEquals('2013-09-07 00:00:00', Carbon::parse('this saturday')->toDateTimeString());
$this->assertEquals('2013-09-01 00:00:00', Carbon::parse('this sunday')->toDateTimeString());

$this->assertEquals('2013-10-01 05:15:05', Carbon::parse('first day of next month')->toDateTimeString());
$this->assertEquals('2013-09-30 05:15:05', Carbon::parse('last day of this month')->toDateTimeString());
}
}

0 comments on commit 06f0b8a

Please sign in to comment.