Merge branch '3.3.x'

.devcontainer/Dockerfile

@@ -0,0 +1,20 @@
+# Debian version
+ARG VARIANT="buster"
+FROM mcr.microsoft.com/vscode/devcontainers/base:0-${VARIANT}
+
+# Install PHP
+RUN apt-get -y update
+RUN apt-get -y install php php-xml php-mbstring php-curl php-zip php-xdebug
+
+# Install Composer
+RUN curl -sS https://getcomposer.org/installer | php -- --install-dir=/usr/local/bin --filename=composer
+
+# Install MySQL
+RUN apt-get -y install mysql-server php-mysql
+
+# Xdebug
+ADD resources/xdebug.ini /etc/php/8.1/apache2/conf.d/xdebug.ini
+
+# Configure Apache
+RUN echo "Listen 8080" >> /etc/apache2/ports.conf && \
+    a2enmod rewrite

.devcontainer/devcontainer.json

@@ -0,0 +1,37 @@
+// For format details, see https://aka.ms/devcontainer.json. For config options, see the README at:
+// https://github.com/microsoft/vscode-dev-containers/tree/v0.238.1/containers/ubuntu
+{
+	"name": "Ubuntu",
+	"build": {
+		"dockerfile": "Dockerfile",
+		// Update 'VARIANT' to pick an Ubuntu version: jammy / ubuntu-22.04, focal / ubuntu-20.04, bionic /ubuntu-18.04
+		// Use ubuntu-22.04 or ubuntu-18.04 on local arm64/Apple Silicon.
+		"args": { "VARIANT": "ubuntu-22.04" }
+	},
+
+	// Configure tool-specific properties.
+	"customizations": {
+		// Configure properties specific to VS Code.
+		"vscode": {
+			"settings": {
+				// Allow Xdebug to listen to requests from remote (or container)
+				"remote.localPortHost": "allInterfaces"
+			},
+			//"devPort": {},
+			// Specify which VS Code extensions to install (List of IDs)
+			"extensions": ["xdebug.php-debug"]
+			}
+		},
+
+	// Use 'forwardPorts' to make a list of ports inside the container available locally.
+	"forwardPorts": [80, 9003],
+
+	// Use 'postCreateCommand' to run commands after the container is created.
+	"postStartCommand": "bash .devcontainer/resources/setup.sh",
+
+	// Comment out to connect as root instead. More info: https://aka.ms/vscode-remote/containers/non-root.
+	"remoteUser": "vscode",
+	"features": {
+		"github-cli": "latest"
+	}
+}

.devcontainer/resources/phpbb-config.yml

@@ -0,0 +1,38 @@
+installer:
+    admin:
+        name: admin
+        password: adminadmin
+        email: admin@example.org
+
+    board:
+        lang: en
+        name: My Board
+        description: My amazing new phpBB board
+
+    database:
+        dbms: mysqli
+        dbhost: 127.0.0.1
+        dbport: 3306
+        dbuser: phpbb
+        dbpasswd: phpbb
+        dbname: phpbb
+        table_prefix: phpbb_
+
+    email:
+        enabled: false
+        smtp_delivery : ~
+        smtp_host: ~
+        smtp_port: ~
+        smtp_auth: ~
+        smtp_user: ~
+        smtp_pass: ~
+
+    server:
+        cookie_secure: false
+        server_protocol: http://
+        force_server_vars: false
+        server_name: localhost
+        server_port: 80
+        script_path: /
+
+    extensions: []

.devcontainer/resources/setup.sh

@@ -0,0 +1,44 @@
+# setup.sh
+# Commands to install and configure phpBB
+
+# Start MySQL
+echo "[Codespaces] Start MySQL"
+sudo service mysql start
+
+# Start Apache
+echo "[Codespaces] Start Apache"
+sudo service apache2 start
+
+# Add SSH key
+echo "[Codespaces] Add SSH key"
+echo "$SSH_KEY" > /home/vscode/.ssh/id_rsa && chmod 600 /home/vscode/.ssh/id_rsa
+
+# Create a MySQL user to use
+echo "[Codespaces] Create MySQL user"
+sudo mysql -u root<<EOFMYSQL
+    CREATE USER 'phpbb'@'localhost' IDENTIFIED BY 'phpbb';
+    GRANT ALL PRIVILEGES ON *.* TO 'phpbb'@'localhost' WITH GRANT OPTION;
+    CREATE DATABASE IF NOT EXISTS phpbb;
+EOFMYSQL
+
+# Download dependencies
+echo "[Codespaces] Install Composer dependencies"
+composer install --no-interaction
+
+# Symlink the webroot so it can be viewed
+echo "[Codespaces] Create Symlink of webroot"
+sudo rm -rf /var/www/html
+sudo ln -s /workspaces/phpbb/phpBB /var/www/html
+
+# Copy phpBB config
+echo "[Codespaces] Copy phpBB configuration"
+cp /workspaces/phpbb/.devcontainer/resources/phpbb-config.yml /workspaces/phpbb/phpBB/install/install-config.yml
+
+# Install phpBB
+echo "[Codespaces] Run phpBB CLI installation"
+cd /workspaces/phpbb/phpBB && composer install --no-interaction
+sudo php /workspaces/phpbb/phpBB/install/phpbbcli.php install /workspaces/phpbb/phpBB/install/install-config.yml
+rm -rf /workspaces/phpbb/phpBB/install
+
+# Finished
+echo "[Codespaces] phpBB installation completed"

.devcontainer/resources/xdebug.ini

