Merge pull request #285 from Liturgical-Calendar/JohnRDOrazio/issue284

JohnRDOrazio/issue284

.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,15 +59,34 @@ _(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/">

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": "*"