Skip to content

Commit

Permalink
Added value type information for iterable parameters.
Browse files Browse the repository at this point in the history 
Updated Provider Interface with required methods. (Not sure if this is preferred; may consider reworking this interface in the future)
  • Loading branch information
@stelgenhof
stelgenhof committed Sep 5, 2021
1 parent 7336e93 commit d932e3e
Show file tree
Hide file tree
Showing 6 changed files with 65 additions and 52 deletions.
4 changes: 3 additions & 1 deletion src/Yasumi/Holiday.php
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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<string>|null $locales The locales to search for translations
*
* @throws MissingTranslationException
*
Expand Down Expand Up @@ -237,6 +237,8 @@ public function mergeGlobalTranslations(TranslationsInterface $globalTranslation
*
* @param array<string>|null $locales Array of locales, or null if the display locale should be used
*
* @return array<string> an array of locales to check for translations
*
* @see Holiday::DEFAULT_LOCALE
* @see Holiday::LOCALE_KEY
*/
Expand Down
32 changes: 4 additions & 28 deletions src/Yasumi/Provider/AbstractProvider.php
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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);
Expand Down Expand Up @@ -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;
Expand All @@ -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
Expand Down Expand Up @@ -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<string> list of all holiday dates defined for the given year
*/
protected function getHolidayDates(): array
{
Expand Down
35 changes: 35 additions & 0 deletions src/Yasumi/ProviderInterface.php
View file
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,8 @@

namespace Yasumi;

use Yasumi\Exception\InvalidDateException;

/**
* Interface ProviderInterface - Holiday provider interface.
*
Expand All @@ -35,4 +37,37 @@ public function initialize(): void;
* @return array<string> 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;
}
22 changes: 11 additions & 11 deletions src/Yasumi/SubstituteHoliday.php
View file
Original file line number Diff line number Diff line change
Expand Up @@ -38,7 +38,7 @@ class SubstituteHoliday extends Holiday
public $substitutedHoliday;

/**
* @var array list of translations of the "{0} observed" pattern
* @var array<string> list of translations of the "{0} observed" pattern
*/
public $substituteHolidayTranslations;

Expand All @@ -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<string, string> $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
Expand Down Expand Up @@ -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<string>|null $locales The locales to search for translations
*
* @throws MissingTranslationException
*
Expand Down
8 changes: 4 additions & 4 deletions src/Yasumi/Translations.php
View file
Original file line number Diff line number Diff line change
Expand Up @@ -25,19 +25,19 @@
class Translations implements TranslationsInterface
{
/**
* @var array translations array: ['<holiday key>' => ['<locale>' => 'translation', ...], ... ]
* @var array<string, array> translations array: ['<holiday key>' => ['<locale>' => 'translation', ...], ... ]
*/
public $translations = [];

/**
* @var array list of all defined locales
* @var array<string> list of all defined locales
*/
private $availableLocales;

/**
* Constructor.
*
* @param array $availableLocales list of all defined locales
* @param array<string> $availableLocales list of all defined locales
*/
public function __construct(array $availableLocales)
{
Expand Down Expand Up @@ -128,7 +128,7 @@ public function getTranslation(string $key, string $locale): ?string
*
* @param string $key holiday key
*
* @return array holiday name translations ['<locale>' => '<translation>', ...]
* @return array<string, string> holiday name translations ['<locale>' => '<translation>', ...]
*/
public function getTranslations(string $key): array
{
Expand Down
16 changes: 8 additions & 8 deletions src/Yasumi/Yasumi.php
View file
Original file line number Diff line number Diff line change
Expand Up @@ -38,7 +38,7 @@ class Yasumi
public const YEAR_UPPER_BOUND = 9999;

/**
* @var array list of all defined locales
* @var array<string> list of all defined locales
*/
private static $locales = [];

Expand All @@ -52,7 +52,7 @@ class Yasumi
/**
* Provider class to be ignored (Abstract, trait, other).
*
* @var array
* @var array<string>
*/
private static $ignoredProvider = [
'AbstractProvider.php',
Expand Down Expand Up @@ -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));
Expand Down Expand Up @@ -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<string> list of available locales
*/
public static function getAvailableLocales(): array
{
Expand All @@ -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
Expand All @@ -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])) {
Expand All @@ -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<string> list of available holiday providers
*
* @throws \ReflectionException
*/
Expand Down

0 comments on commit d932e3e

Please sign in to comment.