@@ -0,0 +1,10 @@
+zend_extension=xdebug.so
+
+[xdebug]
+xdebug.mode=develop,debug
+xdebug.discover_client_host=1
+xdebug.client_port=9003
+xdebug.start_with_request=yes
+xdebug.log='/var/log/xdebug/xdebug.log'
+xdebug.connect_timeout_ms=2000
+xdebug.idekey=VSCODE

.vscode/launch.json

@@ -0,0 +1,18 @@
+{
+    // Use IntelliSense to learn about possible attributes.
+    // Hover to view descriptions of existing attributes.
+    // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
+    "version": "0.2.0",
+    "configurations": [
+        {
+            "name": "Debug phpBB",
+            "type": "php",
+            "request": "launch",
+            "port": 9003,
+            "pathMappings": {
+                "/var/www/html": "${workspaceRoot}/phpBB/"
+            },
+            "log": true
+        }
+    ]
+}

.vscode/settings.json

@@ -0,0 +1,3 @@
+{
+    "php.debug.ideKey": "VSCODE"
+}

README.md

@@ -27,7 +27,10 @@ To run an installation from the repo (and not from a pre-built package) on a loc
   php ../composer.phar install
   ```
 
-Alternatively, you can read our [Vagrant documentation](phpBB/docs/vagrant.md) to find out how to use Vagrant to develop and contribute to phpBB.
+Alternatively, you can read:
+
+* Our [Vagrant documentation](phpBB/docs/vagrant.md) to find out how to use Vagrant to develop and contribute to phpBB.
+* Our [GitHub Codespaces documentation](phpBB/docs/codespaces.md) to learn about phpBB's cloud-based development environment.
 
 ## 📓 Documentation
 

phpBB/docs/codespaces.md

@@ -0,0 +1,55 @@
+## Using GitHub Codespaces with phpBB
+
+phpBB includes support for [Codespaces](https://docs.github.com/en/codespaces), GitHub's cloud-based software development environment. This allows developers and contributors to run and modify phpBB on a consistent environment through a GitHub account without the need to set up a local web server.
+
+Codespaces is completely web-based and does not require any code to be downloaded locally.
+
+Features include:
+
+* Automatic phpBB installation
+* Access to [VS Code](https://docs.github.com/en/codespaces/the-githubdev-web-based-editor) through the web browser 
+* [Xdebug](https://github.com/xdebug/vscode-php-debug) pre-configured to step through the phpBB code and add breakpoints
+* Full LAMP stack with database access
+* Commit, push and test code entirely online
+
+## How it works
+
+### To run phpBB in Codespaces
+
+* On the GitHub.com website, fork the `phpbb/phpbb` repository.
+* Under the `Code` button, click the `Codespaces` tab and then the `+` button to create a new Codespace.
+* It may take several minutes to configure and install phpBB on the newly created virtual machine. Once it is ready, a web-based VS Code instance will appear.
+* Under the `Ports` tab, click on the local address under port 80 to open the private website for the new phpBB installation.
+    * By default, the login details for the new phpBB installation are `admin` / `adminadmin`
+    * Port 9003 is also open to allow Xdebug connections.
+
+### To use the command line
+
+* Click on the `Terminal` tab at the bottom of VS Code and make sure the `bash` window is selected in the right sidebar.
+* The `workspaces/phpbb` directory contains the code from the workspace.
+* Run `mysql -h 127.0.0.1 -u phpbb -p` to log into the MySQL database. The password is `phpbb` and the database name is `phpbb`.
+    * Tip: type `use phpbb;` after logging in to MySQL to switch to the correct database, then queries can be run for the phpBB tables.
+
+### To debug code
+
+* Click the `Run and Debug` tab on the left sidebar in VS Code, then click the green play button next to the `Debug phpBB` option.
+    * Tip: to confirm that Xdebug is working correctly, run `lsof -i :9003` on the command line. It should show that the port is listening for connections.
+* In any of the files in the `phpBB/` directory, add a breakpoint by clicking just to the left of a line number in VS Code. Then, access the private website created on port 80 (found under the VS Code `Ports` tab) through the web browser and navigate to the page with a breakpoint. VS Code will automatically pause execution where the breakpoint is hit, and under the `Run and Debug` tab a variable list will be shown.
+
+### To commit and push code
+
+* To save a change made using VS Code on Codespaces, click the `Source Control` tab on the left sidebar in VS Code.
+* To stage changes or discard changes, right click the file(s) and select the appropriate option.
+* Type a commit message and select the `Commit and Push` option.
+
+**Remember to stop a Codespace once you are finished with it.** GitHub provides all users with a limited number of free core hours per month. A Codespace can be stopped (or deleted) from the main repository page on GitHub.com.
+
+## Technical information
+
+All of the Codespaces configuration can be found in the `.devcontainer/` directory. The `devcontainer.json` holds the general environment information and `Dockerfile` contains the commands to set up the LAMP stack which enables phpBB to run.
+
+`setup.sh` is used to install phpBB from the command line, using pre-determined details from `phpbb-config.yml`.
+
+Codespaces can run without the configuration inside the `.vscode/` directory, however by including this no manual intervention is required to set the Xdebug IDE code to `VSCode` (inside `settings.json`) and  `Debug phpBB` information, such as the path mapping from the Apache webroot to the `phpbb/phpBB` directory (inside `launch.json`).
+
+This configuration information can be safely modified to change the development environment, followed by `Ctrl+Shift+P` in VS Code and selection of the `Full Rebuild Container` option.