Merge pull request #287 from Liturgical-Calendar/development

Prepare v4.1 release

.env.example

@@ -0,0 +1,16 @@
+### .env.example
+### The following environment variables are useful for Unit Test websocket server
+### In a local development environment, copy this file to .env.development to ensure that Unit Test websocket server will run locally
+###  and will use the local API instance to run tests.
+### Set the same value for WS_PORT in the Unit Test frontend project folder.
+### For more information, see https://github.com/Liturgical-Calendar/LiturgicalCalendarAPI/blob/development/LitCalTestServer.php
+
+WS_PORT=8080
+API_PROTOCOL=http
+API_HOST=localhost
+API_PORT=8000 # will not determine on which port the API will launch, only on which port the Unit Test server will look for the API
+# When production, the API will add `/api/{version}` to the path
+# where {version} is the version of the API that is automatically detected
+# based on the current folder name (dev, v3, v4...).
+# When development, no path will be added.
+APP_ENV=development # development | production

.gitignore

@@ -8,3 +8,6 @@ ValidateTestsAgainstSchema.php
 .envrc
 debuginfo.php
 testYaml.php
+.env
+.env.*
+!.env.example

.vscode/tasks.json

@@ -44,6 +44,15 @@
             "dependsOn": [
                 "launch-browser"
             ]
+        },
+        {
+            "label": "litcal-tests-websockets",
+            "type": "shell",
+            "command": "php LitCalTestServer.php",
+            "group": {
+                "kind": "build",
+                "isDefault": true
+            }
         }
     ]
 }

LitCalTestServer.php

@@ -10,17 +10,33 @@
 use Ratchet\Http\HttpServer;
 use Ratchet\WebSocket\WsServer;
 use LiturgicalCalendar\Api\Health;
+use Dotenv\Dotenv;
 
-$apiVersion = basename(__DIR__);
-define('API_BASE_PATH', "https://litcal.johnromanodorazio.com/api/{$apiVersion}");
+$dotenv = Dotenv::createImmutable(__DIR__, ['.env', '.env.local', '.env.development', '.env.production'], false);
+$dotenv->ifPresent(['API_PROTOCOL', 'API_HOST'])->notEmpty();
+$dotenv->ifPresent(['API_PORT'])->isInteger();
+$dotenv->ifPresent(['APP_ENV'])->notEmpty()->allowedValues(['development', 'production']);
+$dotenv->ifPresent(['WS_PROTOCOL', 'WS_HOST'])->notEmpty();
+$dotenv->ifPresent(['WS_PORT'])->isInteger();
+$dotenv->safeLoad();
+$API_PROTOCOL = $_ENV['API_PROTOCOL'] ?? 'https';
+$API_HOST = $_ENV['API_HOST'] ?? 'litcal.johnromanodorazio.com';
+$API_PORT = $_ENV['API_PORT'] ?? 443;
+
+if (isset($_ENV['APP_ENV']) && $_ENV['APP_ENV'] === 'development') {
+    define('API_BASE_PATH', "{$API_PROTOCOL}://{$API_HOST}:{$API_PORT}");
+} else {
+    $apiVersion = basename(__DIR__);
+    define('API_BASE_PATH', "{$API_PROTOCOL}://{$API_HOST}/api/{$apiVersion}");
+}
 
 $server = IoServer::factory(
     new HttpServer(
         new WsServer(
             new Health()
         )
     ),
-    8080
+    $_ENV['WS_PORT'] ?? 8080
 );
 
 $server->run();

README.md

