PHP DateTimeImmutable::modify()(php.net)
php.net
PHP DateTimeImmutable::modify()
http://www.php.net/manual/en/datetimeimmutable.modify.php
2 comments
Some discussion about this method at http://derickrethans.nl/immutable-datetime.html
That seems to explain the logic of having an immutable DateTime type (to avoid breaking backwards compatibility with the inherently mutable old DateTime) but doesn't explain the logic of then including a modify() method for such objects.
"Immutable" probably isn't the right description.
"Immutable" probably isn't the right description.
objects of the DateTimeImmutable class are immutable. All methods that modify the object will return a new copy.
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().
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?
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().
String foo = "foo";
String foobar = foo.concat("bar");
// foo is still set to "foo"
$date = new DateTimeImmutable();
$other_date = $date->modify('+ 3 days');
// $date still is today.
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?
The documentation is ambiguous:
>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...
>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 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.
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(...
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(...
> 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.
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?
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?
> 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.
No, not when the behavior is completely dissimilar and the method name is highly misleading.
The behaviour is not completely dissimilar. The only difference between the two methods is what is done with the result. In fact, every method in that class parallels one from the other class in exactly that way, and that behaviour is described clearly on the documentation page for the class:
> This class behaves the same as DateTime except it never modifies itself but returns a new object instead.
http://www.php.net/manual/en/class.datetimeimmutable.php
> This class behaves the same as DateTime except it never modifies itself but returns a new object instead.
http://www.php.net/manual/en/class.datetimeimmutable.php
> 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.
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.
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.
but then why keep a confusing name and documentation instead of just using something like `withModification` ?
Python does something similar with NamedTuple.replace(). This isn't just some weird crazy PHP thing, as much as people love to rag on PHP.
More relevantly, Python does something similar with datetime.replace():
current_minute = datetime.utcnow().replace(second=0, microsecond=0)
current_minute = datetime.utcnow().replace(second=0, microsecond=0)
$date->modifiedDate('+ 3 days');The method returns a new instance, so it is still immutable, technically.
Then the whole thing is redundant.
If clone $var = DateTimeImmutable->modify()
Then this really doesn't solve anything.
If clone $var = DateTimeImmutable->modify()
Then this really doesn't solve anything.
Let's compare the old thing:
This means that you have to be very defensive, constantly calling clone() or you'll have your dates altered behind your back from some library that's called by a library you're calling.
$date = new DateTime();
$other_date = $date->modify('+ 1 day');
// $date is now tomorrow
$date = new DateTimeImmutable();
$other_date = $date->modify('+ 1 day');
// $date is still today
This means that you have to be very defensive, constantly calling clone() or you'll have your dates altered behind your back from some library that's called by a library you're calling.
This is one of those things that seems hilarious only because you are ignorant of what's actually happening. Being proud of finding this funny is being proud of your own ignorance.
You could explain what's actually happening instead of ridiculing people for not knowing.
According to the comments it returned a modified immutable date. The original date is not modified.
Poor function naming perhaps, (should be `modified()`), but it's not really one of the things that makes PHP infamous.
Poor function naming perhaps, (should be `modified()`), but it's not really one of the things that makes PHP infamous.