Added better stubs for DateTimeImmutable, highlighting how the constructor is **NOT** immutable

[Ocramius]

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

$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);

[Ocramius]

Note: this sparked from initial conversations on slack: I don't really know if I should change the existing CallMap files, after adjusting this stub.

/cc @guidobonuzzi, since you may be interested.

[Ocramius]

Interesting finding: DateTimeImmutable#format() always produces a string, no matter what you pass to it.

I took the occasion to refine that non-empty-string input will lead to non-empty-string output :-)

Ref: 68ffae0

[Ocramius]

@AndrolGenhald @orklah this is now ready, IMO: thanks for all the support! 👍

[orklah]

Could you please keep the content of callmaps please? I'm not entirely sure we can drop it, and even if we could, there's no harm to have a comprehensive list if needed some day

[Ocramius]

I think it's duplicated at this point: shouldn't be kept, if what you said about priority is true.

What value does the added info provide, considering that each removal contains documentation/references?

[orklah]

Fine then :p Thanks!

[Ocramius]

Thanks @orklah!