Added DateTime[Immutable]::[get|set]Microseconds

[marc-mabe]

Follow up of #12413 to manage handling microseconds without precision loss or stringifying/parsing from string.

[derickr]

I am a little on the fence about the API here.

How often do you need to set only microseconds? Should, instead of adding setMicroseconds, this be a second optional argument on setTimestamp?

And of course, setTime() already has the microsecond argument too.

We don't have any setters for any of the other single date/time fields either.

[marc-mabe]

Hi @derickr,

I am a little on the fence about the API here.

How often do you need to set only microseconds?

There are two different cases based on what to create a DateTime object from:

1. Parsing from string
2. Instantiating from another computer time source

The second case might by another DateTime object, which is covered by createFrom[Interface|Mutable] but else you are basically forced to stringify and parse instead. Most of the time you have something as simple as unix timestamps evtl. together with fractions in whatever precision.
#12413 should already address most cases.
With this PR I'm trying to improve even more to also cover cases for passing timestamps and fractions part around.
-> DateTime::createFromTimestamp($ts)->setMicroseconds($usec)

Should, instead of adding setMicroseconds, this be a second optional argument on setTimestamp?

For me there are to reasons here to not add a second argument to setTimestamp:

1. Setter would have additional feature over getTimestamp but this can not simply done on a getter
2. Similar to createFromTimestamp(int|float $ts) I would like to allow float for setTimestamp as well which on the other hand opens questions on handling fractions part twice (e.g. setTimestamp(1.1, 1))

And of course, setTime() already has the microsecond argument too.

With setTime() you can't set the microseconds without knowing the hour, minute and second in your TZ as well which might be cumbersome.

We don't have any setters for any of the other single date/time fields either.

Personally I would like to have other getters and setters as well but this is definitively out of scope of this PR and might be better maintainable for libs like Carbon. Not sure.
For now I'm focusing on improving the case of passing times around different sources / targets.

[derickr]

You have me convinced with the API :-)

However, we don't have any tests in this PR yet! And these we need.

[marc-mabe]

@derickr

You have me convinced with the API :-)

nice :)

However, we don't have any tests in this PR yet! And these we need.

True, now added

[derickr]

One nit about the test file, and after my earlier merge this now has a conflict. So could you please rebase (and feel free to force-push to your personal branch) and fix the conflicts?

[marc-mabe]

@derickr rebased and fixed your comments now

[derickr]

LGTM, but trying to sort out the test failure before merging.

[marc-mabe]

@derickr This was unrelated - Just rebased again and now everything is green 🎉

[marc-mabe]

Also use zend_argument_error as suggested by @iluuu1994 here #12775 (comment) and added NEWS and UPGRADING entry.

[vudaltsov]

Just an idea. What if we add new features to DateTimeImmutable only? That would encourage people to stop using mutable DateTime.

[marc-mabe]

Introducing inconsistency isn't making anything better. If you want to see the mutable class go away, an RFC deprecating it would be a better way and if you are on it deprecating the function interface would be something I support.

[vudaltsov]

@marc-mabe, yes, agree.

@derickr, I remember your tweet about datetime deprecations. Have you decided anything?

[marc-mabe]

Rebased the PR. The test failure is unrelated due to #13299.

@derickr @iluuu1994 can this PR be merged now?

[kocsismate]

I know I'm late to the party, but the 2 methods should share the same implementation, shouldn't they? Only ~2-3 lines differ, which could be handled easily one way or another.