@@ -42,8 +42,8 @@ Some characteristics of this API:
 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.
 
 * The [first example](https://litcal.johnromanodorazio.com/examples/php/) uses cURL in PHP to make a request to the endpoint and handle the results.
-* The [second example](https://litcal.johnromanodorazio.com/examples/javascript/) uses AJAX in Javascript to make the request to the endpoint and handle the results.
-* The [third example](https://litcal.johnromanodorazio.com/examples/fullcalendar/examples/month-view.html) makes use of the [FullCalendar javascript framework](https://github.com/fullcalendar/fullcalendar) to display the results from the AJAX request in a nicely formatted calendar view.
+* The [second example](https://litcal.johnromanodorazio.com/examples/javascript/) uses `fetch` in Javascript to make the request to the endpoint and handle the results.
+* The [third example](https://litcal.johnromanodorazio.com/examples/fullcalendar/examples/month-view.html) makes use of the [FullCalendar javascript framework](https://github.com/fullcalendar/fullcalendar) to display the results from the `fetch` request in a nicely formatted calendar view.
 * The [fourth example](https://litcal.johnromanodorazio.com/examples/fullcalendar/examples/messages.html) is the same as the third except that it outputs the Messages first and the [FullCalendar](https://github.com/fullcalendar/fullcalendar) calendar view after.
 
 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...
@@ -59,22 +59,44 @@ _(See [usage.php#calSubscription](https://litcal.johnromanodorazio.com/usage.php
 
 # Testing locally
 
+System requirements:
+* PHP >= 8.1
+* PHP modules installed and enabled: `intl` * `zip` * `gettext` * `calendar` * `yaml`
+* System language packs for all the supported languages
+
+## Using PHP's builtin server
+
 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:
 ```bash
 PHP_CLI_SERVER_WORKERS=2 php -S localhost:8000
 ```
 
+## Using a docker container
+
 For convenience when using VSCode, a `tasks.json` has been defined so that you can simply type <kbd>CTRL</kbd>+<kbd>SHIFT</kbd>+<kbd>B</kbd> (<kbd>CMD</kbd>+<kbd>SHIFT</kbd>+<kbd>B</kbd> on MacOS) to start the PHP builtin server and open the browser.
 
+To further simplify your setup, without having to worry about getting all the system requirements in place, you can also launch the API in a docker container using the repo `Dockerfile`:
+
+```bash
+# If you haven't cloned the repo locally, you can build directly from the remote repo (replace `{branch}` with the branch or tag from which you want to build):
+docker build -t liturgy-api:{branch} https://github.com/Liturgical-Calendar/LiturgicalCalendarAPI.git#{branch}
+# If instead you have cloned the repo locally, you can build from the local repo (replace `{branch}` with the branch or tag that you have checked out locally):
+docker build -t liturgy-api:{branch} .
+docker run -p 8000:8000 -d liturgy-api:{branch}
+```
+
 # Translations
 
 <a href="https://translate.johnromanodorazio.com/engage/liturgical-calendar/">
 <img src="https://translate.johnromanodorazio.com/widgets/liturgical-calendar/-/open-graph.png" alt="Translation status" />
 </a>
 
 # CHANGELOG
+## [v4.1](https://github.com/JohnRDOrazio/LiturgicalCalendar/releases/tag/v4.1) (January 22nd 2025)
+* restore diocesan calendar `PUT`, `PATCH` and `DELETE` requests with full support for all i18n languages (issue #284)
+
 ## [v4.0](https://github.com/JohnRDOrazio/LiturgicalCalendar/releases/tag/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
@@ -89,13 +111,13 @@ For convenience when using VSCode, a `tasks.json` has been defined so that you c
 * 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](https://github.com/Liturgical-Calendar/LiturgicalCalendarAPI/issues/237)
-* fix Chritmas weekdays should not be created when there is an obligatory memorial, see commit a8ca47744582d89aaed195658a40a22145659eee
+* fix Christmas 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](https://github.com/Liturgical-Calendar/LiturgicalCalendarAPI/issues/271)
 * add abbreviated form of the liturgical rank / grade to the `Festivity` output, see issue [#251](https://github.com/Liturgical-Calendar/LiturgicalCalendarAPI/issues/251)
 * use ISO 3166-1 Alpha-2 codes to identify nations, see issue [#231](https://github.com/Liturgical-Calendar/LiturgicalCalendarAPI/issues/231)
 * created an interface that allows to create Unit Tests, see issue [#205](https://github.com/Liturgical-Calendar/LiturgicalCalendarAPI/issues/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: Immaculate Conception 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](https://github.com/Liturgical-Calendar/LiturgicalCalendarAPI/issues/248)
 * feature: discoverability of supported locales, see issue [#240](https://github.com/Liturgical-Calendar/LiturgicalCalendarAPI/issues/240)
 * feature: all national and diocesan calendars are now multilingual by default, see issue [#150](https://github.com/Liturgical-Calendar/LiturgicalCalendarAPI/issues/150)

composer.json

@@ -8,7 +8,8 @@
         "php": ">=8.1",
         "swaggest/json-schema": "~0.12",
         "cboden/ratchet": "~0.4",
-        "sabre/vobject": "^4.5.1"
+        "sabre/vobject": "^4.5.1",
+        "vlucas/phpdotenv": "^5.6"
     },
     "require-dev": {
         "squizlabs/php_codesniffer": "*"