format all pure PHP files with prettier (#338)

Author: simonLeary42

.github/workflows/phpunit.yml

@@ -9,19 +9,15 @@ jobs:
   docker-compose-phpunit:
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@v3
-      with:
-        submodules: true
-    - name: setup PHP
-      uses: shivammathur/setup-php@v2
-      with:
-        php-version: "8.3"
-        tools: composer
-    - name: install composer dependencies
-      run: composer update
-    - name: Run docker compose
-      uses: hoverkraft-tech/[email protected]
-      with:
-        compose-file: "./tools/docker-dev/docker-compose.yml"
-    - name: Execute tests in the running services
-      run: docker compose -f ./tools/docker-dev/docker-compose.yml exec -w '/var/www/unity-web-portal' web bash -c 'XDEBUG_MODE=coverage ./vendor/bin/phpunit --coverage-clover="$(mktemp --suffix=.xml)" -d --min-coverage=./coverage.php'
+      - uses: actions/checkout@v3
+        with:
+          submodules: true
+      - uses: shivammathur/setup-php@v2
+        with:
+          php-version: "8.3"
+          tools: composer
+      - run: composer install --dev
+      - uses: hoverkraft-tech/[email protected]
+        with:
+          compose-file: "./tools/docker-dev/docker-compose.yml"
+      - run: docker compose -f ./tools/docker-dev/docker-compose.yml exec -w '/var/www/unity-web-portal' web bash -c 'XDEBUG_MODE=coverage ./vendor/bin/phpunit --coverage-clover="$(mktemp --suffix=.xml)" -d --min-coverage=./coverage.php'

.github/workflows/pre-commit.yml

@@ -9,13 +9,15 @@ jobs:
   pre-commit:
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@v3
-      with:
-        submodules: true
-    - uses: actions/setup-python@v3
-    - name: setup PHP
-      uses: shivammathur/setup-php@v2
-      with:
-        php-version: "8.3"
-        tools: composer, phpcs, phpcbf
-    - uses: pre-commit/[email protected]
+      - uses: actions/checkout@v3
+        with:
+          submodules: true
+      - uses: actions/setup-python@v3
+      - uses: shivammathur/setup-php@v2
+        with:
+          php-version: "8.3"
+          tools: composer
+      - run: composer install --dev
+      - uses: actions/[email protected]
+      - run: npm install --dev
+      - uses: pre-commit/[email protected]

.gitignore

@@ -20,3 +20,5 @@ deployment/**/*
 !deployment/**/README.md
 
 .phpunit.result.cache
+
+node_modules

.pre-commit-config.yaml

@@ -11,19 +11,64 @@ repos:
     hooks:
       - id: trailing-whitespace
       - id: end-of-file-fixer
+        # https://github.com/prettier/plugin-php/issues/2430
+        exclude: workers/.*
+
+  - repo: https://github.com/rbubley/mirrors-prettier
+    rev: v3.4.2
+    hooks:
+      - id: prettier
+        exclude: |
+          (?x)^(
+              composer\.json|
+              composer\.lock|
+          )$
 
   - repo: local
     hooks:
       - id: phpcbf
         name: PHP Code Beautifier and Fixer
-        entry: phpcbf
+        entry: ./vendor/bin/phpcbf
+        args: [--standard=./.phpcs-ruleset.xml, --colors]
         language: system
         files: \.php$
-        args: [--standard=./.phpcs-ruleset.xml, --colors]
+        # exclude pure PHP files
         exclude: |
           (?x)^(
               test/.*|
               workers/.*|
+              node_modules/.*|
+              resources/lib/phpopenldaper/.*|
+              vendor/.*|
+              resources/lib/.*|
+          )$
+
+  - repo: local
+    hooks:
+      - id: prettier (php)
+        name: prettier (php)
+        entry: npx
+        args:
+          [
+            -p,
+            prettier,
+            -p,
+            "@prettier/plugin-php",
+            prettier,
+            --plugin=@prettier/plugin-php,
+            --php-version=8.3,
+            --write,
+          ]
+        language: system
+        files: \.php$
+        # exclude impure PHP files
+        exclude: |
+          (?x)^(
+              node_modules/.*|
+              resources/lib/phpopenldaper/.*|
+              vendor/.*|
+              resources/templates/.*|
+              webroot/.*|
           )$
 
   # linters (work required) ########################################################################
@@ -45,14 +90,19 @@ repos:
     hooks:
       - id: phpcs
         name: PHP CodeSniffer
-        entry: phpcs
+        entry: ./vendor/bin/phpcs
         language: system
         files: \.php$
         args: [--standard=./.phpcs-ruleset.xml, --colors]
+        # exclude pure PHP files
         exclude: |
           (?x)^(
               test/.*|
               workers/.*|
+              node_modules/.*|
+              resources/lib/phpopenldaper/.*|
+              vendor/.*|
+              resources/lib/.*|
           )$
       - id: php-l
         name: php -l

CONTRIBUTING.md

@@ -2,24 +2,25 @@
 
 ## Conventions
 
-* PHP version 8.3.
-* All files are required to be linted with PSR-12 standard.
-* The maximum line length for any PHP file is 100 characters, instead of PSR-12's 120 characters.
-* Comments should be used sparingly.
-* Empty lines should be used sparingly.
-* No code should fail quietly, instead exceptions should be thrown.
+- PHP version 8.3.
+- All pure PHP files are required to be formatted with Prettier.
+- All impure PHP files (mixed into HTML) are required to be linted with PSR-12 and formatted with `phpcbf`.
+- The maximum line length for any PHP file is 100 characters.
+- Comments should be used sparingly.
+- Empty lines should be used sparingly.
+- No code should fail quietly, instead exceptions should be thrown.
   PHP builtin functions that fail quietly (ex: `json_encode`) should be replaced with a wrapper in `resources/utils.php`.
-* No code should call `die()` or `exit()`, instead `UnityHTTPD::die()`.
+- No code should call `die()` or `exit()`, instead `UnityHTTPD::die()`.
   This will avoid the premature death of our automated testing processes.
-* No code should call `assert()`, instead `\ensure()`.
+- No code should call `assert()`, instead `\ensure()`.
   This will enforce conditions even in production.
-* No code should call `json_encode()`, instead `\jsonEncode()`.
+- No code should call `json_encode()`, instead `\jsonEncode()`.
   This will throw errors and escape slashes by default.
-* No code should call `mb_convert_encoding()`, instead `\mbConvertEncoding()`.
+- No code should call `mb_convert_encoding()`, instead `\mbConvertEncoding()`.
   This will throw an exception rather than returning `false`.
-* No code should call `mb_detect_encoding()`, instead `\mbDetectEncoding()`.
+- No code should call `mb_detect_encoding()`, instead `\mbDetectEncoding()`.
   This will enable strict mode and throw an exception rather than returning `false`.
-* `UnityHTTPD`'s user-facing error functionality (ex: `badRequest`) should only be called from `webroot/**/*.php`.
+- `UnityHTTPD`'s user-facing error functionality (ex: `badRequest`) should only be called from `webroot/**/*.php`.
   `resources/**/*.php` should throw exceptions instead.
 
 This repository will automatically check PRs for linting compliance.
@@ -29,6 +30,7 @@ This repository will automatically check PRs for linting compliance.
 ### Setting up your Environment
 
 1. Clone this repo (including submodules): `git clone <this-repo> --recurse-submodules`
+1. Install php v8.3
 1. install [composer](https://getcomposer.org/)
 1. install PHP dependencies: `composer update`
 1. If you're on Windows, use [WSL](https://learn.microsoft.com/en-us/windows/wsl/)
@@ -38,15 +40,17 @@ This repository will automatically check PRs for linting compliance.
 1. Install [pre-commit](https://pre-commit.com/)
 1. setup pre-commit hooks: `pre-commit install`
 1. Install modern implementation of grep (not macOS builtin grep): `brew install grep`
+1. Install `npm`
+1. Install nodeJS tools: `npm install`
 
 ### Environment Usage
 
 While the environment is running, the following is accessible:
 
-* http://127.0.0.1:8000 - Web Portal
-* http://127.0.0.1:8010 - PHPLDAPAdmin Portal
-* http://127.0.0.1:8020 - PHPMyAdmin Portal
-* http://127.0.0.1:8030 - Mailcatcher Portal
+- http://127.0.0.1:8000 - Web Portal
+- http://127.0.0.1:8010 - PHPLDAPAdmin Portal
+- http://127.0.0.1:8020 - PHPMyAdmin Portal
+- http://127.0.0.1:8030 - Mailcatcher Portal
 
 ### Test Users
 
@@ -55,9 +59,10 @@ When accessing locked down portions of the portal, you will be asked for a usern
 The password is always `password`. `tools/docker-dev/web/htpasswd` contains all valid usernames.
 
 Notable users:
-* `[email protected]` - admin, PI
-* `[email protected]` - not admin, not PI
-* `[email protected]` - does not yet have an account
+
+- `[email protected]` - admin, PI
+- `[email protected]` - not admin, not PI
+- `[email protected]` - does not yet have an account
 
 ### Changes to Dev Environment
 
@@ -86,13 +91,15 @@ Once a user action has been taken, internal interfaces are used to verify the re
 To run `phpunit`, spawn 2 shells in differnt tabs:
 
 tab 1:
+
 ```shell
 cd ./tools/docker-dev
 ./build.sh
 ./run.sh
 ```
 
 tab 2:
+
 ```
 $ container="$(docker container ls | grep web | awk '{print $1}')"
 $ docker exec -it "$container" bash
@@ -138,6 +145,7 @@ When writing a test, it may be tempting to use the PHP API directly, but the HTT
 Example:
 
 using the PHP API:
+
 ```php
 private function requestGroupCreation()
 {
@@ -146,6 +154,7 @@ private function requestGroupCreation()
 ```
 
 using the HTTP API:
+
 ```php
 private function requestGroupCreation()
 {