From 5c8b29e7f5d8928beddd6ad95183680a23ddbd42 Mon Sep 17 00:00:00 2001 From: "John R. D'Orazio" Date: Sat, 16 Nov 2024 19:30:15 +0100 Subject: [PATCH 1/2] add abbreviated form of liturgical rank Fixes #251 --- src/Enum/LitGrade.php | 225 ++++++++++++++++++++++-------------- src/FestivityCollection.php | 16 ++- 2 files changed, 151 insertions(+), 90 deletions(-) diff --git a/src/Enum/LitGrade.php b/src/Enum/LitGrade.php index 9c0dd3d5..2dd616df 100644 --- a/src/Enum/LitGrade.php +++ b/src/Enum/LitGrade.php @@ -16,139 +16,196 @@ class LitGrade { -// I. - public const HIGHER_SOLEMNITY = 7; -// HIGHER RANKING SOLEMNITIES, THAT HAVE PRECEDENCE OVER ALL OTHERS: - // 1. EASTER TRIDUUM - // 2. CHRISTMAS, EPIPHANY, ASCENSION, PENTECOST - // SUNDAYS OF ADVENT, LENT AND EASTER - // ASH WEDNESDAY - // DAYS OF THE HOLY WEEK, FROM MONDAY TO THURSDAY - // DAYS OF THE OCTAVE OF EASTER - - public const SOLEMNITY = 6; -// 3. SOLEMNITIES OF THE LORD, OF THE BLESSED VIRGIN MARY, OF THE SAINTS LISTED IN THE GENERAL CALENDAR - // COMMEMORATION OF THE FAITHFUL DEPARTED - // 4. PARTICULAR SOLEMNITIES: - // a) PATRON OF THE PLACE, OF THE COUNTRY OR OF THE CITY (CELEBRATION REQUIRED ALSO FOR RELIGIOUS COMMUNITIES); - // b) SOLEMNITY OF THE DEDICATION AND OF THE ANNIVERSARY OF THE DEDICATION OF A CHURCH - // c) SOLEMNITY OF THE TITLE OF A CHURCH - // d) SOLEMNITY OF THE TITLE OR OF THE FOUNDER OR OF THE MAIN PATRON OF AN ORDER OR OF A CONGREGATION - -// II. - public const FEAST_LORD = 5; -// 5. FEASTS OF THE LORD LISTED IN THE GENERAL CALENDAR - // 6. SUNDAYS OF CHRISTMAS AND OF ORDINARY TIME - - public const FEAST = 4; -// 7. FEASTS OF THE BLESSED VIRGIN MARY AND OF THE SAINTS IN THE GENERAL CALENDAR - // 8. PARTICULAR FEASTS: - // a) MAIN PATRON OF THE DIOCESE - // b) FEAST OF THE ANNIVERSARY OF THE DEDICATION OF THE CATHEDRAL - // c) FEAST OF THE MAIN PATRON OF THE REGION OR OF THE PROVINCE, OF THE NATION, OF A LARGER TERRITORY - // d) FEAST OF THE TITLE, OF THE FOUNDER, OF THE MAIN PATRON OF AN ORDER OR OF A CONGREGATION AND OF A RELIGIOUS PROVINCE - // e) OTHER PARTICULAR FEASTS OF SOME CHURCH - // f) OTHER FEASTS LISTED IN THE CALENDAR OF EACH DIOCESE, ORDER OR CONGREGATION - // 9. WEEKDAYS OF ADVENT FROM THE 17th TO THE 24th OF DECEMBER - // DAYS OF THE OCTAVE OF CHRISTMAS - // WEEKDAYS OF LENT - -// III. - public const MEMORIAL = 3; -// 10. MEMORIALS OF THE GENERAL CALENDAR - // 11. PARTICULAR MEMORIALS: - // a) MEMORIALS OF THE SECONDARY PATRON OF A PLACE, OF A DIOCESE, OF A REGION OR A RELIGIOUS PROVINCE - // b) OTHER MEMORIALS LISTED IN THE CALENDAR OF EACH DIOCESE, ORDER OR CONGREGATION - - public const MEMORIAL_OPT = 2; -// 12. OPTIONAL MEMORIALS, WHICH CAN HOWEVER BE OBSERVED IN DAYS INDICATED AT N. 9, - // ACCORDING TO THE NORMS DESCRIBED IN "PRINCIPLES AND NORMS" FOR THE LITURGY OF THE HOURS AND THE USE OF THE MISSAL - - public const COMMEMORATION = 1; -// SIMILARLY MEMORIALS CAN BE OBSERVED AS OPTIONAL MEMORIALS THAT SHOULD FALL DURING THE WEEKDAYS OF LENT - - public const WEEKDAY = 0; -// 13. WEEKDAYS OF ADVENT UNTIL DECEMBER 16th - // WEEKDAYS OF CHRISTMAS, FROM JANUARY 2nd UNTIL THE SATURDAY AFTER EPIPHANY - // WEEKDAYS OF THE EASTER SEASON, FROM THE MONDAY AFTER THE OCTAVE OF EASTER UNTIL THE SATURDAY BEFORE PENTECOST - // WEEKDAYS OF ORDINARY TIME + /** + * HIGHER SOLEMNITIES + * + * I. HIGHER RANKING SOLEMNITIES, THAT HAVE PRECEDENCE OVER ALL OTHERS: + * 1. EASTER TRIDUUM + * 2. CHRISTMAS, EPIPHANY, ASCENSION, PENTECOST + * SUNDAYS OF ADVENT, LENT AND EASTER + * ASH WEDNESDAY + * DAYS OF THE HOLY WEEK, FROM MONDAY TO THURSDAY + * DAYS OF THE OCTAVE OF EASTER + */ + public const int HIGHER_SOLEMNITY = 7; + + /** + * SOLEMNITIES + * + * 3. SOLEMNITIES OF THE LORD, OF THE BLESSED VIRGIN MARY, OF THE SAINTS LISTED IN THE GENERAL CALENDAR + * COMMEMORATION OF THE FAITHFUL DEPARTED + * 4. PARTICULAR SOLEMNITIES: + * * PATRON OF THE PLACE, OF THE COUNTRY OR OF THE CITY (CELEBRATION REQUIRED ALSO FOR RELIGIOUS COMMUNITIES); + * * SOLEMNITY OF THE DEDICATION AND OF THE ANNIVERSARY OF THE DEDICATION OF A CHURCH + * * SOLEMNITY OF THE TITLE OF A CHURCH + * * SOLEMNITY OF THE TITLE OR OF THE FOUNDER OR OF THE MAIN PATRON OF AN ORDER OR OF A CONGREGATION + */ + public const int SOLEMNITY = 6; + + /** + * FEASTS OF THE LORD + * + * II. + * + * 5. FEASTS OF THE LORD LISTED IN THE GENERAL CALENDAR + * 6. SUNDAYS OF CHRISTMAS AND OF ORDINARY TIME + */ + public const int FEAST_LORD = 5; + + /** + * FEASTS + * + * 7. FEASTS OF THE BLESSED VIRGIN MARY AND OF THE SAINTS IN THE GENERAL CALENDAR + * 8. PARTICULAR FEASTS: + * * MAIN PATRON OF THE DIOCESE + * * FEAST OF THE ANNIVERSARY OF THE DEDICATION OF THE CATHEDRAL + * * FEAST OF THE MAIN PATRON OF THE REGION OR OF THE PROVINCE, OF THE NATION, OF A LARGER TERRITORY + * * FEAST OF THE TITLE, OF THE FOUNDER, OF THE MAIN PATRON OF AN ORDER OR OF A CONGREGATION AND OF A RELIGIOUS PROVINCE + * * OTHER PARTICULAR FEASTS OF SOME CHURCH + * * OTHER FEASTS LISTED IN THE CALENDAR OF EACH DIOCESE, ORDER OR CONGREGATION + * 9. WEEKDAYS OF ADVENT FROM THE 17th TO THE 24th OF DECEMBER + * DAYS OF THE OCTAVE OF CHRISTMAS + * WEEKDAYS OF LENT + */ + public const int FEAST = 4; + + /** + * OBLIGATORY MEMORIALS + * + * III. + * + * 10. MEMORIALS OF THE GENERAL CALENDAR + * 11. PARTICULAR MEMORIALS: + * * MEMORIALS OF THE SECONDARY PATRON OF A PLACE, OF A DIOCESE, OF A REGION OR A RELIGIOUS PROVINCE + * * OTHER MEMORIALS LISTED IN THE CALENDAR OF EACH DIOCESE, ORDER OR CONGREGATION + */ + public const int MEMORIAL = 3; + + /** + * OPTIONAL MEMORIALS + * + * 12. OPTIONAL MEMORIALS, WHICH CAN HOWEVER BE OBSERVED IN DAYS INDICATED AT N. 9, + * ACCORDING TO THE NORMS DESCRIBED IN "PRINCIPLES AND NORMS" FOR THE LITURGY OF THE HOURS AND THE USE OF THE MISSAL + */ + public const int MEMORIAL_OPT = 2; + + /** + * COMMEMORATIONS + * + * SIMILARLY MEMORIALS THAT SHOULD FALL DURING THE WEEKDAYS OF LENT CAN BE OBSERVED AS OPTIONAL MEMORIALS + */ + public const int COMMEMORATION = 1; + + /** + * WEEKDAYS + * + * 13. + * + * - WEEKDAYS OF ADVENT UNTIL DECEMBER 16th + * - WEEKDAYS OF CHRISTMAS, FROM JANUARY 2nd UNTIL THE SATURDAY AFTER EPIPHANY + * - WEEKDAYS OF THE EASTER SEASON, FROM THE MONDAY AFTER THE OCTAVE OF EASTER UNTIL THE SATURDAY BEFORE PENTECOST + * - WEEKDAYS OF ORDINARY TIME + */ + public const int WEEKDAY = 0; public static array $values = [ 0, 1, 2, 3, 4, 5, 6, 7 ]; private string $locale; + /** + * Constructor for the LitGrade class. + * + * @param string $locale The locale to be used for localization. + */ public function __construct(string $locale) { $this->locale = $locale; } + /** + * Check if a given liturgical grade is valid. + * + * @param int $value the value to check + * @return bool true if the value is a valid liturgical grade, false otherwise + */ public static function isValid(int $value) { return in_array($value, self::$values); } - public function i18n(int $value, bool $html = true) + /** + * Translates a liturgical grade value into a localized string, optionally wrapped in HTML tags. + * + * @param int $value The liturgical grade value to be translated. + * @param bool $html Optional parameter to determine if the output should be wrapped in HTML tags. + * Defaults to true. + * @return string The localized string representing the liturgical grade, potentially wrapped in HTML. + */ + public function i18n(int $value, bool $html = true, bool $abbreviate = false): string { switch ($value) { case self::WEEKDAY: /**translators: liturgical rank. Keep lowercase */ - - $grade = $this->locale === LitLocale::LATIN ? 'feria' : _("weekday"); + $grade = $this->locale === LitLocale::LATIN ? 'feria' : _("weekday"); + /**translators: liturgical rank 'WEEKDAY' in abbreviated form */ + $gradeAbbr = $this->locale === LitLocale::LATIN ? 'f' : _("w"); $tags = ['','']; - break; case self::COMMEMORATION: - /**translators: liturgical rank. Keep Capitalized */ - - $grade = $this->locale === LitLocale::LATIN ? 'Commemoratio' : _("Commemoration"); + /**translators: liturgical rank. Keep lowercase */ + $grade = $this->locale === LitLocale::LATIN ? 'commemoratio' : _("commemoration"); + /**translators: liturgical rank 'COMMEMORATION' in abbreviated form */ + $gradeAbbr = $this->locale === LitLocale::LATIN ? 'm*' : _("m*"); $tags = ['','']; - break; case self::MEMORIAL_OPT: - /**translators: liturgical rank. Keep Capitalized */ - - $grade = $this->locale === LitLocale::LATIN ? 'Memoria ad libitum' : _("Optional memorial"); + /**translators: liturgical rank. Keep lowercsase */ + $grade = $this->locale === LitLocale::LATIN ? 'memoria ad libitum' : _("optional memorial"); + /**translators: liturgical rank 'OPTIONAL MEMORIAL' in abbreviated form */ + $gradeAbbr = $this->locale === LitLocale::LATIN ? 'm' : _("m"); $tags = ['','']; - break; case self::MEMORIAL: /**translators: liturgical rank. Keep Capitalized */ - - $grade = $this->locale === LitLocale::LATIN ? 'Memoria obligatoria' : _("Memorial"); + $grade = $this->locale === LitLocale::LATIN ? 'Memoria obligatoria' : _("Memorial"); + /**translators: liturgical rank 'MEMORIAL' in abbreviated form */ + $gradeAbbr = $this->locale === LitLocale::LATIN ? 'M' : _("M"); $tags = ['','']; - break; case self::FEAST: /**translators: liturgical rank. Keep UPPERCASE */ - - $grade = $this->locale === LitLocale::LATIN ? 'FESTUM' : _("FEAST"); + $grade = $this->locale === LitLocale::LATIN ? 'FESTUM' : _("FEAST"); + /**translators: liturgical rank 'FEAST' in abbreviated form */ + $gradeAbbr = $this->locale === LitLocale::LATIN ? 'F' : _("F"); $tags = ['','']; - break; case self::FEAST_LORD: /**translators: liturgical rank. Keep UPPERCASE */ - - $grade = $this->locale === LitLocale::LATIN ? 'FESTUM DOMINI' : _("FEAST OF THE LORD"); + $grade = $this->locale === LitLocale::LATIN ? 'FESTUM DOMINI' : _("FEAST OF THE LORD"); + /**translators: liturgical rank 'FEAST OF THE LORD' in abbreviated form */ + $gradeAbbr = $this->locale === LitLocale::LATIN ? 'F✝' : _("F✝"); $tags = ['','']; - break; case self::SOLEMNITY: /**translators: liturgical rank. Keep UPPERCASE */ - - $grade = $this->locale === LitLocale::LATIN ? 'SOLLEMNITAS' : _("SOLEMNITY"); + $grade = $this->locale === LitLocale::LATIN ? 'SOLLEMNITAS' : _("SOLEMNITY"); + /**translators: liturgical rank 'SOLEMNITY' in abbreviated form */ + $gradeAbbr = $this->locale === LitLocale::LATIN ? 'S' : _("S"); $tags = ['','']; - break; case self::HIGHER_SOLEMNITY: /**translators: liturgical rank. Keep lowercase */ - - $grade = $this->locale === LitLocale::LATIN ? 'celebratio altioris ordinis quam sollemnitatis' : _("celebration with precedence over solemnities"); + $grade = $this->locale === LitLocale::LATIN ? 'celebratio altioris ordinis quam sollemnitatis' : _("celebration with precedence over solemnities"); + /**translators: liturgical rank 'HIGHER SOLEMNITY' in abbreviated form */ + $gradeAbbr = $this->locale === LitLocale::LATIN ? 'S+' : _("S+"); $tags = ['','']; - break; default: - $grade = $this->locale === LitLocale::LATIN ? 'feria' : _("weekday"); + $grade = $this->locale === LitLocale::LATIN ? 'feria' : _("weekday"); $tags = ['','']; } + if ($abbreviate) { + return $html ? $tags[0] . $gradeAbbr . $tags[1] : $gradeAbbr; + } return $html ? $tags[0] . $grade . $tags[1] : $grade; } } diff --git a/src/FestivityCollection.php b/src/FestivityCollection.php index 7c2be5e0..e61e0d8d 100644 --- a/src/FestivityCollection.php +++ b/src/FestivityCollection.php @@ -1177,21 +1177,25 @@ public function getSundaysAdventLentEasterCollection(): array * Retrieves all festivities from the collection * in a format that can be easily converted to JSON. * - * This method returns an array of arrays, where each inner array contains the key of the - * event and the properties of the DateTime object as key-value pairs. + * This method returns a collection of liturgical events or celebrations, + * each with properties such as date, name, event_key, etc. * - * @return array An array of arrays, where each inner array contains the key of the event - * and the properties of the DateTime object as key-value pairs. + * @return array A collection of liturgical events, each of which has properties + * such as date, name, event_key, etc. */ public function getFestivitiesCollection(): array { if (empty($this->festivitiesCollection)) { $festivitiesCollection = []; foreach ($this->festivities as $key => $festivity) { - $festivitiesCollection[] = [ + $gradeAbbr = $this->LitGrade->i18n($festivity->grade, false, true); + $festivityAssocArr = [ "event_key" => $key, - ...json_decode(json_encode($festivity), true) + ...json_decode(json_encode($festivity), true), + "grade_abbr" => $gradeAbbr ]; + ksort($festivityAssocArr); + $festivitiesCollection[] = $festivityAssocArr; } return $festivitiesCollection; } else { From 3444b4167629806a407f249bfa9d95ad3c1a09bc Mon Sep 17 00:00:00 2001 From: "John R. D'Orazio" Date: Sat, 16 Nov 2024 19:48:58 +0100 Subject: [PATCH 2/2] fixes add abbreviated form of liturgical rank #251 --- schemas/LitCal.json | 22 ++++++++++++++++++---- schemas/openapi.json | 9 +++++++++ src/Enum/LitGrade.php | 2 +- 3 files changed, 28 insertions(+), 5 deletions(-) diff --git a/schemas/LitCal.json b/schemas/LitCal.json index 9d4e48d0..c9940de2 100644 --- a/schemas/LitCal.json +++ b/schemas/LitCal.json @@ -204,9 +204,10 @@ "StsBasilGreg" ] }, - "litcal": { - "Advent1_vigil": { + "litcal": [ + { "event_idx": 1076, + "event_key": "Advent1_vigil", "name": "Dominica Prima Adventus Missa in Vigilia", "date": 1701475200, "color": [ @@ -218,6 +219,7 @@ "type": "mobile", "grade": 7, "grade_lcl": "celebratio altioris ordinis quam sollemnitatis", + "grade_abbr": "S✝", "grade_display": "", "common": [], "common_lcl": "", @@ -235,8 +237,9 @@ "liturgical_season": "ADVENT", "liturgical_season_lcl": "Tempus Adventus" }, - "Advent1": { + { "event_idx": 583, + "event_key": "Advent1", "name": "Dominica Prima Adventus", "date": 1701561600, "color": [ @@ -248,6 +251,7 @@ "type": "mobile", "grade": 7, "grade_lcl": "celebratio altioris ordinis quam sollemnitatis", + "grade_abbr": "S✝", "grade_display": "", "common": [], "common_lcl": "", @@ -267,7 +271,7 @@ "liturgical_season": "ADVENT", "liturgical_season_lcl": "Tempus Adventus" } - }, + ], "messages": [ "The Solemnity 'Sancti Ioseph Sponsi Beatæ Mariæ Virginis' falls on Dominica IV in Quadragesima in the year 2023, the celebration has been transferred to the following Monday (20 Martius) as per the Decree of the Congregation for Divine Worship.", "'Dominica XVIII «Per Annum»' is superseded by the FESTUM DOMINI 'In Transfiguratione Domini' in the year 2023." @@ -334,6 +338,9 @@ "grade_lcl": { "type": "string" }, + "grade_abbr": { + "type": "string" + }, "grade_display": { "type": "string" }, @@ -412,6 +419,8 @@ "color_lcl", "type", "grade", + "grade_lcl", + "grade_abbr", "grade_display", "common", "common_lcl", @@ -465,6 +474,9 @@ "grade_lcl": { "type": "string" }, + "grade_abbr": { + "type": "string" + }, "grade_display": { "type": "string" }, @@ -546,6 +558,8 @@ "color_lcl", "type", "grade", + "grade_lcl", + "grade_abbr", "grade_display", "common", "common_lcl", diff --git a/schemas/openapi.json b/schemas/openapi.json index 61001508..b86c20d2 100644 --- a/schemas/openapi.json +++ b/schemas/openapi.json @@ -4788,6 +4788,15 @@ "SOLEMNITY" ] }, + "GradeAbbr": { + "description": "The logical importance of the celebration, represented in abbreviated human readable form and localized according to the current requested locale", + "type": "string", + "examples": [ + "w", + "F", + "S" + ] + }, "DisplayGrade": { "type": "string", "description": "will often be empty, in which case the ***grade*** or ***gradeLcl*** properties can be used, for the purpose of displaying the rank of the current liturgical event. If non empty, will contain the localized rank of the liturgical event and should be used instead of the ***grade*** or ***gradeLcl*** properties for display purposes" diff --git a/src/Enum/LitGrade.php b/src/Enum/LitGrade.php index 2dd616df..f45116e4 100644 --- a/src/Enum/LitGrade.php +++ b/src/Enum/LitGrade.php @@ -196,7 +196,7 @@ public function i18n(int $value, bool $html = true, bool $abbreviate = false): s /**translators: liturgical rank. Keep lowercase */ $grade = $this->locale === LitLocale::LATIN ? 'celebratio altioris ordinis quam sollemnitatis' : _("celebration with precedence over solemnities"); /**translators: liturgical rank 'HIGHER SOLEMNITY' in abbreviated form */ - $gradeAbbr = $this->locale === LitLocale::LATIN ? 'S+' : _("S+"); + $gradeAbbr = $this->locale === LitLocale::LATIN ? 'S✝' : _("S✝"); $tags = ['','']; break; default: