Migrate to CodeIgniter 4 and PHP 8.5

.dockerignore

@@ -5,8 +5,9 @@
 !Dockerfile
 
 # Include application specific files
-!system/
-!application/
+!app/
+!composer.json
+!composer.lock
 
 # Include Node package files
 !package.json

.env.example

@@ -0,0 +1,19 @@
+CI_ENVIRONMENT = production
+app.baseURL = 'http://localhost:8080/'
+app.defaultLocale = en
+
+database.default.hostname = lisa-mariadb
+database.default.database = lisa
+database.default.username = lisa
+database.default.password = lisa
+database.default.DBDriver = MySQLi
+database.default.port = 3306
+
+email.fromEmail = 'lisa@example.com'
+email.fromName = 'Lisa'
+# email.protocol = smtp
+# email.SMTPHost = smtp.example.com
+# email.SMTPUser = ''
+# email.SMTPPass = ''
+# email.SMTPPort = 587
+# email.SMTPCrypto = tls

.github/workflows/continuous-integration.yaml

@@ -28,6 +28,9 @@ jobs:
     - name: Wait until test environment is up
       run: npx wait-on http-get://localhost:8080/Install
 
+    - name: PHP 8.5 migration regression checks
+      run: docker compose exec -T php-fpm composer test
+
     - name: Cypress run
       uses: cypress-io/github-action@v6.7.8
       with:

.gitignore

@@ -15,11 +15,20 @@ user_guide_src/cilexer/build/*
 user_guide_src/cilexer/dist/*
 user_guide_src/cilexer/pycilexer.egg-info/*
 /vendor/
+/.env
+/writable/*
+!/writable/.htaccess
+!/writable/index.html
+!/writable/*/
+/writable/*/*
+!/writable/*/index.html
 
 node_modules/
 
 # Ignore Cypress' video recordings
 *.mp4
+/cypress/screenshots/
+/cypress/videos/
 
 # IDE Files
 #-------------------------

README.md

@@ -1,4 +1,6 @@
 # LISA
