Full PHP 8.3 support

.githooks/pre-commit

@@ -0,0 +1,11 @@
+#!/bin/sh
+set -eu
+
+if git diff --cached --name-only --diff-filter=ACM | grep -qE '\.php$'; then
+  echo "PHP files changed — running unit tests..."
+  make test_unit
+
+  make lint
+else
+  echo "No PHP changes — skipping unit tests."
+fi

.github/workflows/ci.yml

@@ -1,30 +1,47 @@
 name: CI
-
 on: [push]
-
 jobs:
     build-test:
         runs-on: ubuntu-latest
+        strategy:
+            matrix:
+                # add 8.4 soon
+                php-version: ['8.3']
 
         steps:
             - name: Checkout code
-              uses: actions/checkout@v2
+              uses: actions/checkout@v4
 
             - name: Setup .env
               run: cp .env.example .env
 
+            - name: Setup ownership
+              run: git config --global --add safe.directory /app
+
             - name: Replace placeholders with GitHub Secrets
               run: |
                 sed -i "s/BLUEM_SENDER_ID=S/BLUEM_SENDER_ID=${{ secrets.BLUEM_SENDER_ID }}/g" .env
                 sed -i "s/BLUEM_TEST_ACCESS_TOKEN=/BLUEM_TEST_ACCESS_TOKEN=${{ secrets.BLUEM_TEST_ACCESS_TOKEN }}/g" .env
 
+            - name: Setup PHP
+              uses: shivammathur/setup-php@v2
+              with:
+                  php-version: ${{ matrix.php-version }}
+                  extensions: mbstring, intl
+                  coverage: xdebug
+
             - name: Run composer
-              uses: php-actions/composer@v5
+              uses: php-actions/composer@v6
+              with:
+                  php_version: ${{ matrix.php-version }}
+
+            - name: PHPCS Lint
+              run: make lint
 
             - name: PHPUnit Tests
-              uses: php-actions/phpunit@v3
+              uses: php-actions/phpunit@v4
               with:
-                  version: 9.5
-                  php_version: 8.1
+                  php_version: ${{ matrix.php-version }}
+                  version: 11
                   bootstrap: ./vendor/autoload.php
                   configuration: ./.github/workflows/phpunit.xml

.github/workflows/phpunit.xml

@@ -7,7 +7,13 @@
 >
   <testsuites>
     <testsuite name="Unit">
-      <directory suffix="Test.php">../../tests</directory>
+      <directory suffix="Test.php">../../tests/Unit</directory>
+    </testsuite>
+    <testsuite name="Integration">
+      <directory suffix="Test.php">../../tests/Integration</directory>
+    </testsuite>
+    <testsuite name="Acceptance">
+      <directory suffix="Test.php">../../tests/Acceptance</directory>
     </testsuite>
   </testsuites>
 </phpunit>

AGENTS.md

@@ -0,0 +1,35 @@
+# AGENTS.md
+
+## Project at a glance
+- `bluem-php` is a PHP 8.3 library for Bluem payment flows: Payments, eMandates, iDIN, and IBAN-name check.
+- `src/Bluem.php` is the main orchestration layer: it builds requests, validates XML, sends them through `Transport/`, and turns responses into `Responses/*` objects.
+- `src/Webhook.php` handles inbound webhook XML and is intentionally strict: HTTPS POST + `text/xml; charset=UTF-8` + XML/signature validation.
+
+## Code structure to preserve
+- `src/Contexts/*` defines service-specific bank/BIC sets and XSD schema paths (`IdentityContext`, `PaymentsContext`, `MandatesContext`).
+- `src/Requests/*` owns XML/endpoint generation; `src/Responses/*` wraps `SimpleXMLElement` parsing.
+- `src/Transport/` isolates HTTP; `CurlHttpTransport` is the default and is injected into `Bluem` for testability.
+- `src/Validators/*` enforces XML and webhook constraints; do not bypass these checks in higher layers.
+
+## Conventions specific to this repo
+- Public API names are legacy-compatible and intentionally mixed-case in places (`CreateMandateRequest`, `PerformRequest`, `getConfig`, `Webhook::getPurchaseID()`); avoid renaming unless you are ready to update downstream consumers.
+- `phpcs.xml.dist` uses PSR-12 with narrow exceptions for legacy method/property naming and file-header ordering.
+- Existing code mixes older style and newer strict typing; prefer small, behavior-preserving edits over broad refactors.
+
+## Developer workflow
+- Install deps with `composer install`.
+- Lint with `make lint`; auto-fix style with `make lint_fix`.
+- Run unit tests with `make test_unit` or `./vendor/bin/phpunit tests/Unit`.
+- Run live tests with `make test_integration` / `make test_acceptance`; these require `.env`.
+- CI (`.github/workflows/ci.yml`) runs on PHP 8.3, then `make lint`, then PHPUnit.
+
+## Environment and testing
+- Copy `.env.example` to `.env` for integration/acceptance tests.
+- Required env vars are enforced in `tests/Integration/BluemGenericTestCase.php`: `BLUEM_ENV`, `BLUEM_SENDER_ID`, `BLUEM_BRANDID`, `BLUEM_TEST_ACCESS_TOKEN`, `BLUEM_MERCHANTID`, `BLUEM_MERCHANTRETURNURLBASE`.
+- Unit tests typically use a fake transport; integration tests extend the shared base case and hit live Bluem services.
+
+## When changing code
+- Update request/response/context pieces together so XML shape, endpoint URL, and validation stay aligned.
+- Check `validation/*.xsd` and `examples/` when touching service-specific payloads.
+- Keep webhook validation strict; relaxing HTTPS, content-type, or signature checks is a security regression.
+

