Complete set of PHP Date classes extensions:
| class | extends | comment |
|---|---|---|
| Carbon | DateTime | |
| CarbonImmutable | DateTimeImmutable | new |
| CarbonInterface | DateTimeInterface | new |
| CarbonTimeZone | DateTimeZone | new |
| CarbonInterval | DateInterval | Read-only days property |
| CarbonPeriod | DatePeriod | Blocked until php/php-src#3121 get merged |
Setter methods of Carbon become cloners in CarbonImmutable:
$m = new Carbon;
$c1 = $m->setDay(1);
// $m->day === $c1->day as $c1 === $m
$i = new CarbonImmutable;
$c2 = $i->setDay(1);
// $m->day !== $c2->day as $c2 is a new object
$c1->day = 9; // $m->day === 9
$c2->day = 9; // error, immutableTo reduce code amount, we could rather have a magic __call method parsing methods matching actionUnit with action in a given list (isSame, isCurrent, add, sub, get, set, floor, ceil, round, etc.) and unit as valid unit (second, minute, hour, day, etc.) to route to generic method (action) with a unit argument.
This will enforce some methods consistency (easy way to handle singular/plural, same arguments for a given action). And a easier way to add actions. This would encourage to drop boolean arguments (which give multiple responsability to a single method) in favor of adding methods.
A automated script could update the PHPDoc comment to add @method annotations so even if the methods does not really exist, IDE autocompletion will propose magic methods and we would not have to add them all manually.
Having a methods set compatible with https://momentjs.com could help to create a full-stack standard.
Critical methods should be final (macro methods, magic methods) so it would help us to prevent breaking changes in sub-classes.
Methods should be grouped in traits and each trait should remain stand-alone (could be taken alone).
Instead of extends the Carbon classes, users would be able to compose their own date classes picking traits.
Documentation could be interactive (see https://pug-demo.herokuapp.com and https://phug-lang.com/, it provides code examples the user can edit in live to see the PHP result).
Carbon become big, the single-page and one-level links menu will become a bit too limited, some search/expand/collapse tools would help to browse it.
Each method must be documented with minimal informations:
- history, example: added in 2.1.0, argument $foo added in 2.2.0, $foo can be an array since 2.2.1
- trait, example: set() belongs to Setter trait
- arguments, return and exceptions thrown
- code examples
To provide reliable solid library, Carbon should rely on a full microseconds support, that means at least PHP 7.1.8.
Carbon is widely used. We should not abandon v1 users.
- V1 documentation must remain available
- An issue templating and 1.x/2.x tagging will help to handle issues
- A migration guide could help user to upgrade
- Dropped methods could remain in the documentation (tagged as obsolete with some gray-styling and collapsed description)
floor/ceil/round is nearly finished in my local env.
Quick overview about momentjs compatibility (including briannesbitt/Carbon#1360):
(1) min and max are deprecated because of an inverted behavior, our behavior match the non-inverted behavior. Moment also have a static method which could be nice to have for min/max.
(2) format in momentjs is isoFormat in Carbon to keep original format method from DateTime class.
(3) deprecated method not relevant.
(4) provide getter instead.