Merge branch 'master' into use-xml-from-robrichards

Author: DaanRijpkema

.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/dependabot.yaml

@@ -1,7 +1,30 @@
 version: 2
+
 updates:
-  - package-ecosystem: "composer"
-    directory: "/"
+  - package-ecosystem: composer
+    directory: /
     schedule:
-      interval: "weekly"
+      interval: weekly
     open-pull-requests-limit: 10
+    versioning-strategy: increase-if-necessary
+    labels:
+      - dependencies
+    groups:
+      php-platform:
+        patterns:
+          - php
+        update-types:
+          - minor
+          - patch
+      composer-minor-and-patch:
+        patterns:
+          - "*"
+        exclude-patterns:
+          - php
+        update-types:
+          - minor
+          - patch
+    ignore:
+      - dependency-name: php
+        versions:
+          - "<8.3"

.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
-                  bootstrap: vendor/autoload.php
+                  php_version: ${{ matrix.php-version }}
+                  version: 11
+                  bootstrap: ./vendor/autoload.php
                   configuration: ./.github/workflows/phpunit.xml

.github/workflows/phpunit.xml

@@ -1,8 +1,19 @@
 <?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" cacheDirectory=".phpunit.cache">
+<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"
+>
   <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>
+</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

@@ -0,0 +1,30 @@
+test_unit:
+	@printf 'Running unit tests:\n';
+	./vendor/bin/phpunit tests/Unit --testdox --display-errors --display-warnings --display-deprecations --display-phpunit-deprecations --display-notices
+
+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 --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

@@ -1,4 +1,4 @@
-![Bluem](https://bluem.nl/img/BluemAboutIcon.svg)
+<img width="250" height="250" alt="image" src="https://github.com/user-attachments/assets/c1e56d5e-87c6-41db-8076-880255523f86" />
 
 **Bluem-php for Payment, Mandates, iDIN & IBAN-Name check**
 
@@ -50,14 +50,19 @@ Utilized by other applications as well:
 * [Appendices](#appendices)
     + [List of all supported BICs per context](#list-of-all-supported-bics-per-context)
 
-## Requirements
-- Update April 2024: Since our release >= 2.4, **PHP 8.1** is the minimum required version for this library. Previous releases requires **PHP 8.0**.
+
+# Requirements & Versioning
+## 3.0 is coming with PHP 8.3 support and requirement
+A new version of the PHP library will be released in the coming 1-2 months.
+Starting this release, **PHP 8.3** is the minimum required version for this library.
+- 2026: Starting at our release >= 3.0, **PHP 8.3** is the minimum required version for this library. Previous releases requires **PHP 8.1**.
+- 2024: Starting at our release >= 2.4, **PHP 8.1** is the minimum required version for this library. Previous releases requires **PHP 8.0**.
 - Update April 2023: Since our release >= 2.3, **PHP 8.0** is the minimum required version for this library. Previous releases requires **PHP 7.4**.
 
 - Please use the [major git releases](https://github.com/bluem-development/bluem-php/releases) for the stable versions of this plugin.
 - Refer to the `composer.json` requirements for any other dependencies
 
-## Getting started
+# Getting started
 Install the library through [Composer](https://getcomposer.org). Run Composer to install this library and dependencies from your project folder.
 
 ```bash
@@ -74,6 +79,8 @@ See [Changelog](changelog.md)
 ## 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:
 ```
@@ -245,6 +252,12 @@ To use Carte Bancaire, use the following method:
 $request = $request->setPaymentMethodToCarteBancaire(); 
 ```
 
+To use Bancontact, use the following method
+```php
+$request = $request->setPaymentMethodToBancontact();
+```
+
+
 These methods will throw an exception if required information is missing.
 
 Once the request executes, the link to the transaction will send you to the Bluem Portal with the corresponding interface and flow.
@@ -790,12 +803,12 @@ To be able to use webhook functionality, retrieve a copy of the Webhook certific
 #### ePayments
 - ABN AMRO  <BR> BIC: `ABNANL2A`
 - ASN Bank  <BR> BIC: `ASNBNL21`
+- ASN (previously SNS)   <BR> BIC: `SNSBNL2A`
 - bunq  <BR> BIC: `BUNQNL2A`
 - ING   <BR> BIC: `INGBNL2A`
 - Knab  <BR> BIC: `KNABNL2H`
 - Rabobank  <BR> BIC: `RABONL2U`
 - RegioBank <BR> BIC: `RBRBNL21`
-- SNS   <BR> BIC: `SNSBNL2A`
 - Triodos Bank  <BR> BIC: `TRIONL2U`
 - Van Lanschot  <BR> BIC: `FVLBNL22`
 - Revolut   <BR> BIC: `REVOLT21`
@@ -805,10 +818,10 @@ To be able to use webhook functionality, retrieve a copy of the Webhook certific
 #### eMandates CORE
 - ABN AMRO  <BR> BIC: `ABNANL2A`
 - ASN Bank  <BR> BIC: `ASNBNL21`
+- ASN (previously SNS)   <BR> BIC: `SNSBNL2A`
 - ING   <BR> BIC: `INGBNL2A`
 - Rabobank  <BR> BIC: `RABONL2U`
 - RegioBank <BR> BIC: `RBRBNL21`
-- SNS   <BR> BIC: `SNSBNL2A`
 - Triodos Bank  <BR> BIC: `TRIONL2U`
 #### eMandates B2B
 - ABN AMRO  <BR> BIC: `ABNANL2A`
@@ -818,11 +831,11 @@ To be able to use webhook functionality, retrieve a copy of the Webhook certific
 #### Identity
 - ABN AMRO  <BR> BIC: `ABNANL2A`
 - ASN Bank  <BR> BIC: `ASNBNL21`
+- ASN (previously SNS)   <BR> BIC: `SNSBNL2A`
 - bunq  <BR> BIC: `BUNQNL2A`
 - ING   <BR> BIC: `INGBNL2A`
 - Rabobank  <BR> BIC: `RABONL2U`
 - RegioBank <BR> BIC: `RBRBNL21`
-- SNS   <BR> BIC: `SNSBNL2A`
 
 Please note: Knab with BIC: `KNABNL2H` does not support eMandates CORE anymore as of 4th of October 2023.
 

composer.json

@@ -24,8 +24,13 @@
     "support": {
         "issues": "https://github.com/bluem-development/bluem-php"
     },
+    "config": {
+        "platform": {
+            "php": "8.3"
+        }
+    },
     "require": {
-        "php": ">=8.1",
+        "php": ">=8.3",
         "ext-dom": "*",
         "ext-libxml": "*",
         "ext-simplexml": "*",
@@ -41,12 +46,11 @@
         }
     },
     "require-dev": {
-        "phpunit/phpunit": "^9.5",
+        "phpunit/phpunit": "^12",
         "phpspec/prophecy": "~1.0",
         "vlucas/phpdotenv": "^5.4",
-        "rector/rector": "^0.15.10",
+        "rector/rector": "^2.4",
         "squizlabs/php_codesniffer": "^3.7",
-        "magento/magento-coding-standard": "^31.0",
         "phpcompatibility/php-compatibility": "^9.3"
     },
     "prefer-stable": true,