Makefile

@@ -5,4 +5,26 @@ test_unit:
 test_integration:
 	@printf 'Running integration tests:\n';
 	@echo "Note: Ensure you have the necessary environment variables set for integration tests in the .env file."
-	./vendor/bin/phpunit tests/Integration
+	./vendor/bin/phpunit tests/Integration --testdox --display-errors --display-warnings --display-deprecations --display-phpunit-deprecations --display-notices
+
+test_acceptance:
+	@printf 'Running acceptance tests:\n';
+	./vendor/bin/phpunit tests/Acceptance --testdox --display-errors --display-warnings --display-deprecations --display-phpunit-deprecations --display-notices
+
+test:
+	@printf 'Running all tests:\n';
+	make test_unit;
+	make test_acceptance;
+	make test_integration;
+
+lint:
+	./vendor/bin/phpcs --standard=phpcs.xml.dist --extensions=php --ignore=vendor/ .
+
+lint_fix:
+	./vendor/bin/phpcbf --standard=phpcs.xml.dist --extensions=php --ignore=vendor/ .
+
+
+setup-git-hooks:
+	@echo "Setting up Git hooks..."
+	git config core.hooksPath .githooks
+	chmod +x .githooks/pre-commit

README.md

@@ -150,6 +150,8 @@ No earlier changelog was recorded. Please refer to the [commit log](https://gith
 ## Testing
 For improving future features, unit testing is introduced since november 2021.
 
+The repository also has a PHPCS linting setup: `make lint` runs the shared ruleset from `phpcs.xml.dist`, and CI uses the same lint step so local and automated checks stay aligned. That XML file also contains a few narrow exceptions for legacy naming and file-header issues, which lets the existing public API stay intact without failing the build on historical style violations.
+
 Tests are located in the `tests` folder
 To run tests:
 ```

composer.json

@@ -14,6 +14,11 @@
     "support": {
         "issues": "https://github.com/bluem-development/bluem-php"
     },
+    "config": {
+        "platform": {
+            "php": "8.3"
+        }
+    },
     "require": {
         "php": ">=8.3",
         "ext-dom": "*",

phpcs.xml.dist

@@ -0,0 +1,29 @@
+<?xml version="1.0"?>
+<ruleset name="Bluem">
+    <description>Project PHPCS rules with narrow exceptions for the legacy public API.</description>
+
+    <config name="ignore_warnings_on_exit" value="1" />
+
+    <file>src</file>
+    <file>tests</file>
+    <file>examples</file>
+    <file>rector.php</file>
+
+    <exclude-pattern>vendor/*</exclude-pattern>
+
+    <rule ref="PSR12">
+        <exclude name="PSR12.Files.FileHeader.IncorrectOrder" />
+    </rule>
+
+    <rule ref="PSR1.Methods.CamelCapsMethodName">
+        <exclude name="PSR1.Methods.CamelCapsMethodName.NotCamelCaps" />
+    </rule>
+
+    <rule ref="PSR2.Methods.MethodDeclaration">
+        <exclude name="PSR2.Methods.MethodDeclaration.Underscore" />
+    </rule>
+
+    <rule ref="PSR2.Classes.PropertyDeclaration">
+        <exclude name="PSR2.Classes.PropertyDeclaration.Underscore" />
+    </rule>
+</ruleset>

phpunit.xml

@@ -1,11 +1,14 @@
 <?xml version="1.0" encoding="UTF-8"?>
-<phpunit xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" bootstrap="vendor/autoload.php" colors="true" stopOnFailure="false" xsi:noNamespaceSchemaLocation="https://schema.phpunit.de/10.0/phpunit.xsd">
+<phpunit bootstrap="vendor/autoload.php" colors="true" stopOnFailure="false">
   <testsuites>
     <testsuite name="Unit">
       <directory suffix="Test.php">./tests/Unit</directory>
     </testsuite>
     <testsuite name="Integration">
       <directory suffix="Test.php">./tests/Integration</directory>
     </testsuite>
+    <testsuite name="Acceptance">
+      <directory suffix="Test.php">./tests/Acceptance</directory>
+    </testsuite>
   </testsuites>
 </phpunit>