Methods documentation.

Author: andrew-svirin

CHANGELOG.md

@@ -1,7 +1,6 @@
 ## 3.1
 
-* Documentation detailization.
-* Safety improvements.
+* Safety & Stability & Documentation improvements.
 
 ## 3.0
 

src/Contracts/AuthSignatureHandlerInterface.php

@@ -0,0 +1,58 @@
+<?php
+
+namespace EbicsApi\Ebics\Contracts;
+
+use DOMDocument;
+use DOMNode;
+use EbicsApi\Ebics\Exceptions\EbicsException;
+
+/**
+ * Authentication Signature Handler interface.
+ *
+ * Handles the creation and insertion of the `AuthSignature` XML element
+ * into EBICS request documents. This signature authenticates the
+ * request using the user's X (transaction signing) signature.
+ *
+ * EBICS Protocol Context:
+ * The AuthSignature is an XML Digital Signature (XML-DSig) that proves
+ * the authenticity of an EBICS request. It is inserted after the `<header>`
+ * element and signs all XML elements marked with `authenticate="true"`.
+ *
+ * The signature process:
+ * 1. Canonicalize the signed info section (XML-C14N)
+ * 2. Compute SHA-256 digest of the canonicalized data
+ * 3. Encrypt the digest with the user's X private key (RSA)
+ * 4. Embed the signature value in the `<ds:SignatureValue>` element
+ *
+ * Different EBICS versions use different signature algorithms:
+ * - EBICS 2.4/2.5: RSA-PKCS#1 v1.5 with SHA-256
+ * - EBICS 3.0: May use RSA-PSS with SHA-256
+ *
+ * @license http://www.opensource.org/licenses/mit-license.html  MIT License
+ * @author Andrew Svirin
+ */
+interface AuthSignatureHandlerInterface
+{
+    /**
+     * Add the AuthSignature element and its children to the request DOM.
+     *
+     * Signs all elements with attribute `authenticate="true"` and inserts
+     * the completed AuthSignature block after the Header section.
+     *
+     * The method performs the following steps:
+     * 1. Creates the `<AuthSignature>` element
+     * 2. Builds `<ds:SignedInfo>` with canonicalization and signature methods
+     * 3. Computes the digest value for all authenticated elements
+     * 4. Encrypts the signed info hash with the user's X private key
+     * 5. Embeds the signature value
+     *
+     * @param DOMDocument $dom The request DOM document to sign
+     * @param DOMNode|null $xmlRequestHeader Optional header element to insert after.
+     *                                       If null, the handler locates the Header automatically.
+     *
+     * @return void
+     *
+     * @throws EbicsException If signature creation fails
+     */
+    public function handle(DOMDocument $dom, ?DOMNode $xmlRequestHeader = null): void;
+}

src/Contracts/BankLetter/FormatterInterface.php

