kylekatarnls/roadmap.md

## roadmap.md

      
    Raw
  

              roadmap.md
            
          
    Carbon 2 (Draft)

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, immutable
Generic methods

To 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.
Stricter extends

Critical methods should be final (macro methods, magic methods) so it would help us to prevent breaking changes in sub-classes.
All methods in traits

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

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

Requirement

To provide reliable solid library, Carbon should rely on a full microseconds support, that means at least PHP 7.1.8.
About version 1.x

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)
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
Method	exists	is compatible
add	x	x
calendar	x	x
clone	x	x
creationData
date	(4)	(4)
dates	(3)	(3)
day	x
dayOfYear	x	x
days	x
daysInMonth	(4)	(4)
diff	x
endOf	x	x
format	x	x(2)
from	x	x
fromNow	x	x
get	x	x
hasAlignedHourOffset
hour	x	x
hours	x	x
inspect
invalidAt
isAfter	x	x
isBefore	x	x
isBetween	x	x
isDST	x	x
isDSTShifted	(3)	(3)
isLeapYear	x	x
isLocal	x	x
isSame
isSameOrAfter
isSameOrBefore
isUTC	x	x
isUtc	x	x
isUtcOffset
isValid	x	x
isoWeek	x	x
isoWeekYear	x	x
isoWeekday	x	x
isoWeeks	x	x
isoWeeksInYear	x	x
lang	(3)	(3)
local
locale	x	x
localeData
max	x	(1)
millisecond	x	x
milliseconds	x	x
min	x	(1)
minute	x	x
minutes	x	x
month	x	x
months	x	x
parseZone
parsingFlags
quarter	x	x
quarters	x	x
second	x	x
seconds	x	x
set	x	x
startOf	x	x
subtract	x	x
to	x	x
toArray	x
toDate	x	x
toISOString	x	x
toJSON	x	x
toNow	x	x
toObject	x	x
toString	x	x
tz	x
unix	x	x
utc	x	x
utcOffset	x	x
valueOf	x	x
week	x	x
weekYear	x	x
weekday	x	x
weeks	x	x
weeksInYear	x	x
year	x	x
years	x	x
zone	(3)	(3)
zoneAbbr	(3)	(3)
zoneName	(3)	(3)