Chore: Fix dev env friction, bump PHP floor to 8.3, add PHP matrix (#245)

* Chore: Fix dev env friction, bump PHP floor to 8.3, add PHP matrix

- Dockerfiles now ship composer, composer.json/lock, phpstan.neon, pint.json
  so composer scripts (test/analyze/format) work in-container
- CONTRIBUTING: document host-native inner loop; fix wrong service name
  (web -> fpm); drop stale psalm reference; add swoole exec path
- Drop PHP 8.2 support; bump require/platform pin and FPM base image to 8.3
- CI unit job runs a matrix over PHP 8.3 / 8.4 / 8.5 with per-version
  composer cache keys; coverage (pcov + clover artifact) collected on 8.3
- example/docker-compose.yml: drop deprecated version key

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* Chore: Regenerate composer.lock for PHP 8.3 floor

The require.php / platform bump changed composer.json's content-hash,
so the lock was reporting out-of-date.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: loks0n

.github/workflows/ci.yml

@@ -25,7 +25,7 @@ jobs:
 
       - uses: shivammathur/setup-php@v2
         with:
-          php-version: '8.2'
+          php-version: '8.3'
           extensions: swoole
           coverage: none
 
@@ -49,16 +49,20 @@ jobs:
         run: composer analyze
 
   unit:
-    name: Tests / Unit
+    name: Tests / Unit / PHP ${{ matrix.php }}
     runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        php: ['8.3', '8.4', '8.5']
     steps:
       - uses: actions/checkout@v6
 
       - uses: shivammathur/setup-php@v2
         with:
-          php-version: '8.2'
+          php-version: ${{ matrix.php }}
           extensions: swoole
-          coverage: none
+          coverage: ${{ matrix.php == '8.3' && 'pcov' || 'none' }}
 
       - name: Get composer cache directory
         id: composer-cache
@@ -67,15 +71,28 @@ jobs:
       - uses: actions/cache@v5
         with:
           path: ${{ steps.composer-cache.outputs.dir }}
-          key: composer-${{ hashFiles('composer.lock') }}
-          restore-keys: composer-
+          key: composer-${{ matrix.php }}-${{ hashFiles('composer.lock') }}
+          restore-keys: composer-${{ matrix.php }}-
 
       - name: Install dependencies
         run: composer install --prefer-dist --no-progress --no-interaction --ignore-platform-req=ext-opentelemetry
 
       - name: Run unit tests
+        if: matrix.php != '8.3'
         run: vendor/bin/phpunit --configuration phpunit.xml --testsuite unit
 
+      - name: Run unit tests with coverage
+        if: matrix.php == '8.3'
+        run: vendor/bin/phpunit --configuration phpunit.xml --testsuite unit --coverage-text --coverage-clover coverage.xml
+
+      - name: Upload coverage artifact
+        if: matrix.php == '8.3' && always()
+        uses: actions/upload-artifact@v7
+        with:
+          name: coverage-clover
+          path: coverage.xml
+          if-no-files-found: ignore
+
   e2e:
     name: Tests / E2E / ${{ matrix.adapter.display }}
     runs-on: ubuntu-latest

CONTRIBUTING.md

@@ -64,11 +64,33 @@ $ git push origin [name_of_your_new_branch]
 8. After approval, merge your PR
 9. GitHub will automatically delete the branch after the merge is done. (they can still be restored).
 
-### Testing
+### Development environment
 
-- `docker compose up -d`
-- `docker compose exec web  vendor/bin/phpunit --configuration phpunit.xml`
-- `docker compose exec web vendor/bin/psalm --show-info=true`
+The repo ships two server adapters (FPM and Swoole), each with its own container. For most inner-loop work you don't need Docker — install deps on the host and run the unit suite directly:
+
+```
+composer install --ignore-platform-req=ext-opentelemetry
+composer test        # unit suite
+composer analyze     # PHPStan
+composer format:check
+composer format      # auto-fix
+```
+
+The end-to-end suites need the adapter containers:
+
+```
+docker compose up -d --build
+docker compose exec fpm    vendor/bin/phpunit --configuration phpunit.xml --testsuite e2e-fpm
+docker compose exec swoole vendor/bin/phpunit --configuration phpunit.xml --testsuite e2e-swoole
+```
+
+You can also run the unit suite and lint/analyze inside either container — `composer.json`, `phpstan.neon`, and `pint.json` are all present in the image:
+
+```
+docker compose exec fpm composer test
+docker compose exec fpm composer analyze
+docker compose exec fpm composer format:check
+```
 
 ## Introducing New Features
 

Dockerfile.fpm

@@ -13,7 +13,7 @@ RUN composer install --ignore-platform-reqs --optimize-autoloader \
     --no-plugins --no-scripts --prefer-dist \
     `if [ "$TESTING" != "true" ]; then echo "--no-dev"; fi`
 
-FROM php:8.2-fpm-alpine AS final
+FROM php:8.3-fpm-alpine AS final
 LABEL maintainer="team@appwrite.io"
 
 ENV DEBIAN_FRONTEND=noninteractive \
@@ -34,10 +34,14 @@ COPY ./tests/docker/www.conf /usr/local/etc/php-fpm.d/www.conf
 # Script
 COPY ./tests/docker/start /usr/local/bin/start
 
+# Composer binary (for running scripts inside the container)
+COPY --from=composer:2.7 /usr/bin/composer /usr/local/bin/composer
+
 # Add PHP Source Code
 COPY ./src /usr/share/nginx/html/src
 COPY ./tests /usr/share/nginx/html/tests
 COPY ./phpunit.xml /usr/share/nginx/html/phpunit.xml
+COPY ./composer.json ./composer.lock ./phpstan.neon ./pint.json /usr/share/nginx/html/
 COPY --from=step0 /usr/local/src/vendor /usr/share/nginx/html/vendor
 
 # Supervisord Conf

Dockerfile.swoole

@@ -18,9 +18,13 @@ LABEL maintainer="team@appwrite.io"
 
 WORKDIR /usr/src/code
 
+# Composer binary (for running scripts inside the container)
+COPY --from=composer:2.7 /usr/bin/composer /usr/local/bin/composer
+
 COPY ./src /usr/src/code/src
 COPY ./tests /usr/src/code/tests
 COPY ./phpunit.xml /usr/src/code/phpunit.xml
+COPY ./composer.json ./composer.lock ./phpstan.neon ./pint.json /usr/src/code/
 COPY --from=step0 /usr/local/src/vendor /usr/src/code/vendor
 
 EXPOSE 80

README.md

@@ -259,7 +259,7 @@ To learn more about architecture and features for this library, check out more i
 
 ## System Requirements
 
-Utopia HTTP requires PHP 8.2 or later. We recommend using the latest PHP version whenever possible.
+Utopia HTTP requires PHP 8.3 or later. We recommend using the latest PHP version whenever possible.
 
 ## More from Utopia
 

composer.json

@@ -28,7 +28,7 @@
         "test": "vendor/bin/phpunit --configuration phpunit.xml"
     },
     "require": {
-        "php": ">=8.2",
+        "php": ">=8.3",
         "utopia-php/di": "0.3.*",
         "utopia-php/servers": "0.3.*",
         "utopia-php/compression": "0.1.*",
@@ -40,7 +40,7 @@
     },
     "config": {
         "platform": {
-            "php": "8.2",
+            "php": "8.3",
             "ext-opentelemetry": "1.0.0",
             "ext-protobuf": "4.26.1"
         },

composer.lock

@@ -269,6 +269,6 @@ Http::shutdown(function($request) {
 # Running Locally
 If you have PHP and Composer installed on your device, you can run Utopia apps locally by downloading the `utopia-php/http` dependency using `composer require utopia-php/http` command.
 
-> Utopia HTTP requires PHP 8.2 or later. We recommend using the latest PHP version whenever possible.
+> Utopia HTTP requires PHP 8.3 or later. We recommend using the latest PHP version whenever possible.
 
 Wonderful! 😄  You’re all set to create a basic demo app using the Utopia HTTP. If you have any issues or questions feel free to reach out to us on our [Discord Server](https://appwrite.io/discord).

docs/Getting-Starting-Guide.md

@@ -1,5 +1,3 @@
-version: '3'
-
 services:
   server:
     build: