Rename “short name” to “key”

CHANGELOG.md

@@ -17,7 +17,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/) and this
 - Added American English spelling for Labour Day [\#216](https:/azuyalabs/yasumi/issues/216)
 - Added French translation for Second Christmas Day [\#188](https:/azuyalabs/yasumi/pull/188) ([Arkounay](https:/Arkounay))
 
-- Added accessor methods Holiday::getShortName() and SubstituteHoliday::getSubstitutedHoliday() [\#220](https:/azuyalabs/yasumi/pull/220) ([c960657](https:/c960657))
+- Added accessor methods Holiday::getKey() and SubstituteHoliday::getSubstitutedHoliday() [\#220](https:/azuyalabs/yasumi/pull/220)+[\#221](https:/azuyalabs/yasumi/pull/221) ([c960657](https:/c960657))
 - Added missing return (correct) and parameter types in various methods.
 
 ### Changed

src/Yasumi/Exception/MissingTranslationException.php

@@ -22,11 +22,11 @@ class MissingTranslationException extends BaseException implements Exception
  /**
  * Initializes the Exception instance
  *
- * @param string $shortName The short name (internal name) of the holiday
+ * @param string $key The holiday key
  * @param array $locales The locales that was searched
  */
- public function __construct(string $shortName, array $locales)
+ public function __construct(string $key, array $locales)
  {
- parent::__construct(\sprintf("Translation for '%s' not found for any locale: '%s'", $shortName, \implode("', '", $locales)));
+ parent::__construct(\sprintf("Translation for '%s' not found for any locale: '%s'", $key, \implode("', '", $locales)));
  }
 }

src/Yasumi/Filters/AbstractFilter.php

@@ -35,10 +35,10 @@ public function count(): int
  {
  $names = \array_map(static function ($holiday) {
  if ($holiday instanceof SubstituteHoliday) {
- return $holiday->getSubstitutedHoliday()->getShortName();
+ return $holiday->getSubstitutedHoliday()->getKey();
  }
 
- return $holiday->getShortName();
+ return $holiday->getKey();
  }, \iterator_to_array($this));
 
  return \count(\array_unique($names));

src/Yasumi/Holiday.php

@@ -56,19 +56,19 @@ class Holiday extends DateTime implements JsonSerializable
  public const DEFAULT_LOCALE = 'en_US';
 
  /**
- * Pseudo-locale representing the short name (internal name) of the holiday.
+ * Pseudo-locale representing the holiday key.
  */
- public const LOCALE_SHORT_NAME = 'shortName';
+ public const LOCALE_KEY = '_key';
 
  /**
  * @var array list of all defined locales
  */
  private static $locales = [];
 
  /**
- * @var string short name (internal name) of this holiday
- * @deprecated public access to this property is deprecated in favor of getShortName()
- * @see getShortName()
+ * @var string holiday key
+ * @deprecated Public access to this property is deprecated in favor of getKey()
+ * @see getKey()
  */
  public $shortName;
 
@@ -93,7 +93,7 @@ class Holiday extends DateTime implements JsonSerializable
  * 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 string $shortName The short name (internal name) of this holiday
+ * @param string $key Holiday key
  * @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
@@ -109,14 +109,14 @@ class Holiday extends DateTime implements JsonSerializable
  * @throws \Exception
  */
  public function __construct(
- string $shortName,
+ string $key,
  array $names,
  \DateTimeInterface $date,
  string $displayLocale = self::DEFAULT_LOCALE,
  string $type = self::TYPE_OFFICIAL
  ) {
- // Validate if short name is not empty
- if (empty($shortName)) {
+ // Validate if key is not empty
+ if (empty($key)) {
  throw new InvalidArgumentException('Holiday name can not be blank.');
  }
 
@@ -131,7 +131,7 @@ public function __construct(
  }
 
  // Set additional attributes
- $this->shortName = $shortName;
+ $this->shortName = $key;
  $this->translations = $names;
  $this->displayLocale = $displayLocale;
  $this->type = $type;
@@ -141,11 +141,11 @@ public function __construct(
  }
 
  /**
- * Returns the short name for this holiday.
+ * Returns the key for this holiday.
  *
- * @return string the short name, e.g. "newYearsDay".
+ * @return string the key, e.g. "newYearsDay".
  */
- public function getShortName(): string
+ public function getKey(): string
  {
  return $this->shortName;
  }
@@ -176,21 +176,21 @@ public function jsonSerialize(): self
  * The provided locales are searched for a translation. The first locale containing a translation will be used.
  *
  * If no locale is provided, proceed as if an array containing the display locale, Holiday::DEFAULT_LOCALE ('en_US'), and
- * Holiday::LOCALE_SHORT_NAME (the short name (internal name) of this holiday) was provided.
+ * Holiday::LOCALE_KEY (the holiday key) was provided.
  *
  * @param array $locales The locales to search for translations
  *
  * @return string
  * @throws MissingTranslationException
  *
  * @see Holiday::DEFAULT_LOCALE
- * @see Holiday::LOCALE_SHORT_NAME
+ * @see Holiday::LOCALE_KEY
  */
  public function getName(array $locales = null): string
  {
  $locales = $this->getLocales($locales);
  foreach ($locales as $locale) {
- if ($locale === self::LOCALE_SHORT_NAME) {
+ if ($locale === self::LOCALE_KEY) {
  return $this->shortName;
  }
  if (isset($this->translations[$locale])) {
@@ -208,7 +208,7 @@ public function getName(array $locales = null): string
  * ['ca_ES_VALENCIA', 'es_ES'] is expanded into ['ca_ES_VALENCIA', 'ca_ES', 'ca', 'es_ES', 'es'].
  *
  * If a string is provided, return as if this string, Holiday::DEFAULT_LOCALE, and Holiday::LOCALE_SHORT_NAM
- * was provided. E.g. 'de_DE' is expanded into ['de_DE', 'de', 'en_US', 'en', Holiday::LOCALE_SHORT_NAME].
+ * was provided. E.g. 'de_DE' is expanded into ['de_DE', 'de', 'en_US', 'en', Holiday::LOCALE_KEY].
  *
  * If null is provided, return as if the display locale was provided as a string.
  *
@@ -217,7 +217,7 @@ public function getName(array $locales = null): string
  * @return array
  *
  * @see Holiday::DEFAULT_LOCALE
- * @see Holiday::LOCALE_SHORT_NAME
+ * @see Holiday::LOCALE_KEY
  */
  protected function getLocales(?array $locales): array
  {
@@ -226,7 +226,7 @@ protected function getLocales(?array $locales): array
  } else {
  $locales = [$this->displayLocale];
  // DEFAULT_LOCALE is 'en_US', and its parent is 'en'.
- $expanded = [self::LOCALE_SHORT_NAME, 'en', 'en_US'];
+ $expanded = [self::LOCALE_KEY, 'en', 'en_US'];
  }
 
  // Expand e.g. ['de_DE', 'en_GB'] into ['de_DE', 'de', 'en_GB', 'en'].

src/Yasumi/Provider/AbstractProvider.php

@@ -158,7 +158,7 @@ public function addHoliday(Holiday $holiday): void
  $holiday->mergeGlobalTranslations($this->globalTranslations);
  }
 
- $this->holidays[$holiday->getShortName()] = $holiday;
+ $this->holidays[$holiday->getKey()] = $holiday;
  \uasort($this->holidays, [__CLASS__, 'compareDates']);
  }
 
@@ -169,13 +169,13 @@ public function addHoliday(Holiday $holiday): void
  * This function can be helpful in cases where an existing holiday provider class can be extended but some holidays
  * are not part of the original (extended) provider.
  *
- * @param string $shortName short name of the holiday
+ * @param string $key holiday key
  *
  * @return void
  */
- public function removeHoliday(string $shortName): void
+ public function removeHoliday(string $key): void
  {
- unset($this->holidays[$shortName]);
+ unset($this->holidays[$key]);
  }
 
  /**
@@ -256,53 +256,68 @@ public function isWeekendDay(\DateTimeInterface $date): bool
  /**
  * On what date is the given holiday?
  *
- * @param string $shortName short name of the holiday
+ * @param string $key holiday key
  *
  * @return string the date of the requested holiday
  * @throws InvalidArgumentException when the given name is blank or empty.
  *
  */
- public function whenIs(string $shortName): string
+ public function whenIs(string $key): string
  {
- $this->isHolidayNameNotEmpty($shortName); // Validate if short name is not empty
+ $this->isHolidayNameNotEmpty($key); // Validate if key is not empty
 
- return (string)$this->holidays[$shortName];
+ return (string)$this->holidays[$key];
  }
 
  /**
- * Checks whether the given holiday (short name) is not empty.
+ * Checks whether the given holiday is not empty.
  *
- * @param string $shortName the name of the holiday to be checked.
+ * @param string $key key of the holiday to be checked.
  *
  * @return true upon success, otherwise an InvalidArgumentException is thrown
  * @throws InvalidArgumentException An InvalidArgumentException is thrown if the given holiday parameter is empty.
  */
- protected function isHolidayNameNotEmpty(string $shortName): bool
+ protected function isHolidayKeyNotEmpty(string $key): bool
  {
- if (empty($shortName)) {
- throw new InvalidArgumentException('Holiday name can not be blank.');
+ if (empty($key)) {
+ throw new InvalidArgumentException('Holiday key can not be blank.');
  }
 
  return true;
  }
 
+ /**
+ * Checks whether the given holiday is not empty.
+ *
+ * @param string $key key of the holiday to be checked.
+ *
+ * @return true upon success, otherwise an InvalidArgumentException is thrown
+ * @throws InvalidArgumentException An InvalidArgumentException is thrown if the given holiday parameter is empty.
+ * @deprecated deprecated in favor of isHolidayKeyNotEmpty()
+ * @deprecated see isHolidayKeyNotEmpty()
+ */
+ protected function isHolidayNameNotEmpty(string $key): bool
+ {
+ return $this->isHolidayKeyNotEmpty($key);
+ }
+
  /**
  * On what day of the week is the given holiday?
  *
  * This function returns the index number for the day of the week on which the given holiday falls.
  * The index number is an integer starting with 0 being Sunday, 1 = Monday, etc.
  *
- * @param string $shortName short name of the holiday
+ * @param string $key key of the holiday
  *
  * @return int the index of the weekdays of the requested holiday (0 = Sunday, 1 = Monday, etc.)
  * @throws InvalidArgumentException when the given name is blank or empty.
  *
  */
- public function whatWeekDayIs(string $shortName): int
+ public function whatWeekDayIs(string $key): int
  {
- $this->isHolidayNameNotEmpty($shortName); // Validate if short name is not empty
+ $this->isHolidayNameNotEmpty($key); // Validate if key is not empty
 
- return (int)$this->holidays[$shortName]->format('w');
+ return (int)$this->holidays[$key]->format('w');
  }
 
  /**
@@ -315,10 +330,10 @@ public function count(): int
  {
  $names = \array_map(static function ($holiday) {
  if ($holiday instanceof SubstituteHoliday) {
- return $holiday->getSubstitutedHoliday()->getShortName();
+ return $holiday->getSubstitutedHoliday()->getKey();
  }
 
- return $holiday->getShortName();
+ return $holiday->getKey();
  }, $this->getHolidays());
 
  return \count(\array_unique($names));
@@ -357,7 +372,7 @@ public function getYear(): int
  /**
  * Retrieves the next date (year) the given holiday is going to take place.
  *
- * @param string $shortName the name of the holiday for which the next occurrence need to be retrieved.
+ * @param string $key key of the holiday for which the next occurrence need to be retrieved.
  *
  * @return Holiday|null a Holiday instance for the given holiday
  *
@@ -368,16 +383,16 @@ public function getYear(): int
  *
  * @covers AbstractProvider::anotherTime
  */
- public function next(string $shortName): ?Holiday
+ public function next(string $key): ?Holiday
  {
- return $this->anotherTime($this->year + 1, $shortName);
+ return $this->anotherTime($this->year + 1, $key);
  }
 
  /**
  * Determines the date of the given holiday for another year.
  *
  * @param int $year the year to get the holiday date for
- * @param string $shortName the name of the holiday for which the date needs to be fetched
+ * @param string $key key of the holiday for which the date needs to be fetched
  *
  * @return Holiday|null a Holiday instance for the given holiday and year
  *
@@ -386,38 +401,38 @@ public function next(string $shortName): ?Holiday
  * @throws UnknownLocaleException
  * @throws \RuntimeException
  */
- private function anotherTime(int $year, string $shortName): ?Holiday
+ private function anotherTime(int $year, string $key): ?Holiday
  {
- $this->isHolidayNameNotEmpty($shortName); // Validate if short name is not empty
+ $this->isHolidayNameNotEmpty($key); // Validate if key is not empty
 
  // Get calling class name
  $hReflectionClass = new \ReflectionClass(\get_class($this));
 
- return Yasumi::create($hReflectionClass->getShortName(), $year, $this->locale)->getHoliday($shortName);
+ return Yasumi::create($hReflectionClass->getShortName(), $year, $this->locale)->getHoliday($key);
  }
 
  /**
  * Retrieves the holiday object for the given holiday.
  *
- * @param string $shortName the name of the 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 $shortName): ?Holiday
+ public function getHoliday(string $key): ?Holiday
  {
- $this->isHolidayNameNotEmpty($shortName); // Validate if short name is not empty
+ $this->isHolidayNameNotEmpty($key); // Validate if key is not empty
 
  $holidays = $this->getHolidays();
 
- return $holidays[$shortName] ?? null;
+ return $holidays[$key] ?? null;
  }
 
  /**
  * Retrieves the previous date (year) the given holiday took place.
  *
- * @param string $shortName the name of the holiday for which the previous occurrence need to be retrieved.
+ * @param string $key key of the holiday for which the previous occurrence need to be retrieved.
  *
  * @return Holiday|null a Holiday instance for the given holiday
  *
@@ -428,9 +443,9 @@ public function getHoliday(string $shortName): ?Holiday
  *
  * @covers AbstractProvider::anotherTime
  */
- public function previous(string $shortName): ?Holiday
+ public function previous(string $key): ?Holiday
  {
- return $this->anotherTime($this->year - 1, $shortName);
+ return $this->anotherTime($this->year - 1, $key);
  }
 
  /**