While there is value in declaring `DateTimeImmutable::createFromInterface()` as mutation-free in
a stub, this method was introduced in PHP 8.0, so we cannot really declare it in a stub.
For now, we drop it, as the value of its stub declaration is much lower than the problems it
introduces through its conditional existence.
Also:
* a non-empty format string will always lead to `non-empty-string`
* it seems that you can throw **everything** at `DateTimeInterface#format()`, even null bytes,
and it will always produce a `string`
Also simplified the return type from `static|false` to `static`, since
the method throws at all times, on failure.
On PHP 7.x, it could only fail if an invalid type was passed in, which is
not really valid anyway, from a type perspective.
Ref (PHP 8.1.x): 32d55f7422/ext/date/php_date.c (L3353-L3369)
Ref (PHP 7.0.33): bf574c2b67/ext/date/php_date.c (L3596-L3612)
Also simplified the return type from `static|false` to `static`, since
the method throws at all times, on failure.
On PHP 7.x, it could only fail if an invalid type was passed in, which is
not really valid anyway, from a type perspective.
Ref (PHP 8.1.x): 32d55f7422/ext/date/php_date.c (L3308-L3324)
Ref (PHP 7.0.33): bf574c2b67/ext/date/php_date.c (L3549-L3565)
Also simplified the return type from `static|false` to `static`, since
the method throws at all times, on failure.
On PHP 7.x, it could only fail if an invalid type was passed in, which is
not really valid anyway, from a type perspective.
Ref (PHP 8.1.x): 32d55f7422/ext/date/php_date.c (L3258-L3274)
Ref (PHP 7.0.33): bf574c2b67/ext/date/php_date.c (L3496-L3512)
Also simplified the return type from `static|false` to `static`, since
the method throws at all times, on failure.
On PHP 7.x, it could only fail if an invalid type was passed in, which is
not really valid anyway, from a type perspective.
Ref (PHP 8.1.x): 32d55f7422/ext/date/php_date.c (L3212-L3228)
Ref (PHP 7.0.33): bf574c2b67/ext/date/php_date.c (L3447-L3463)
Also expanded the return type from `static` to `static|false`, since the
operation can fail (with a warning too), such as in following example:
https://3v4l.org/Xrjlc
```php
<?php
var_dump(
(new DateTimeImmutable())
->modify('potato')
);
```
Produces
```
Warning: DateTimeImmutable::modify(): Failed to parse time string (potato) at position 0 (p): The timezone could not be found in the database in /in/Xrjlc on line 6
bool(false)
```
Ref: 534127d3b2/ext/date/php_date.stub.php (L508-L509)
Ref: c205d652d1 (r934032422)
The idea is that `@psalm-pure` disallows `$this` usage in child classes,
which is not wanted, while `@psalm-mutation-free` allows it.
By using `@psalm-mutation-free`, we don't completely destroy inheritance
use-cases based on internal (immutable) state.
`DateTimeImmutable` is **almost** immutable: `DateTimeImmutable::__construct()` is in fact not a pure
method, since `new DateTimeImmutable('now')` produces a different value at each instantiation (by design).
This change makes sure that `DateTimeImmutable` loses its `@psalm-immutable` class-level marker,
preventing downstream misuse of the constructor inside otherwise referentially transparent code.
Note: only pure methods are stubbed here: all other methods declared by `DateTimeImmutable` (parent interface)
are NOT present here, and are either inferred from runtime reflection, or `CallMap*.php` definitions.
Methods are sorted in the order defined by reflection on PHP 8.1.8, at the time of writing this ( https://3v4l.org/3TGg8 ).
Following simplistic snippet was used to infer the current signature:
```php
<?php
$c = new \ReflectionClass(\DateTimeImmutable::class);
$methods = array_map(function ($m) {
return $m->getName()
. '(' . implode(',', array_map(function ($p) {
return $p->getType()
. ' $' . $p->getName()
. ($p->isOptional() ? ' = ' . var_export($p->getDefaultValue(), true) : '');
}, $m->getParameters())) . ')' . ($m->getReturnType() ? (': ' . $m->getReturnType()) : '');
}, $c->getMethods());
$properties = array_map(function ($m) {
return $m->getName();
}, $c->getProperties());
var_dump($methods, $properties);
```
