Skip to content

Latest commit

 

History

History
227 lines (191 loc) · 33.2 KB

README.md

File metadata and controls

227 lines (191 loc) · 33.2 KB
Raw
Code qualityTranslation statusOpenAPI validation
main branchdevelopment branch
Translation status OpenAPI validation result

Liturgical Calendar

An API written in PHP that will generate the liturgical calendar for any given year, based on the General Roman Calendar, calculating the mobile festivities and the precedence of solemnities, feasts, memorials... Can also produce calendar data for nations, dioceses, or groups of dioceses. This calendar data can be served in various formats such as JSON, YAML, XML, or ICS. More information on the website https://litcal.johnromanodorazio.com/.

OpenAPI documentation can be found here (kudos to @MichaelRShelton for generating the docs from the Swagger docker image).

The API is packaged as a composer library: run composer install to setup the autoload functionality.

Some characteristics of this API:

  • The data is based on official sources, not copied from random internet sources. Sources used are the various editions of the Roman Missal in Latin, English, and Italian, Magisterial documents, and the Decrees of the Congregation for Divine Worship
  • The data is historically accurate, i.e. the liturgical calendar produced for the year 1979 will reflect the calendar as it was in that year, and not as it would be today (obviously future years will reflect the calendar as it is generated in the current year; as new decrees are issued by the Congregation for Divine Worship or new editions of the Roman Missal are published, the script will need to be updated to account for any new criteria)

Example applications

There are a few proof of concept example applications for usage of the API at https://litcal.johnromanodorazio.com/usage.php, which demonstrate generating an HTML representation of the Liturgical Calendar.

All of these examples request JSON as the data exchange format generated by the endpoint. Any application could use the endpoint in a similar manner: an Android App, a plugin for a Desktop Publishing App...

Using the endpoint as a calendar URL for Calendar Apps

