Methods documentation.

Author: andrew-svirin

AGENTS.md

@@ -0,0 +1,145 @@
+# Project Guide — ebics-client-php
+
+## Overview
+
+PHP library to communicate with banks through the **EBICS** protocol (Electronic Banking Internet Communication Standard).  
+Supports EBICS versions 2.4, 2.5, 3.0 and signature/encryption variants E002, X002, A005, A006.
+
+## Technology Stack
+
+| Item | Version |
+|------|---------|
+| **PHP** | 8.5+ (`^8.5`) |
+| **PHPUnit** | ~10.5 |
+| **PHPStan** | ~2.1 |
+| **PHPCS** | ~3.13 (PSR-12) |
+| **Composer** | latest |
+
+### Required PHP Extensions
+
+`bcmath`, `curl`, `dom`, `json`, `openssl`, `zip`, `zlib`, `libxml`
+
+## Docker Environment
+
+The project uses Docker for a consistent development environment.
+
+```
+docker/
+├── docker-compose.yml
+└── php-cli/
+    ├── Dockerfile          (php:8.5.4-cli + xdebug + extensions)
+    └── php.ini
+```
+
+### Docker Compose
+
+| Target | Image | Container Name |
+|--------|-------|----------------|
+| `php-cli-ebics-client-php` | `php-cli-ebics-client-php:8.5.4-cli` | `php-cli-ebics-client-php` |
+
+Network mode: **host** (for easy access to local services).  
+Xdebug is pre-installed and enabled (port 9003).
+
+### Makefile Targets
+
+| Command | Alias | Description |
+|---------|-------|-------------|
+| `make docker-up` | `u`, `start` | Start Docker containers |
+| `make docker-down` | `d`, `stop` | Stop Docker containers |
+| `make docker-build` | `build` | Rebuild Docker images |
+| `make docker-install` | `install` | Run `composer install` in container |
+| `make docker-php` | `php` | Open a bash shell in the PHP container |
+| `make check` | — | Run PHPCBF, PHPCS, PHPStan, PHPUnit |
+| `make credentials-pack` | — | Zip test credentials |
+| `make credentials-unpack` | — | Unzip test credentials |
+
+### Composer Scripts (run inside Docker)
+
+| Command | Description |
+|---------|-------------|
+| `composer code-test` | Run PHPUnit tests |
+| `composer code-style` | Run PHPCS |
+| `composer code-analyse` | Run PHPStan |
+
+## Directory Structure
+
+```
+├── src/                    # PSR-4: EbicsApi\Ebics\
+│   ├── Contracts/          # Interfaces
+│   ├── Exceptions/         # Custom exception classes
+│   ├── Factories/          # Factory classes (Crypt, Signature, etc.)
+│   ├── Models/             # Data models (Key, KeyPair, Keyring, Buffer, etc.)
+│   ├── Services/           # Business logic services
+│   └── EbicsClient.php     # Main client entry point
+├── tests/                  # PSR-4: EbicsApi\Ebics\Tests\
+│   ├── _data/              # Test data & keyring files
+│   ├── _fixtures/          # Test fixtures (XML files, keys)
+│   ├── _workspace/         # Generated test artifacts
+│   └── AbstractEbicsTestCase.php  # Base test class with helpers
+├── doc/schema/             # EBICS XSD schemas
+└── docker/                 # Docker configuration
+```
+
+## Coding Standards
+
+- **PSR-12** coding style (enforced by PHPCS).
+- **PHPStan** level enforced via `phpstan.neon`.
+- Source code lives in `src/`; tests live in `tests/`.
+- PHPCS targets `src/` only (tests excluded in `phpcs.xml`).
+- Tests may use snake_case method names where needed (PHPCS exclusion).
+
+## Running Commands
+
+All commands execute **inside Docker**:
+
+```bash
+# Start environment
+make docker-up
+
+# Run full quality check
+make check
+
+# Or individually:
+docker compose -p ebics-client-php exec php-cli-ebics-client-php ./vendor/bin/phpunit
+docker compose -p ebics-client-php exec php-cli-ebics-client-php ./vendor/bin/phpcs
+docker compose -p ebics-client-php exec php-cli-ebics-client-php ./vendor/bin/phpstan
+
+# Open shell
+make docker-php
+```
+
+## Testing Conventions
+
+- Base class: `AbstractEbicsTestCase` (provides client setup, keyring, credentials).
+- Test groups (PHPUnit `@group`): e.g. `@group crypt-services`.
+- Credentials stored in `tests/_data/credentials/credentials_<id>.json`.
+- Keyrings stored in `tests/_data/workspace/keyring_<id>.json`.
+- Fixtures (static XML/JSON) in `tests/_fixtures/`.
+
+### Client Setup Helpers
+
+```php
+// In any test extending AbstractEbicsTestCase:
+$client = $this->setupClientV24($credentialsId);  // EBICS 2.4
+$client = $this->setupClientV25($credentialsId);  // EBICS 2.5
+$client = $this->setupClientV30($credentialsId);  // EBICS 3.0
+```
+
+### Fake / Debug HTTP Clients
+
+Pass `$fake = true` or `$debug = true` to `setupClient*()` to use `FakerHttpClient` (returns fixture data) or `DebuggerHttpClient` (logs requests).
+
+## Key Concepts
+
+| Concept | Description |
+|---------|-------------|
+| **Keyring** | Holds user & bank signatures (A = authentication, X = signing, E = encryption), passwords, and optional X.509 certificates. |
+| **Signature A** | Authentication signature (versions A005 / A006). |
+| **Signature X** | Transaction signing (version X002). |
+| **Signature E** | Encryption (version E002). |
+| **CryptService** | All crypto ops: hashing, AES-128-CBC encrypt/decrypt, RSA sign/encrypt, key generation, nonces, order IDs. |
+| **KeyPair** | Public key + private key + password bundle. |
+
+## Notable Implementation Details
+
+- Classes marked `@internal` may change without notice.

