From d932e3e23acab82d9e278922ea03007412dc1b8e Mon Sep 17 00:00:00 2001 From: Sacha Telgenhof Date: Sun, 5 Sep 2021 14:15:42 +0900 Subject: [PATCH] Added value type information for iterable parameters. Updated Provider Interface with required methods. (Not sure if this is preferred; may consider reworking this interface in the future) --- src/Yasumi/Holiday.php | 4 ++- src/Yasumi/Provider/AbstractProvider.php | 32 +++------------------- src/Yasumi/ProviderInterface.php | 35 ++++++++++++++++++++++++ src/Yasumi/SubstituteHoliday.php | 22 +++++++-------- src/Yasumi/Translations.php | 8 +++--- src/Yasumi/Yasumi.php | 16 +++++------ 6 files changed, 65 insertions(+), 52 deletions(-) diff --git a/src/Yasumi/Holiday.php b/src/Yasumi/Holiday.php index 09cbb0e64..9a4b1364d 100755 --- a/src/Yasumi/Holiday.php +++ b/src/Yasumi/Holiday.php @@ -191,7 +191,7 @@ public function jsonSerialize(): self * If no locale is provided, proceed as if an array containing the display locale, Holiday::DEFAULT_LOCALE ('en_US'), and * Holiday::LOCALE_KEY (the holiday key) was provided. * - * @param array|null $locales The locales to search for translations + * @param array|null $locales The locales to search for translations * * @throws MissingTranslationException * @@ -237,6 +237,8 @@ public function mergeGlobalTranslations(TranslationsInterface $globalTranslation * * @param array|null $locales Array of locales, or null if the display locale should be used * + * @return array an array of locales to check for translations + * * @see Holiday::DEFAULT_LOCALE * @see Holiday::LOCALE_KEY */ diff --git a/src/Yasumi/Provider/AbstractProvider.php b/src/Yasumi/Provider/AbstractProvider.php index cc31c2c5a..79338e321 100755 --- a/src/Yasumi/Provider/AbstractProvider.php +++ b/src/Yasumi/Provider/AbstractProvider.php @@ -150,19 +150,7 @@ public function removeHoliday(string $key): void unset($this->holidays[$key]); } - /** - * Determines whether a date represents a working day or not. - * - * A working day is defined as a day that is not a holiday nor falls in the weekend. The index of the weekdays of - * the defined date is used for establishing this (0 = Sunday, 1 = Monday, etc.) - * - * @param \DateTimeInterface $date any date object that implements the DateTimeInterface (e.g. Yasumi\Holiday, - * \DateTime) - * - * @return bool true if date represents a working day, otherwise false - * - * @throws InvalidDateException - */ + /** {@inheritdoc} */ public function isWorkingDay(\DateTimeInterface $date): bool { return !$this->isHoliday($date) && !$this->isWeekendDay($date); @@ -287,11 +275,7 @@ public function getHolidayNames(): array return array_keys($this->holidays); } - /** - * Returns the current year set for this Holiday calendar. - * - * @return int the year set for this Holiday calendar - */ + /** @inheritdoc */ public function getYear(): int { return $this->year; @@ -316,15 +300,7 @@ public function next(string $key): ?Holiday return $this->anotherTime($this->year + 1, $key); } - /** - * Retrieves the holiday object for the given holiday. - * - * @param string $key the name of the holiday - * - * @return Holiday|null a Holiday instance for the given holiday - * - * @throws InvalidArgumentException when the given name is blank or empty - */ + /** {@inheritdoc} */ public function getHoliday(string $key): ?Holiday { $this->isHolidayNameNotEmpty($key); // Validate if key is not empty @@ -414,7 +390,7 @@ public function on(\DateTimeInterface $date): OnFilter /** * Gets all the holiday dates defined by this holiday provider (for the given year). * - * @return array list of all holiday dates defined for the given year + * @return array list of all holiday dates defined for the given year */ protected function getHolidayDates(): array { diff --git a/src/Yasumi/ProviderInterface.php b/src/Yasumi/ProviderInterface.php index 93a340460..89d8f6c6f 100755 --- a/src/Yasumi/ProviderInterface.php +++ b/src/Yasumi/ProviderInterface.php @@ -14,6 +14,8 @@ namespace Yasumi; +use Yasumi\Exception\InvalidDateException; + /** * Interface ProviderInterface - Holiday provider interface. * @@ -35,4 +37,37 @@ public function initialize(): void; * @return array a list of external sources (empty when no sources are defined) */ public function getSources(): array; + + /** + * Returns the current year set for this Holiday calendar. + * + * @return int the year set for this Holiday calendar + */ + public function getYear(): int; + + /** + * Determines whether a date represents a working day or not. + * + * A working day is defined as a day that is not a holiday nor falls in the weekend. The index of the weekdays of + * the defined date is used for establishing this (0 = Sunday, 1 = Monday, etc.) + * + * @param \DateTimeInterface $date any date object that implements the DateTimeInterface (e.g. Yasumi\Holiday, + * \DateTime) + * + * @return bool true if date represents a working day, otherwise false + * + * @throws InvalidDateException + */ + public function isWorkingDay(\DateTimeInterface $date): bool; + + /** + * Retrieves the holiday object for the given holiday. + * + * @param string $key the name of the holiday + * + * @return Holiday|null a Holiday instance for the given holiday + * + * @throws \InvalidArgumentException when the given name is blank or empty + */ + public function getHoliday(string $key): ?Holiday; } diff --git a/src/Yasumi/SubstituteHoliday.php b/src/Yasumi/SubstituteHoliday.php index f6f83d88d..947e2f1f3 100755 --- a/src/Yasumi/SubstituteHoliday.php +++ b/src/Yasumi/SubstituteHoliday.php @@ -38,7 +38,7 @@ class SubstituteHoliday extends Holiday public $substitutedHoliday; /** - * @var array list of translations of the "{0} observed" pattern + * @var array list of translations of the "{0} observed" pattern */ public $substituteHolidayTranslations; @@ -48,15 +48,15 @@ class SubstituteHoliday extends Holiday * If a holiday date needs to be defined for a specific timezone, make sure that the date instance * (DateTimeInterface) has the correct timezone set. Otherwise, the default system timezone is used. * - * @param Holiday $substitutedHoliday The holiday being substituted - * @param array $names An array containing the name/description of this holiday - * in various languages. Overrides global translations - * @param \DateTimeInterface $date A DateTimeInterface instance representing the date of the holiday - * @param string $displayLocale Locale (i.e. language) in which the holiday information needs to - * be displayed in. (Default 'en_US') - * @param string $type The type of holiday. Use the following constants: TYPE_OFFICIAL, - * TYPE_OBSERVANCE, TYPE_SEASON, TYPE_BANK or TYPE_OTHER. By default, - * an official holiday is considered. + * @param Holiday $substitutedHoliday The holiday being substituted + * @param array $names An array containing the name/description of this holiday + * in various languages. Overrides global translations + * @param \DateTimeInterface $date A DateTimeInterface instance representing the date of the holiday + * @param string $displayLocale Locale (i.e. language) in which the holiday information needs to + * be displayed in. (Default 'en_US') + * @param string $type The type of holiday. Use the following constants: TYPE_OFFICIAL, + * TYPE_OBSERVANCE, TYPE_SEASON, TYPE_BANK or TYPE_OTHER. By default, + * an official holiday is considered. * * @throws InvalidDateException * @throws UnknownLocaleException @@ -100,7 +100,7 @@ public function getSubstitutedHoliday(): Holiday * If no locale is provided, proceed as if an array containing the display locale, Holiday::DEFAULT_LOCALE ('en_US'), and * Holiday::LOCALE_KEY (the holiday key) was provided. * - * @param array|null $locales The locales to search for translations + * @param array|null $locales The locales to search for translations * * @throws MissingTranslationException * diff --git a/src/Yasumi/Translations.php b/src/Yasumi/Translations.php index 15d084ba2..ca02885bf 100644 --- a/src/Yasumi/Translations.php +++ b/src/Yasumi/Translations.php @@ -25,19 +25,19 @@ class Translations implements TranslationsInterface { /** - * @var array translations array: ['' => ['' => 'translation', ...], ... ] + * @var array translations array: ['' => ['' => 'translation', ...], ... ] */ public $translations = []; /** - * @var array list of all defined locales + * @var array list of all defined locales */ private $availableLocales; /** * Constructor. * - * @param array $availableLocales list of all defined locales + * @param array $availableLocales list of all defined locales */ public function __construct(array $availableLocales) { @@ -128,7 +128,7 @@ public function getTranslation(string $key, string $locale): ?string * * @param string $key holiday key * - * @return array holiday name translations ['' => '', ...] + * @return array holiday name translations ['' => '', ...] */ public function getTranslations(string $key): array { diff --git a/src/Yasumi/Yasumi.php b/src/Yasumi/Yasumi.php index 7fb5d0ae6..1c27b2c05 100755 --- a/src/Yasumi/Yasumi.php +++ b/src/Yasumi/Yasumi.php @@ -38,7 +38,7 @@ class Yasumi public const YEAR_UPPER_BOUND = 9999; /** - * @var array list of all defined locales + * @var array list of all defined locales */ private static $locales = []; @@ -52,7 +52,7 @@ class Yasumi /** * Provider class to be ignored (Abstract, trait, other). * - * @var array + * @var array */ private static $ignoredProvider = [ 'AbstractProvider.php', @@ -118,14 +118,14 @@ public static function nextWorkingDay( * between the defined lower and upper bounds. * @param string $locale The locale to use. If empty we'll use the default locale (en_US) * - * @return AbstractProvider An instance of class $class is created and returned + * @return ProviderInterface An instance of class $class is created and returned * * @throws RuntimeException If no such holiday provider is found * @throws InvalidYearException if the year parameter is not between the defined lower and upper bounds * @throws UnknownLocaleException if the locale parameter is invalid * @throws ProviderNotFoundException if the holiday provider for the given country does not exist */ - public static function create(string $class, int $year = self::YEAR_LOWER_BOUND, string $locale = self::DEFAULT_LOCALE): AbstractProvider + public static function create(string $class, int $year = self::YEAR_LOWER_BOUND, string $locale = self::DEFAULT_LOCALE): ProviderInterface { // Find and return holiday provider instance $providerClass = sprintf('Yasumi\Provider\%s', str_replace('/', '\\', $class)); @@ -165,7 +165,7 @@ public static function create(string $class, int $year = self::YEAR_LOWER_BOUND, /** * Returns a list of available locales. * - * @return array list of available locales + * @return array list of available locales */ public static function getAvailableLocales(): array { @@ -184,7 +184,7 @@ public static function getAvailableLocales(): array * integer between the defined lower and upper bounds. * @param string $locale The locale to use. If empty we'll use the default locale (en_US) * - * @return AbstractProvider An instance of class $class is created and returned + * @return ProviderInterface An instance of class $class is created and returned * * @throws RuntimeException If no such holiday provider is found * @throws InvalidArgumentException if the year parameter is not between the defined lower and upper bounds @@ -196,7 +196,7 @@ public static function createByISO3166_2( string $isoCode, int $year = self::YEAR_LOWER_BOUND, string $locale = self::DEFAULT_LOCALE - ): AbstractProvider { + ): ProviderInterface { $availableProviders = self::getProviders(); if (false === isset($availableProviders[$isoCode])) { @@ -209,7 +209,7 @@ public static function createByISO3166_2( /** * Returns a list of available holiday providers. * - * @return array list of available holiday providers + * @return array list of available holiday providers * * @throws \ReflectionException */