(See usage.php#calSubscription.)

  • GOOGLE CALENDAR ON A DESKTOP COMPUTER: you can only add a calendar by URL using Google Calendar on a computer, I don't believe it is possible from smartphone / Android devices. At the bottom left corner of the screen, next to Other calendars, click on the + to add a new calendar and choose From URL. Paste in the URL of the endpoint with the desired parameters, (make sure you use ICS as value of the return_type parameter). And remember, if you omit the year parameter, it will use the current year. This should mean that as Google Calendar continues to poll the calendar URL (supposedly every 8 hours), on the turn of a new year new events should be created automatically for the new year. Once the calendar has been added from a computer, it should become available for the same gmail account on the Google Calendar app on a smartphone.
  • CALENDAR APPS ON AN ANDROID DEVICE: after you have added a calendar by URL in your Google Calendar on a Desktop Computer, you should then find that calendar synchronized with your Google account, so the calendar should become available to any Android Calendar apps that have access to your Google account to synchronize calendars.
  • IPHONE: go to Phone Settings -> Accounts -> Add account -> Other -> Add Calendar, and paste in the endpoint URL with the desired parameters, (make sure you use ICS as value of the return_type parameter). And remember, if you omit the year parameter, it will use the current year. This should mean that as the iPhone Calendar continues to poll the calendar URL, on the turn of a new year new events should be created automatically for the new year.
  • MICROSOFT OUTLOOK (tested with Outlook 2013): at the bottom of the screen, switch from Email view to Calendar view. On the ribbon of the Home menu item, click on Open calendar -> From the internet. Paste the endpoint URL with the desired parameters, (make sure you use ICS as value of the return_type parameter). And remember, if you omit the year parameter, it will use the current year. On the following screen, check the checkbox along the lines of "Poll this calendar in the interval suggested by the creator", which would mean that Outlook Calendar should poll the calendar URL once a day. This means that without the year parameter, on the turn of a new year new events should be created automatically for the new year. Make sure the Calendar is created in the Other calendars folder; if you find it under the Personal calendars folder, drag it and drop it onto the Other calendars folder, this should ensure that it is treated as a subscription internet calendar. You can manually trigger an update against the calendar URL by clicking on Send/receive all (from the SEND/RECEIVE menu item). One highlight of the calendar in Outlook is that it supports a minimal amount of HTML in the event description, so the event descriptions in the Liturgical Calendar are a little bit more "beautified" for Outlook.

Testing locally

To test the API locally, you can use PHP's builtin server. However, you will need to spawn at least a couple of workers, since some routes will make a request internally to another route. For example, a request to the /calendar route will make a request internally to the /calendars route.

Spawn at least two workers:

PHP_CLI_SERVER_WORKERS=2 php -S localhost:8000

For convenience when using VSCode, a tasks.json has been defined so that you can simply type CTRL+SHIFT+B (CMD+SHIFT+B on MacOS) to start the PHP builtin server and open the browser.

Translations

Translation status

CHANGELOG

v4.0 (January 3rd 2025)

  • package the API source as a composer library for autoload functionality
  • move the endpoints from PHP scripts to resource paths, and create a router
  • add YAML as a response media type
  • use JSON resource files for the Tests server in place of PHP Unit defs (remove dependency on PHP Unit)
  • fix bug where liturgical commons were not getting localized correctly
  • fix XML response, implement XML and ICS validation
  • update the OpenAPI schema
  • add timing to response output and to response headers
  • refactor responses to use snake_case properties and collections (this also fixes SaintAndrewAp bug for year_type=LITURGICAL in year=2023, see issue #249)
  • add Calendars for Netherlands and for Canada, kudos to Steven van Roode and to Fr. @chrissherren for the contributions
  • add a Dockerfile to easily spin up a Docker container with a local instance of the API
  • fix for cases in which Immaculate Heart of Mary is suppressed, see commit 6f16f130fb2df88488f8ad9ddcc5c8961380f387
  • fix calculation of weekdays between Epiphany and Baptism of the Lord, see issue #237
  • fix Chritmas weekdays should not be created when there is an obligatory memorial, see commit a8ca47744582d89aaed195658a40a22145659eee
  • fix moving of celebrations by a National Calendar that were suppressed in the General Roman Calendar, see issue #271
  • add abbreviated form of the liturgical rank / grade to the Festivity output, see issue #251
  • use ISO 3166-1 Alpha-2 codes to identify nations, see issue #231
  • created an interface that allows to create Unit Tests, see issue #205
  • added an index of all dioceses of Latin rite, kudos to Gabriel Chow of gcatholic.org for the contribution
  • add Decree of the Congregation for Divine Worship for Italy: Immaculate Heart suppresses 2nd Sunday of Advent, see commit 191d3247838a4da18ce1ab7c0ca2f16a1b2d516e
  • add Decree of the Congregation for Divine Worship for Italy: Saint Nicholas obligatory memorial since 2020, see issue #248
  • feature: discoverability of supported locales, see issue #240
  • feature: all national and diocesan calendars are now multilingual by default, see issue #150
  • and a number of other bugfixes, features, and improvements

v3.9 (April 9th 2024)

v3.8 (February 1st 2023)

  • fix language for iCal / ICS format
  • fix bug in LitColor enum (static class variable)
  • add empty displayGrade property for higher solemnities
  • add localized info to Festivity output for liturgical color, common, grade...
  • define Divine Mercy Sunday starting from the year 2000
  • update OpenAPI schema to v3.1

v3.7 (December 14th 2022)

  • fix support for correct ordinal number spelling for any language
  • fix "Year I", "Year II" references which should only concern weekdays of Ordinary Time
  • fix: in cases where the diocesancalendar parameter was set, but the nationalcalendar parameter was not, the national calendar settings were not being picked up correctly
  • fix for Netherlands national calendar data (Ascension on Thursday)

v3.6 (December 13th 2022)

  • allow Diocesan calendars to define mobile festivities
  • allow Diocesan calendars to define untilYear properties for festivities that may have changes after a given year
  • remove hardcoding of English, Latin and the 5 main European languages and allow for any possible language
  • allow for geographic locales, in order to better identify source data for a given national or diocesan calendar
  • remove hardcoding of supported national calendars, and automate the scan for existing calendars

v3.5 (December 4th 2022)

  • Fix days before / after Epiphany (handled differently in different national calendars!)
  • Add Dutch translation for Netherlands, thanks to Steven van Roode

v3.4 (June 6th 2022)

v3.3 (January 27th 2022)

  • move festivity data from the 2008 Editio Typica Tertia emendata out from the LitCalAPI.php, to a JSON file
  • move data for festivities from Decrees of the Congregation of Divine Worship out from the LitCalAPI.php, to a JSON file

v3.2 (January 23rd 2022)

  • allow full CORS requests from enabled domains
  • allow Diocesan overrides for Epiphany, Ascension and Corpus Christi

v3.1 (December 26th 2021)

  • bugfix which was missed in the v3.0 release: 86ee62ad68d58736880da2b5b39117dec7386dfc

v3.0 (December 26th 2021)

  • all calendar data moved from a MySQL database to JSON files, that can be tracked in the repository
  • the Calendar data for the Universal Calendar, as contained in the JSON files, is now translatable to other languages through a Weblate project
  • the frontend and any implementations of the API have been moved to their own separate repositories, only the API code remains in this repository
  • the PHP source code for the API has been pretty much completely rewritten, using classes and enum type classes
  • all translatable strings in the PHP source code have been ported to gettext, and are now managed in a Weblate project
  • parameters diocesanpreset and nationalpreset have been renamed to diocesancalendar and nationalcalendar
  • API now supports POST requests that send JSON in the body instead of Form Data
  • Data type can be set through the Accept header rather than the returntype parameter
  • Language can be set through the Accept-Language header rather than the locale parameter

v2.9 (November 12th 2020)

  • adds Vigil Masses for Sundays and Solemnities, including occasional notes by the Congregation for Divine Worship
  • add Patron Saints of Europe, applicable for Italian Calendar (and eventually any other national calendar in Europe that may be added in the future)
  • add Saturday Memorial of the Blessed Virgin Mary

v2.8 (August 11th 2020)

  • adds diocesanpreset and nationalpreset parameters with relative calendar data
  • adds all of the data from the recent Decrees of the Congregation for Divine Worship and verifies integrity with past Decrees
  • ensures Messages returned are as specific as possible, while trying to keep the code as clean as possible
  • adds FullCalendar example

v2.7 (July 28th 2020)

  • adds Messages array to the data that is generated by the endpoint, justifying the calculations made for the generation of the requested calendar
  • fixes an issue with the memorial Saint Jane Frances de Chantal after 1999, when it was decided to move the memorial from Dec. 12 to Aug. 12 in order to allow Our Lady of Guadalupe on Dec. 12 (if another more important celebration took place on Dec. 12, Saint Jane Frances was being removed before it could be moved, this is now handled correctly) add translations for the Messages array in Italian, English and Latin (please forgive my macaronic latin, it's not at all perfect, it's mostly conjecture, I hope to have it proofread at some point)
  • update PHP example to display Messages array in a table below the generated calendar
  • update PHP example to fix parsing of Liturgical colors for memorials with more than one possible Common and more than one possible liturgical color
  • fix a few errors in the database as regards liturgical colors for some memorials with more than one possible Common

v2.6 (July 26th 2020)

  • integrate the calculation of the liturgical cycle (YEAR A,B,C for festivities and YEAR I,II for weekdays) directly into the engine, so that applications that take care of elaborating the data for display don't have to worry about it
  • update both examples, PHP and Javascript, to use the new liturgicalyear property returned in the JSON data, and bring Javascript example up to par with the PHP example (add month cell that spans all events for that month)

v2.5 (July 25th 2020)

  • make sure all endpoint parameters can have values with either uppercase or lowercase characters
  • fix a few small issues with the ICS data generation

v2.4 (July 24th 2020)

  • move as many festivities as possible to the MySQL tables to allow for localization (mobile feasts will be calculated in the script, but still need to be localized)
  • add ICS data generation (requires more localization strings, because it is already a form of final display of the data)

v2.0 (January 8th 2018)

  • separate the display logic from the engine, so that the engine can act as an endpoint
  • make the engine return JSON or XML data that the display logic can use to generate a user-friendly representation of the data

v1.0 (July 26th 2017)

  • proof of concept for the correct generation of a liturgical calendar
  • create MySQL table for the Proper of the Saints