CHANGELOG.md

@@ -1,5 +1,6 @@
 ## 3.1
 
+* Documentation detailization.
 * Safety improvements.
 
 ## 3.0

phpunit.xml

@@ -4,7 +4,8 @@
          bootstrap="tests/bootstrap.php"
          colors="true"
          beStrictAboutOutputDuringTests="true"
-         cacheResult="false">
+         cacheResult="false"
+         failOnDeprecation="true">
     <source>
         <include>
             <directory>src</directory>

src/Contracts/SignatureInterface.php

@@ -5,21 +5,54 @@
 use EbicsApi\Ebics\Models\Crypt\Key;
 
 /**
- * EBICS SignatureInterface representation.
+ * EBICS Signature interface.
+ *
+ * Represents a cryptographic signature used in EBICS protocol communication.
+ * Each signature type serves a specific role:
+ *
+ * - **Type A** (Authentication): Authenticates the user to the bank.
+ *   Versions: `A005` (RSA-PKCS#1 v1.5), `A006` (RSA-PSS).
+ * - **Type X** (Signing): Signs transaction data. Version: `X002`.
+ * - **Type E** (Encryption): Encrypts data transfer. Version: `E002`.
  *
  * @license http://www.opensource.org/licenses/mit-license.html  MIT License
  * @author Andrew Svirin
  */
 interface SignatureInterface
 {
+    /**
+     * Authentication signature version 5 (RSA-PKCS#1 v1.5 with SHA-256).
+     */
     const A_VERSION5 = 'A005';
+
+    /**
+     * Authentication signature version 6 (RSA-PSS with SHA-256).
+     */
     const A_VERSION6 = 'A006';
 
+    /**
+     * Encryption signature version 2.
+     */
     const E_VERSION2 = 'E002';
+
+    /**
+     * Transaction signing signature version 2.
+     */
     const X_VERSION2 = 'X002';
 
+    /**
+     * Authentication signature type identifier.
+     */
     const TYPE_A = 'A';
+
+    /**
+     * Transaction signing signature type identifier.
+     */
     const TYPE_X = 'X';
+
+    /**
+     * Encryption signature type identifier.
+     */
     const TYPE_E = 'E';
 
     /**

src/Factories/Crypt/AESFactory.php

@@ -6,7 +6,10 @@
 use EbicsApi\Ebics\Models\Crypt\AES;
 
 /**
- * Class AESFactory represents producers for the @see AES.
+ * AES factory for creating AES cryptographic instances.
+ *
+ * Produces `AESInterface` instances used for symmetric encryption/decryption
+ * (typically AES-128-CBC) in EBICS data transfer pipelines.
  *
  * @license http://www.opensource.org/licenses/mit-license.html  MIT License
  * @author Andrew Svirin

src/Factories/Crypt/RSAFactory.php

@@ -8,7 +8,11 @@
 use EbicsApi\Ebics\Models\Crypt\RSA;
 
 /**
- * Class RSAFactory represents producers for the @see RSA.
+ * RSA factory for creating RSA cryptographic instances.
+ *
+ * Produces `RSAInterface` instances configured as private or public keys.
+ * Decouples the concrete RSA implementation from business logic, allowing
+ * different underlying libraries to be swapped via the class map.
  *
  * @license http://www.opensource.org/licenses/mit-license.html  MIT License
  * @author Andrew Svirin
@@ -32,7 +36,9 @@ public function __construct(?array $classMap = null)
     }
 
     /**
-     * @param int $type
+     * Create an RSA instance by key type identifier.
+     *
+     * @param int $type Key type constant (e.g. RSA::PRIVATE_FORMAT_PKCS1).
      * @return RSAInterface
      */
     public function create(int $type): RSAInterface

src/Models/Buffer.php

@@ -6,7 +6,12 @@
 use RuntimeException;
 
 /**
- * Buffer class.
+ * Buffer wraps a file stream for chunked read/write operations.
+ *
+ * This model provides a stream-based buffer abstraction used throughout
+ * encryption/decryption pipelines. It supports opening files, reading/writing
+ * data in chunks, seeking, and applying stream filters. The buffer tracks
+ * remaining length and automatically closes the stream on destruction.
  *
  * @license http://www.opensource.org/licenses/mit-license.html  MIT License
  * @author Andrew Svirin

src/Models/Crypt/ASN1.php

@@ -665,6 +665,7 @@ public function asn1map($decoded, $mapping, $special = [])
                             continue;
                         }
                         $maymatch = true;
+                        $candidate = null;
                         if ($child['type'] != self::TYPE_CHOICE) {
                             $childClass = self::CLASS_UNIVERSAL;
                             $constant = null;

src/Models/Crypt/Key.php

@@ -3,7 +3,10 @@
 namespace EbicsApi\Ebics\Models\Crypt;
 
 /**
- * Key.
+ * Cryptographic key wrapper.
+ *
+ * Holds raw key material (PEM string or binary) and its type identifier
+ * (e.g. `RSA::PRIVATE_FORMAT_PKCS1`, `RSA::PUBLIC_FORMAT_PKCS1`).
  *
  * @license http://www.opensource.org/licenses/mit-license.html  MIT License
  * @author Andrew Svirin

src/Models/Crypt/KeyPair.php

@@ -3,7 +3,10 @@
 namespace EbicsApi\Ebics\Models\Crypt;
 
 /**
- * Key pair.
+ * RSA key pair bundle.
+ *
+ * Holds a public key, a private key, and the password used to encrypt
+ * the private key. Used for key generation, storage, and password rotation.
  *
  * @license http://www.opensource.org/licenses/mit-license.html  MIT License
  * @author Andrew Svirin