+LISA runs on CodeIgniter 4.7.5 or newer and PHP 8.5.
+
 [![Continuous Integration](https://github.com/Addono/LISA/actions/workflows/continuous-integration.yaml/badge.svg)](https://github.com/Addono/LISA/actions/workflows/continuous-integration.yaml)
 [![All Contributors](https://img.shields.io/badge/all_contributors-3-orange.svg)](#contributors)
 [![Project Status: Inactive – The project has reached a stable, usable state but is no longer being actively developed; support/maintenance will be provided as time allows.](https://www.repostatus.org/badges/latest/inactive.svg)](https://www.repostatus.org/#inactive)
@@ -15,27 +17,19 @@ Many use-cases can be imagined, in general LISA gives each user an integer sized
 
 ```bash
 # Clone the repository
-git clone https://github.com/Addono/lisa && cd lisa
+git clone https://github.com/Addono/LISA.git && cd LISA
 
 # Install dependencies
-npm install
-
-# (Optional) Configure the database, the defaults are for a docker compose instance
-vim application/config/database.php
+npm ci
 
-# (Optional) Configure general settings, setting the hostname is mandatory
-# by default it is set to http://localhost:8080, if your Docker instance
-# is not at localhost, then you need to set $config['base_url'] manually 
-# in application/config/config.php
-vim application/config/config.php
-
-# (Optional) Although you will get nasty errors in your logs whenever it
-# tries to send email.
-vim application/config/email.php
+# Configure the URL, database, locale, and optional SMTP settings
+cp .env.example .env
 
 # Configuration is finished, let's deploy the application and all required services
-docker compose up -d
+docker compose up --build -d
 ```
+The PHP container installs the locked Composer dependencies and prepares `writable/` before starting PHP-FPM. The default database settings match Docker Compose. Change `app.baseURL` in `.env` when using another hostname. Never commit `.env` or expose it through your web server.
+
 One small last thing we need to do is to run all database migrations, either point your browser at [http://localhost:8080/install](http://localhost:8080/install) or run`curl http://localhost:8080/install`.
 
 :rocket: And we are live at [http://localhost:8080](http://localhost:8080) :rocket:
@@ -46,18 +40,35 @@ _Note: Depending on how you installed Docker it might be that Docker is not acce
 
 ### Manual
 Requirements:
- * PHP 7* with the mysqli extension enabled.
- * MySQL database
+ * PHP 8.5 with `intl`, `mbstring`, and `mysqli` extensions.
+ * Composer 2, Node.js, and npm.
+ * MySQL or MariaDB.
+
+1. Clone the repository, run `composer install` and `npm ci`.
+2. Copy `.env.example` to `.env` and configure your URL, database, locale, and SMTP server.
+3. Configure the web server's document root as `public/`, not the repository root. Forward dynamic requests to `public/index.php` and serve `/node_modules/` from the installed frontend dependencies, as shown in the Nginx configuration.
+4. Make `writable/` writable by the PHP process. Application code and `vendor/` must not be publicly accessible.
+5. Open `/Install` to initialize the database, then change the default administrator password.
+
+### Migrating an Existing Installation
+
+Back up the database and the old configuration before deployment. This is a CI3-to-CI4 application conversion, following the [official migration guide](https://codeigniter4.github.io/userguide/installation/upgrade_4xx.html).
 
- 1. Download a copy/make a clone/make a fork of the project and move it to a folder in your web server.
- 1. Rename or copy  `config.php-setup`, `database.php-setup` and `email.php-config` to `config.php`, `database.php` and `email.php` respectively, these files can be found in `application/config/`.
- 1. Edit these config files to match your system.
-    * Add your hostname in `config.php`.
-    * Enter the settings of your database in `database.php`.
-    * (Optional, but recommended) Configure an SMTP server in `email.php`.
- 1. Navigate to __YOUR_HOSTNAME__/index.php/Install to initialize the database.
+Move your database, URL, SMTP, and language settings from the old `application/config/` files into `.env` using the names in `.env.example`. Existing tables, password hashes, model-version keys, and transaction data are retained. Preserve any configured database table prefix with `database.default.DBPrefix`. Do not import a fresh database or recreate existing tables. Running `/Install` again applies only outstanding schema versions. Existing sessions are replaced, so users must log in again.
+
+The source lives in `app/`; the framework is installed under `vendor/`. The old `application/`, bundled `system/`, and root entry point are no longer used. Keep the `/Install` endpoint restricted to operators in production, and configure SMTP to deliver low-credit notifications.
+
+### Verification
+
+```bash
+# Isolated regression checks; requires the sqlite3 extension
+docker compose exec -T php-fpm composer test
+
+# Browser checks against the running MariaDB-backed application
+npx cypress run --record false
+```
 
-*The Docker Compose deploy method and the CI are using 7.4. The version used there is leading and the only one supported.
+The regression checks use an in-memory database and do not modify application data. Cypress uses the running application and creates test users; run it against a development database.
 
 ## Development Environment
 
@@ -88,7 +99,7 @@ Afterwards, use the admin user to create new users, which can be done in the bac
 ## Customisation
 
 ### Language
-Currently, the language used by the application is hard-coded into `Handler.php`, for future releases it is planned to move configurations like these into the database. For now, one should edit hard-coded language or substitute all language files in the `nederlands` language folder with your language of preference. During development I tried to add translations for both English and Dutch, so the English translation files should be complete.
+Set `app.defaultLocale = en` or `app.defaultLocale = nl` in `.env`. Frontend translations are in `app/Language/<locale>/Lisa.php`; administrator translations are in `Admin.php`. The existing default, application, and custom dictionaries have been combined into these files.
 
 ## Contributors✨
 

system/.htaccess → app/.htaccess

@@ -3,4 +3,4 @@
 </IfModule>
 <IfModule !authz_core_module>
 	Deny from all
-</IfModule>
+</IfModule>

app/Common.php

@@ -0,0 +1,15 @@
+<?php
+
+/**
+ * The goal of this file is to allow developers a location
+ * where they can overwrite core procedural functions and
+ * replace them with their own. This file is loaded during
+ * the bootstrap process and is called during the framework's
+ * execution.
+ *
+ * This can be looked at as a `master helper` file that is
+ * loaded early on, and may also contain additional functions
+ * that you'd like to use throughout your entire application
+ *
+ * @see: https://codeigniter.com/user_guide/extending/common.html
+ */

app/Config/App.php

@@ -0,0 +1,202 @@
+<?php
+
+namespace Config;
+
+use CodeIgniter\Config\BaseConfig;
+
+class App extends BaseConfig
+{
+    /**
+     * --------------------------------------------------------------------------
+     * Base Site URL
+     * --------------------------------------------------------------------------
+     *
+     * URL to your CodeIgniter root. Typically, this will be your base URL,
+     * WITH a trailing slash:
+     *
+     * E.g., http://example.com/
+     */
+    public string $baseURL = 'http://localhost:8080/';
+
+    /**
+     * Allowed Hostnames in the Site URL other than the hostname in the baseURL.
+     * If you want to accept multiple Hostnames, set this.
+     *
+     * E.g.,
+     * When your site URL ($baseURL) is 'http://example.com/', and your site
+     * also accepts 'http://media.example.com/' and 'http://accounts.example.com/':
+     *     ['media.example.com', 'accounts.example.com']
+     *
+     * @var list<string>
+     */
+    public array $allowedHostnames = [];
+
+    /**
+     * --------------------------------------------------------------------------
+     * Index File
+     * --------------------------------------------------------------------------
+     *
+     * Typically, this will be your `index.php` file, unless you've renamed it to
+     * something else. If you have configured your web server to remove this file
+     * from your site URIs, set this variable to an empty string.
+     */
+    public string $indexPage = '';
+
+    /**
+     * --------------------------------------------------------------------------
+     * URI PROTOCOL
+     * --------------------------------------------------------------------------
+     *
+     * This item determines which server global should be used to retrieve the
+     * URI string. The default setting of 'REQUEST_URI' works for most servers.
+     * If your links do not seem to work, try one of the other delicious flavors:
+     *
+     *  'REQUEST_URI': Uses $_SERVER['REQUEST_URI']
+     * 'QUERY_STRING': Uses $_SERVER['QUERY_STRING']
+     *    'PATH_INFO': Uses $_SERVER['PATH_INFO']
+     *
+     * WARNING: If you set this to 'PATH_INFO', URIs will always be URL-decoded!
+     */
+    public string $uriProtocol = 'REQUEST_URI';
+
+    /*
+    |--------------------------------------------------------------------------
+    | Allowed URL Characters
+    |--------------------------------------------------------------------------
+    |
+    | This lets you specify which characters are permitted within your URLs.
+    | When someone tries to submit a URL with disallowed characters they will
+    | get a warning message.
+    |
+    | As a security measure you are STRONGLY encouraged to restrict URLs to
+    | as few characters as possible.
+    |
+    | By default, only these are allowed: `a-z 0-9~%.:_-`
+    |
+    | Set an empty string to allow all characters -- but only if you are insane.
+    |
+    | The configured value is actually a regular expression character group
+    | and it will be used as: '/\A[<permittedURIChars>]+\z/iu'
+    |
+    | DO NOT CHANGE THIS UNLESS YOU FULLY UNDERSTAND THE REPERCUSSIONS!!
+    |
+    */
+    public string $permittedURIChars = 'a-z 0-9~%.:_\-';
+
+    /**
+     * --------------------------------------------------------------------------
+     * Default Locale
+     * --------------------------------------------------------------------------
+     *
+     * The Locale roughly represents the language and location that your visitor
+     * is viewing the site from. It affects the language strings and other
+     * strings (like currency markers, numbers, etc), that your program
+     * should run under for this request.
+     */
+    public string $defaultLocale = 'en';
+
+    /**
+     * --------------------------------------------------------------------------
+     * Negotiate Locale
+     * --------------------------------------------------------------------------
+     *
+     * If true, the current Request object will automatically determine the
+     * language to use based on the value of the Accept-Language header.
+     *
+     * If false, no automatic detection will be performed.
+     */
+    public bool $negotiateLocale = false;
+
+    /**
+     * --------------------------------------------------------------------------
+     * Supported Locales
+     * --------------------------------------------------------------------------
+     *
+     * If $negotiateLocale is true, this array lists the locales supported
+     * by the application in descending order of priority. If no match is
+     * found, the first locale will be used.
+     *
+     * IncomingRequest::setLocale() also uses this list.
+     *
+     * @var list<string>
+     */
+    public array $supportedLocales = ['en', 'nl'];
+
+    /**
+     * --------------------------------------------------------------------------
+     * Application Timezone
+     * --------------------------------------------------------------------------
+     *
+     * The default timezone that will be used in your application to display
+     * dates with the date helper, and can be retrieved through app_timezone()
+     *
+     * @see https://www.php.net/manual/en/timezones.php for list of timezones
+     *      supported by PHP.
+     */
+    public string $appTimezone = 'UTC';
+
+    /**
+     * --------------------------------------------------------------------------
+     * Default Character Set
+     * --------------------------------------------------------------------------
+     *
+     * This determines which character set is used by default in various methods
+     * that require a character set to be provided.
+     *
+     * @see http://php.net/htmlspecialchars for a list of supported charsets.
+     */
+    public string $charset = 'UTF-8';
+
+    /**
+     * --------------------------------------------------------------------------
+     * Force Global Secure Requests
+     * --------------------------------------------------------------------------
+     *
+     * If true, this will force every request made to this application to be
+     * made via a secure connection (HTTPS). If the incoming request is not
+     * secure, the user will be redirected to a secure version of the page
+     * and the HTTP Strict Transport Security (HSTS) header will be set.
+     */
+    public bool $forceGlobalSecureRequests = false;
+
+    /**
+     * --------------------------------------------------------------------------
+     * Reverse Proxy IPs
+     * --------------------------------------------------------------------------
+     *
+     * If your server is behind a reverse proxy, you must whitelist the proxy
+     * IP addresses from which CodeIgniter should trust headers such as
+     * X-Forwarded-For or Client-IP in order to properly identify
+     * the visitor's IP address.
+     *
+     * You need to set a proxy IP address or IP address with subnets and
+     * the HTTP header for the client IP address.
+     *
+     * Here are some examples:
+     *     [
+     *         '10.0.1.200'     => 'X-Forwarded-For',
+     *         '192.168.5.0/24' => 'X-Real-IP',
+     *     ]
+     *
+     * @var array<string, string>
+     */
+    public array $proxyIPs = [];
+
+    /**
+     * --------------------------------------------------------------------------
+     * Content Security Policy
+     * --------------------------------------------------------------------------
+     *
+     * Enables the Response's Content Secure Policy to restrict the sources that
+     * can be used for images, scripts, CSS files, audio, video, etc. If enabled,
+     * the Response object will populate default values for the policy from the
+     * `ContentSecurityPolicy.php` file. Controllers can always add to those
+     * restrictions at run time.
+     *
+     * For a better understanding of CSP, see these documents:
+     *
+     * @see http://www.html5rocks.com/en/tutorials/security/content-security-policy/
+     * @see http://www.w3.org/TR/CSP/
+     */
+    public bool $CSPEnabled = false;
+}