>DateTimeImmutable::modify — Alters the timestamp
As you have said, it creates a copy, it doesn't alter the object.
Compare it to Python documentation, ex. str.capitalize()[1]:
>Return a copy of the string with its first character capitalized and the rest lowercased.
[1]: https://docs.python.org/3/library/stdtypes.html#str.capitali...
The old datetime's method modifies the object in place[-1], if you replace the old with the new it's not going to work anymore.
> Besides - what would you call a method that modifies a timestamp?
Replace[0]? withFieldValue[1]? add with a delta object, possibly relative[2]?
[-1] it also returns the object it was called on since 5.3.0, the method was introduced in 5.2.0
[0] https://docs.python.org/2/library/datetime.html#datetime.dat...
[1] http://joda-time.sourceforge.net/apidocs/org/joda/time/DateT...
[2] http://msdn.microsoft.com/en-us/library/system.datetime.add(...
Of course it would be impossible to make the APIs exactly the same, because the two classes have different behaviour. But shouldn't they at least strive to make the APIs as similar as possible?
No, not when the behavior is completely dissimilar and the method name is highly misleading.
> This class behaves the same as DateTime except it never modifies itself but returns a new object instead.
All the old datetime's methods modify the object in place, while none of DateTimeImmutable's methods do. It's not meant to be a drop-in replacement.
current_minute = datetime.utcnow().replace(second=0, microsecond=0)
While the naming is a bit unfortunate, this isn't different from other languages that have immutable types like Java String which also have methods that act on the string they are called on and return a new copy.
Like concat().
And with datetimeimmutable: Python strings work the same. And all the ruby string methods not ending with a bang also work the same.The reason why the method is called 'modify' in PHP is because the old DateTime (mutable edition™) method was also called 'modify' and the two should be more or less drop-in replacements.
Besides - what would you call a method that modifies a timestamp?