@@ -5,27 +5,52 @@
 use EbicsApi\Ebics\Models\BankLetter;
 
 /**
- * EBICS formatter for bank letter.
+ * Bank Letter Formatter interface.
+ *
+ * Defines the contract for formatting {@see BankLetter} objects into
+ * human-readable output (e.g., plain text, HTML, PDF-ready markup).
+ *
+ * EBICS Protocol Context:
+ * A bank letter (also called an "EBICS initialization letter") is a
+ * document that contains the cryptographic parameters of an EBICS
+ * setup, including:
+ * - Hash values of user signatures (A, E, X) for verification
+ * - Bank identification details (host ID, URL, country)
+ * - User identification (partner ID, user ID)
+ * - Public key fingerprints
+ *
+ * The bank letter is typically printed and sent by postal mail or
+ * secure fax to the bank as part of the INI/HIA initialization
+ * process, allowing the bank to verify the hash values before
+ * activating the EBICS connection.
  *
  * @license http://www.opensource.org/licenses/mit-license.html  MIT License
  * @author Andrew Svirin
  */
 interface FormatterInterface
 {
-
     /**
-     * Format bank letter to printable.
+     * Format a bank letter into a printable string representation.
+     *
+     * Transforms the BankLetter model into a human-readable format
+     * suitable for printing or display. The output format depends on
+     * the specific formatter implementation (text, HTML, etc.).
      *
-     * @param BankLetter $bankLetter
+     * @param BankLetter $bankLetter The bank letter model to format
      *
-     * @return string
+     * @return string The formatted bank letter ready for printing or display
      */
     public function format(BankLetter $bankLetter): string;
 
     /**
-     * Set translations.
+     * Set custom translations for the formatted output.
+     *
+     * Allows overriding the default labels/headers in the bank letter
+     * with locale-specific translations. Translation keys are implementation-
+     * dependent.
      *
-     * @param array<string, string> $translations
+     * @param array<string, string> $translations Associative array mapping
+ *                                            translation keys to translated strings
      *
      * @return void
      */

src/Contracts/BankLetter/HashGeneratorInterface.php

@@ -5,21 +5,40 @@
 use EbicsApi\Ebics\Contracts\SignatureInterface;
 
 /**
- * EBICS Generate hash for bank letter.
- * Strategy pattern.
+ * Bank Letter Hash Generator interface.
+ *
+ * Generates cryptographic hash values for signature keys to be
+ * included in the {@see \EbicsApi\Ebics\Models\BankLetter} for
+ * bank verification.
+ *
+ * EBICS Protocol Context:
+ * During the EBICS initialization process (INI/HIA/H3K), the client
+ * generates public/private key pairs and sends the public keys to
+ * the bank. The bank letter contains hash values (fingerprints) of
+ * these public keys, which the bank uses to verify that the keys
+ * received electronically match the keys documented in the printed
+ * letter.
+ *
+ * This interface uses the Strategy pattern, allowing different hash
+ * algorithms (SHA-256, SHA-512, etc.) to be plugged in depending
+ * on the signature version and bank requirements.
  *
  * @license http://www.opensource.org/licenses/mit-license.html  MIT License
  * @author Andrew Svirin
  */
 interface HashGeneratorInterface
 {
-
     /**
-     * Generate hash.
+     * Generate a hash (fingerprint) for the given signature's public key.
+     *
+     * Computes a cryptographic hash of the public key associated with
+     * the provided signature. This hash is included in the bank letter
+     * for manual verification by the bank.
      *
-     * @param SignatureInterface $signature
+     * @param SignatureInterface $signature The signature whose public key
+ *                                      hash should be generated
      *
-     * @return string
+     * @return string The hexadecimal hash string (fingerprint)
      */
     public function generate(SignatureInterface $signature): string;
 }

src/Contracts/BufferInterface.php

@@ -3,93 +3,120 @@
 namespace EbicsApi\Ebics\Contracts;
 
 /**
- * Buffer class interface.
+ * Buffer interface.
+ *
+ * Provides a stream-based buffer for reading and writing data during
+ * EBICS operations. This interface abstracts PHP stream operations
+ * and is primarily used for handling large order data that may exceed
+ * memory limits when processed as a single string.
+ *
+ * The buffer supports standard stream operations (open, close, read, write,
+ * seek) as well as stream filter application for on-the-fly data
+ * transformation (e.g., compression, encoding).
+ *
+ * EBICS Protocol Context:
+ * Large order data (e.g., batch payment files) are often streamed rather
+ * than loaded into memory. The buffer enables efficient handling of:
+ * - Upload order data segmented into chunks
+ * - Download order data reassembled from segments
+ * - ZIP compression/decompression on the fly via stream filters
  *
  * @license http://www.opensource.org/licenses/mit-license.html  MIT License
  * @author Andrew Svirin
  */
 interface BufferInterface
 {
+    /**
+     * Default read length in bytes for buffer read operations.
+     */
     const DEFAULT_READ_LENGTH = 1024;
 
     /**
-     * Open buffer.
+     * Open the buffer with the specified mode.
+     *
+     * Initializes the underlying stream resource for reading and/or writing.
+     * Common modes: 'r' (read), 'w' (write), 'r+' (read/write).
      *
-     * @param string $mode
+     * @param string $mode Stream open mode (same as PHP fopen modes)
      *
      * @return void
      */
     public function open(string $mode): void;
 
     /**
-     * Close buffer.
+     * Close the buffer and release the underlying stream resource.
      *
      * @return void
      */
     public function close(): void;
 
     /**
-     * Reset pointer.
+     * Reset the stream pointer to the beginning of the buffer.
      *
      * @return void
      */
     public function rewind(): void;
 
     /**
-     * Write to buffer.
+     * Write a string to the buffer at the current position.
      *
-     * @param string $string
+     * @param string $string The data to write
      *
      * @return void
      */
     public function write(string $string): void;
 
     /**
-     * Read from buffer.
+     * Read data from the buffer at the current position.
      *
-     * @param int|null $length
+     * If no length is specified, reads up to DEFAULT_READ_LENGTH bytes.
      *
-     * @return string
+     * @param int|null $length Number of bytes to read (defaults to DEFAULT_READ_LENGTH)
+     *
+     * @return string The data read from the buffer
      */
     public function read(?int $length = null): string;
 
     /**
-     * Read from buffer full content.
+     * Read the entire buffer content from the current position to EOF.
      *
-     * @return string
+     * @return string The full remaining content of the buffer
      */
     public function readContent(): string;
 
     /**
-     * Is end of file.
+     * Check if the stream pointer has reached the end of the buffer.
      *
-     * @return bool
+     * @return bool True if the pointer is at EOF, false otherwise
      */
     public function eof(): bool;
 
     /**
-     * Move to pointer.
+     * Move the stream pointer to the specified byte offset.
      *
-     * @param int $offset
+     * @param int $offset The byte offset to seek to
      *
-     * @return int
+     * @return int Returns 0 on success, or -1 on failure
      */
     public function fseek(int $offset): int;
 
     /**
-     * Apply filter.
+     * Apply a stream filter to the buffer for data transformation.
+     *
+     * Filters can be used for on-the-fly compression (zlib), encoding
+     * (convert.*), or custom data processing during read/write operations.
      *
-     * @param string $filterName
-     * @param int $mode
+     * @param string $filterName The PHP stream filter name (e.g., 'zlib.deflate')
+     * @param int $mode Filter mode: STREAM_FILTER_READ, STREAM_FILTER_WRITE, or STREAM_FILTER_ALL
      *
      * @return void
      */
     public function filterAppend(string $filterName, int $mode): void;
 
     /**
-     * Length of content.
+     * Get the total length of the buffer content in bytes.
      *
-     * @return int
+     * @return int The byte length of the buffer content
      */
     public function length(): int;
 }

src/Contracts/Crypt/HashInterface.php

@@ -3,27 +3,42 @@
 namespace EbicsApi\Ebics\Contracts\Crypt;
 
 /**
- * Crypt RSA representation.
+ * Cryptographic Hash interface.
+ *
+ * Provides a unified abstraction over various hash algorithms used in
+ * EBICS protocol operations, including SHA-256, SHA-512, and others.
+ *
+ * EBICS Protocol Context:
+ * Hash functions are fundamental to EBICS security:
+ * - Computing digests of order data for RSA signature generation (A005, A006)
+ * - Creating transaction signatures (X002) over request headers
+ * - Verifying data integrity during transmission
+ *
+ * EBICS 2.5 and 3.0 primarily use SHA-256 (256-bit) for most operations,
+ * while A006 (RSA-PSS) may use SHA-512 for enhanced security.
  *
  * @license http://www.opensource.org/licenses/mit-license.html  MIT License
  * @author Andrew Svirin
  */
 interface HashInterface
 {
-
     /**
-     * Compute the HMAC.
+     * Compute the cryptographic hash of the given text.
      *
-     * @param string $text
+     * @param string $text The input data to hash
      *
-     * @return string
+     * @return string The raw binary hash output
      */
     public function hash($text);
 
     /**
-     * Returns the hash length (in bytes)
+     * Get the output length of the hash algorithm in bytes.
+     *
+     * Returns the size of the hash output (e.g., 32 bytes for SHA-256,
+     * 64 bytes for SHA-512). This is useful for allocating buffers
+     * and validating hash lengths.
      *
-     * @return int
+     * @return int The hash output length in bytes
      */
     public function getLength();
 }