Add factory methods for DatePeriod and ReflectionMethod

[kocsismate]

This PR proposes to add the following factory methods:

class DatePeriod
{
    public static function createFromRecurrences(DateTimeInterface $start, DateInterval $interval, int $recurrences, int $options = 0): static {}

    public static function createFromDates(DateTimeInterface $start, DateInterval $interval, DateTimeInterface $end, int $options = 0): static {}

    public static function createFromIso8601(string $specification, int $options = 0): static {}
}

class ReflectionMethod
{
    public static function createFromMethodName(string $method): static {}
}

The longer-term advantage of these added methods is that we could get rid of the overloaded signatures of DatePeriod::__construct() and ReflectionMethod::__construct() in PHP 9 after a deprecation phase in PHP 8.x (https://wiki.php.net/rfc/deprecations_php_8_1#dateperiodconstruct and https://wiki.php.net/rfc/deprecations_php_8_1#passing_a_method_name_as_the_first_parameter_to_reflectionmethodconstruct).

P.S. I don't have any strong preference about the method names, and the current ones should be considered as WIP ones. :)

[kocsismate]

other candidates I thought about: createBetweenDates, createBetweenStartAndEnd, createFromStartAndEnd

[derickr]

I think I would prefer createFromStartAndEnd, and I would also switch the order of arguments to:

    public static function createFromStartAndEnd(DateTimeInterface $start, DateTimeInterface $end, DateInterval $interval, int $options = 0): static {}

[nyamsprod]

Another suggestion would be to use createFromEndpoints or createFromDatepoints to imply that the DatePeriod endpoints are expressed using DateTimeInterface objects.

[kocsismate]

I think we should decide what to do with the overloaded constructor:

• do nothing so that the overloaded signature remains supported forever
• deprecate it in 8.x and remove it in 9.0 altogether
• choose one "canonical" signature, deprecate the others in 8.x, and get rid of them in 9.0

Depending on the outcome, we could only have 2 factory methods, and the 3rd signature could be implemented by the constructor

[kocsismate]

@nikic Now that there is an implementation for these methods... Do you think it's a good idea to vote about their inclusion in PHP 8.1 and the deprecation of the related constructor behavior in PHP 8.2 as part of the 8.1 Deprecations RFC?

[derickr]

I would prefer it if this initialisation function gets split as well. The old __construct should use the new (3) initialisation methods, which also makes it easier to clean up in for example PHP 9.0. It can also mean that error and bounds checking (for example, recurrences can't be negative) to the right and logical position.

[iluuu1994]

@kocsismate Are there plans to pursue this RFC?

[kocsismate]

@iluuu1994 yes, absolutely! My plan is to first fix the easier issues in stubs (mostly declaring the missing constants) and then continue with the improvements which need more thinking.

[jurchiks]

My suggestions for the methods:

class DatePeriod
{
    public function __construct(string $isoRecurringInterval, int $options = 0)

    public static function fromStartAndEnd(DateTimeInterface $start, DateInterval $interval, DateTimeInterface $end, int $options = 0): static

    public static function fromStartAndRecurrences(DateTimeInterface $start, DateInterval $interval, int $recurrences, int $options = 0): static

    public static function fromEndAndRecurrences(DateTimeInterface $end, DateInterval $interval, int $recurrences, int $options = 0): static

    public function __toString(): string // returns ISO8601 formatted recurring interval
}

I'm pretty sure that the static methods are in order of popularity as written here, although perhaps that can be researched (though constructor overloads make this problematic).
IMO the prefix create is completely redundant and adds no extra meaning to the already pretty clear name. I don't believe you can misunderstand what DatePeriod::fromStartAndRecurrences(...) will do; it's a static method that returns an instance of DatePeriod, obviously it's going to "create" the new instance because it can't come from anywhere else, there's no need to explicitly say it. It's also closer to natural language: "date period from start and occurrences" vs "date period create from start and occurrences"; the latter one just sounds weird.

In addition to that, having the string constructor be the main default one, and having a __toString method would enable easy and convenient serializing/unserializing to/from database.

P.S. I don't understand why including the end date is opt-in; to me it makes far more sense for it to be opt-out, same as EXCLUDE_START_DATE.

[kocsismate]

Closing in favor of #11703