Initial commit

vendor/fakerphp/faker/src/Faker/Extension/DateTimeExtension.php

@@ -0,0 +1,242 @@
+<?php
+
+namespace Faker\Extension;
+
+/**
+ * FakerPHP extension for Date-related randomization.
+ *
+ * Functions accepting a date string use the `strtotime()` function internally.
+ *
+ * @experimental
+ *
+ * @since 1.20.0
+ */
+interface DateTimeExtension
+{
+    /**
+     * Get a DateTime object between January 1, 1970, and `$until` (defaults to "now").
+     *
+     * @param \DateTime|int|string $until    maximum timestamp, defaults to "now"
+     * @param string|null          $timezone zone timezone for generated date, fallback to `DateTime::$defaultTimezone` and `date_default_timezone_get()`.
+     *
+     * @see \DateTimeZone
+     * @see http://php.net/manual/en/timezones.php
+     * @see http://php.net/manual/en/function.date-default-timezone-get.php
+     *
+     * @example DateTime('2005-08-16 20:39:21')
+     */
+    public function dateTime($until = 'now', ?string $timezone = null): \DateTime;
+
+    /**
+     * Get a DateTime object for a date between January 1, 0001, and now.
+     *
+     * @param \DateTime|int|string $until    maximum timestamp, defaults to "now"
+     * @param string|null          $timezone zone timezone for generated date, fallback to `DateTime::$defaultTimezone` and `date_default_timezone_get()`.
+     *
+     * @example DateTime('1265-03-22 21:15:52')
+     *
+     * @see http://php.net/manual/en/timezones.php
+     * @see http://php.net/manual/en/function.date-default-timezone-get.php
+     */
+    public function dateTimeAD($until = 'now', ?string $timezone = null): \DateTime;
+
+    /**
+     * Get a DateTime object a random date between `$from` and `$until`.
+     * Accepts date strings that can be recognized by `strtotime()`.
+     *
+     * @param \DateTime|string     $from     defaults to 30 years ago
+     * @param \DateTime|int|string $until    maximum timestamp, defaults to "now"
+     * @param string|null          $timezone zone timezone for generated date, fallback to `DateTime::$defaultTimezone` and `date_default_timezone_get()`.
+     *
+     * @see \DateTimeZone
+     * @see http://php.net/manual/en/timezones.php
+     * @see http://php.net/manual/en/function.date-default-timezone-get.php
+     */
+    public function dateTimeBetween($from = '-30 years', $until = 'now', ?string $timezone = null): \DateTime;
+
+    /**
+     * Get a DateTime object based on a random date between `$from` and an interval.
+     * Accepts date string that can be recognized by `strtotime()`.
+     *
+     * @param \DateTime|int|string $from     defaults to 30 years ago
+     * @param string               $interval defaults to 5 days after
+     * @param string|null          $timezone zone timezone for generated date, fallback to `DateTime::$defaultTimezone` and `date_default_timezone_get()`.
+     *
+     * @see \DateTimeZone
+     * @see http://php.net/manual/en/timezones.php
+     * @see http://php.net/manual/en/function.date-default-timezone-get.php
+     */
+    public function dateTimeInInterval($from = '-30 years', string $interval = '+5 days', ?string $timezone = null): \DateTime;
+
+    /**
+     * Get a date time object somewhere inside the current week.
+     *
+     * @param \DateTime|int|string $until    maximum timestamp, defaults to "now"
+     * @param string|null          $timezone zone timezone for generated date, fallback to `DateTime::$defaultTimezone` and `date_default_timezone_get()`.
+     *
+     * @see \DateTimeZone
+     * @see http://php.net/manual/en/timezones.php
+     * @see http://php.net/manual/en/function.date-default-timezone-get.php
+     */
+    public function dateTimeThisWeek($until = 'now', ?string $timezone = null): \DateTime;
+
+    /**
+     * Get a date time object somewhere inside the current month.
+     *
+     * @param \DateTime|int|string $until    maximum timestamp, defaults to "now"
+     * @param string|null          $timezone timezone for generated date, fallback to `DateTime::$defaultTimezone` and `date_default_timezone_get()`.
+     *
+     * @see \DateTimeZone
+     * @see http://php.net/manual/en/timezones.php
+     * @see http://php.net/manual/en/function.date-default-timezone-get.php
+     */
+    public function dateTimeThisMonth($until = 'now', ?string $timezone = null): \DateTime;
+
+    /**
+     * Get a date time object somewhere inside the current year.
+     *
+     * @param \DateTime|int|string $until    maximum timestamp, defaults to "now"
+     * @param string|null          $timezone timezone for generated date, fallback to `DateTime::$defaultTimezone` and `date_default_timezone_get()`.
+     *
+     * @see \DateTimeZone
+     * @see http://php.net/manual/en/timezones.php
+     * @see http://php.net/manual/en/function.date-default-timezone-get.php
+     */
+    public function dateTimeThisYear($until = 'now', ?string $timezone = null): \DateTime;
+
+    /**
+     * Get a date time object somewhere inside the current decade.
+     *
+     * @param \DateTime|int|string $until    maximum timestamp, defaults to "now"
+     * @param string|null          $timezone timezone for generated date, fallback to `DateTime::$defaultTimezone` and `date_default_timezone_get()`.
+     *
+     * @see \DateTimeZone
+     * @see http://php.net/manual/en/timezones.php
+     * @see http://php.net/manual/en/function.date-default-timezone-get.php
+     */
+    public function dateTimeThisDecade($until = 'now', ?string $timezone = null): \DateTime;
+
+    /**
+     * Get a date time object somewhere inside the current century.
+     *
+     * @param \DateTime|int|string $until    maximum timestamp, defaults to "now"
+     * @param string|null          $timezone timezone for generated date, fallback to `DateTime::$defaultTimezone` and `date_default_timezone_get()`.
+     *
+     * @see \DateTimeZone
+     * @see http://php.net/manual/en/timezones.php
+     * @see http://php.net/manual/en/function.date-default-timezone-get.php
+     */
+    public function dateTimeThisCentury($until = 'now', ?string $timezone = null): \DateTime;
+
+    /**
+     * Get a date string between January 1, 1970, and `$until`.
+     *
+     * @param string               $format DateTime format
+     * @param \DateTime|int|string $until  maximum timestamp, defaults to "now"
+     *
+     * @see https://www.php.net/manual/en/datetime.format.php
+     */
+    public function date(string $format = 'Y-m-d', $until = 'now'): string;
+
+    /**
+     * Get a time string (24h format by default).
+     *
+     * @param string               $format DateTime format
+     * @param \DateTime|int|string $until  maximum timestamp, defaults to "now"
+     *
+     * @see https://www.php.net/manual/en/datetime.format.php
+     */
+    public function time(string $format = 'H:i:s', $until = 'now'): string;
+
+    /**
+     * Get a UNIX (POSIX-compatible) timestamp between January 1, 1970, and `$until`.
+     *
+     * @param \DateTime|int|string $until maximum timestamp, defaults to "now"
+     */
+    public function unixTime($until = 'now'): int;
+
+    /**
+     * Get a date string according to the ISO-8601 standard.
+     *
+     * @param \DateTime|int|string $until maximum timestamp, defaults to "now"
+     */
+    public function iso8601($until = 'now'): string;
+
+    /**
+     * Get a string containing either "am" or "pm".
+     *
+     * @param \DateTime|int|string $until maximum timestamp, defaults to "now"
+     *
+     * @example 'am'
+     */
+    public function amPm($until = 'now'): string;
+
+    /**
+     * Get a localized random day of the month.
+     *
+     * @param \DateTime|int|string $until maximum timestamp, defaults to "now"
+     *
+     * @example '16'
+     */
+    public function dayOfMonth($until = 'now'): string;
+
+    /**
+     * Get a localized random day of the week.
+     *
+     * Uses internal DateTime formatting, hence PHP's internal locale will be used (change using `setlocale()`).
+     *
+     * @param \DateTime|int|string $until maximum timestamp, defaults to "now"
+     *
+     * @example 'Tuesday'
+     *
+     * @see setlocale
+     * @see https://www.php.net/manual/en/function.setlocale.php Set a different output language
+     */
+    public function dayOfWeek($until = 'now'): string;
+
+    /**
+     * Get a random month (numbered).
+     *
+     * @param \DateTime|int|string $until maximum timestamp, defaults to "now"
+     *
+     * @example '7'
+     */
+    public function month($until = 'now'): string;
+
+    /**
+     * Get a random month.
+     *
+     * @param \DateTime|int|string $until maximum timestamp, defaults to "now"
+     *
+     * @see setlocale
+     * @see https://www.php.net/manual/en/function.setlocale.php Set a different output language
+     *
+     * @example 'September'
+     */
+    public function monthName($until = 'now'): string;
+
+    /**
+     * Get a random year between 1970 and `$until`.
+     *
+     * @param \DateTime|int|string $until maximum timestamp, defaults to "now"
+     *
+     * @example '1987'
+     */
+    public function year($until = 'now'): string;
+
+    /**
+     * Get a random century, formatted as Roman numerals.
+     *
+     * @example 'XVII'
+     */
+    public function century(): string;
+
+    /**
+     * Get a random timezone, uses `\DateTimeZone::listIdentifiers()` internally.
+     *
+     * @param string|null $countryCode two-letter ISO 3166-1 compatible country code
+     *
+     * @example 'Europe/Rome'
+     */
+    public function timezone(?string $countryCode = null): string;
+}