Methods documentation.

Author: andrew-svirin

.gitignore

@@ -1,6 +1,9 @@
 # IntellijIdea files
 .idea
 
+# QWEN files
+.qwen
+
 # Composer
 composer.lock
 vendor

src/Contexts/FDLContext.php

@@ -6,7 +6,37 @@
 use EbicsApi\Ebics\Contracts\OrderContextInterface;
 
 /**
- * Class Parameters context container for FUL/FDL orders
+ * EBICS FDL (File Download) Context - Parameters for file download orders.
+ *
+ * EBICS Protocol Context:
+ * The FDLContext holds order-specific parameters for the FDL (File Download) order.
+ * It configures how files are requested from the bank and how the downloaded
+ * data should be parsed.
+ *
+ * FDL Order Parameters:
+ * - FileFormat: The format of the file to download (e.g., 'camt.053', 'pain.002')
+ * - CountryCode: Country-specific format variant (usually from bank configuration)
+ * - Parameters: Additional order-specific parameters (depends on bank/file type)
+ * - ParserFormat: How to parse the downloaded data (text, XML, XML files, ZIP files)
+ *
+ * Parser Format Options:
+ * - FILE_PARSER_FORMAT_TEXT: Raw text data (default)
+ * - FILE_PARSER_FORMAT_XML: Parse as single XML document
+ * - FILE_PARSER_FORMAT_XML_FILES: Extract multiple XML files from archive
+ * - FILE_PARSER_FORMAT_ZIP_FILES: Extract files from ZIP archive
+ *
+ * Typical Usage:
+ * $fdlContext = new FDLContext();
+ * $fdlContext->setFileFormat('camt.053');  // Bank statement
+ * $fdlContext->setCountryCode('DE');       // German format
+ *
+ * $order = new FDL($fdlContext, $startDate, $endDate);
+ * $result = $client->executeDownloadOrder($order);
+ *
+ * Common File Formats:
+ * - camt.052/053/054: Account reports (Cash Management)
+ * - pain.002: Payment status report
+ * - mt940/942: Account statement (older format)
  *
  * @license http://www.opensource.org/licenses/mit-license.html  MIT License
  * @author Andrew Svirin

src/Contexts/FULContext.php

@@ -5,7 +5,38 @@
 use EbicsApi\Ebics\Contracts\OrderContextInterface;
 
 /**
- * Class context for FUL order.
+ * EBICS FUL (File Upload) Context - Parameters for file upload orders.
+ *
+ * EBICS Protocol Context:
+ * The FULContext holds order-specific parameters for the FUL (File Upload) order.
+ * It configures how files are formatted and submitted to the bank.
+ *
+ * FUL Order Parameters:
+ * - FileFormat: The format of the file being uploaded (e.g., 'pain.001', 'pain.008')
+ * - CountryCode: Country-specific format variant (usually from bank configuration)
+ * - Parameters: Additional order-specific parameters (depends on bank/file type)
+ *
+ * Typical Usage:
+ * $fulContext = new FULContext();
+ * $fulContext->setFileFormat('pain.001');  // SEPA Credit Transfer
+ * $fulContext->setCountryCode('DE');       // German format
+ *
+ * $orderData = new XmlData($sepaXml);
+ * $order = new FUL($fulContext, $orderData);
+ * $result = $client->executeUploadOrder($order);
+ *
+ * Common File Formats:
+ * - pain.001: SEPA Credit Transfer (customer credit transfer)
+ * - pain.008: SEPA Direct Debit (core and B2B)
+ * - pain.001.001.03: Specific pain.001 version
+ * - pain.008.001.02: Specific pain.008 version
+ *
+ * Upload Process:
+ * 1. File is validated against XML schema (if XML format)
+ * 2. File is split into segments (if large)
+ * 3. Segments are encrypted with transaction key
+ * 4. Segments are uploaded sequentially to the bank
+ * 5. Bank acknowledges receipt
  *
  * @license http://www.opensource.org/licenses/mit-license.html  MIT License
  * @author Andrew Svirin

src/Contexts/RequestContext.php

@@ -11,7 +11,43 @@
 use EbicsApi\Ebics\Models\User;
 
 /**
- * Class RequestContext context container for @see \EbicsApi\Ebics\Factories\RequestFactory
+ * EBICS Request Context - Container for EBICS request parameters and transaction state.
+ *
+ * EBICS Protocol Context:
+ * The RequestContext holds all parameters required to build an EBICS XML request and
+ * manage the transaction state throughout the request-response lifecycle. It serves
+ * as a data container that flows through the order creation and execution process.
+ *
+ * Key Components:
+ *
+ * Identity & Security:
+ * - bank: EBICS server identification (Host ID, URL, country)
+ * - user: Subscriber identification (Partner ID, User ID)
+ * - keyring: Cryptographic material (signatures, certificates, keys)
+ * - withES: Whether electronic signature is required for the order
+ *
+ * Transaction State:
+ * - transactionId: Unique identifier for multi-phase transactions
+ * - transactionKey: AES key for encrypting order data (from bank)
+ * - segmentNumber/isLastSegment: For segmented downloads/uploads
+ * - numSegments: Total number of segments to transfer
+ *
+ * Date Ranges:
+ * - startDateTime/endDateTime: For download orders with date filtering
+ * - dateTime: Current timestamp for request signing
+ *
+ * Order Data:
+ * - orderType: EBICS order code (INI, HIA, FDL, FUL, etc.)
+ * - orderData: XML payload for upload orders
+ * - dataDigest: Hash of order data for integrity verification
+ *
+ * Product Information:
+ * - product: Client product name sent in requests
+ * - language: Language preference for bank responses
+ *
+ * Advanced:
+ * - ackClosure: Custom closure to control receipt acknowledgment
+ * - orderContext: Order-specific parameters (FDL, FUL, BTD, BTU contexts)
  *
  * @license http://www.opensource.org/licenses/mit-license.html  MIT License
  * @author Andrew Svirin

src/Contracts/EbicsClientInterface.php

@@ -29,85 +29,220 @@ interface EbicsClientInterface
     public const FILE_PARSER_FORMAT_ZIP_FILES = 'zip_files';
 
     /**
-     * Create user signatures A, E and X on first launch.
+     * Create user signatures A (Authorization), E (Encryption), and X (Authentication) on first launch.
+     *
+     * EBICS Protocol Context:
+     * This method initializes the cryptographic key pairs required for EBICS communication.
+     * It generates three types of signatures:
+     * - Signature A (A005/A006): Used for authorization/order signing
+     * - Signature E (E002): Used for encryption of order data
+     * - Signature X (X002): Used for authentication of requests
+     *
+     * The method should be called once during initial setup before any EBICS transactions.
+     * It creates the key pairs and stores them in the keyring for subsequent use.
+     *
      * @param array<string, mixed>|null $options Setup to specify custom certificate, private, public keys and version
-     * for Electronic Signature, Authorization and Identification, Encryption details.
+     *   for Electronic Signature (E), Authorization and Identification (A), Encryption details.
+     *   Supported options:
+     *   - 'x509_generator': Custom X509GeneratorInterface implementation
+     *   - 'signature_a_version': Version for signature A (A005 or A006)
+     *   - 'signature_e_version': Version for signature E (E002)
+     *   - 'signature_x_version': Version for signature X (X002)
+     *   - 'certificate': Custom X.509 certificate
+     *   - 'private_key': Custom private key
+     *   - 'public_key': Custom public key
      */
     public function createUserSignatures(?array $options = null): void;
 
     /**
-     * Generate certificate for issuer.
-     * @return array
+     * Generate X.509 certificate for issuer (certificate authority).
+     *
+     * EBICS Protocol Context:
+     * Creates a self-signed X.509 certificate that can be used as the issuer certificate
+     * for signing user certificates in the EBICS protocol. This is part of the certificate
+     * infrastructure required for secure EBICS communication with certified banks.
+     *
+     * The certificate is used in the INI/HIA/H3K initialization processes.
+     *
+     * @return array Certificate data array containing:
+     *   - 'certificate': The X.509 certificate in PEM format
+     *   - 'private_key': The corresponding private key
+     *   - 'public_key': The corresponding public key
      */
     public function generateIssuerCertificate(): array;
 
     /**
-     * Execute Initialization Order.
-     * @param InitializationOrderInterface $order
-     * @return InitializationOrderResult
+     * Execute an EBICS initialization order.
+     *
+     * EBICS Protocol Context:
+     * Initialization orders are used during the initial setup phase with the bank to exchange
+     * cryptographic keys and certificates. These orders establish the trust relationship
+     * between the client and the bank.
+     *
+     * The typical initialization sequence is: INI → HIA → HPB (or H3K → HPB for version 3.0).
+     *
+     * @param InitializationOrderInterface $order The initialization order to execute
+     *
+     * @return InitializationOrderResult Result containing order execution status and any returned data
      */
     public function executeInitializationOrder(InitializationOrderInterface $order): InitializationOrderResult;
 
     /**
-     * Execute Standard Order.
-     * @param StandardOrderInterface $order
-     * @return StandardOrderResult
+     * Execute an EBICS standard order.
+     *
+     * EBICS Protocol Context:
+     * Standard orders are used for general information retrieval and administrative tasks.
+     * These orders do not involve file transfer and typically return metadata or status information.
+     *
+     * Supported standard order types:
+     * - HEV: Get supported EBICS protocol versions from the bank
+     * - HPD: Download server parameters (bank capabilities and configuration)
+     * - HKD: Download customer information (account details, partner data)
+     * - HTD: Download subscriber information (user permissions and settings)
+     * - HAA: Download available order types that the customer is authorized to use
+     * - PTK: Download transaction status report in plain text format
+     * - HAC: Download transaction status report in XML format
+     *
+     * Standard orders follow the request-response pattern without file segmentation.
+     *
+     * @param StandardOrderInterface $order The standard order to execute
+     *
+     * @return StandardOrderResult Result containing order execution status and returned data
      */
     public function executeStandardOrder(StandardOrderInterface $order): StandardOrderResult;
 
     /**
-     * Execute Download Order.
-     * @param DownloadOrderInterface $order
-     * @return DownloadOrderResult
+     * Execute an EBICS download order.
+     *
+     * EBICS Protocol Context:
+     * Download orders are used to retrieve files and data from the bank. The download process
+     * follows a multi-phase transaction model:
+     *
+     * 1. Initialization Phase: Client requests download with order type and date range
+     * 2. Distribution Phase: Bank prepares the requested data
+     * 3. Retrieval Phase: Client retrieves the data in segments (if large)
+     * 4. Receipt Phase: Client confirms successful receipt (optional for some order types)
+     *
+     * The order data may be compressed (ZIP), encrypted, and split into multiple segments
+     * for large files. The client handles automatic decompression and reassembly.
+     *
+     * @param DownloadOrderInterface $order The download order to execute
+     *
+     * @return DownloadOrderResult Result containing downloaded order data, transaction details, and file contents
      */
     public function executeDownloadOrder(DownloadOrderInterface $order): DownloadOrderResult;
 
     /**
-     * Execute Upload Order.
-     * @param UploadOrderInterface $order
-     * @return UploadOrderResult
+     * Execute an EBICS upload order.
+     *
+     * EBICS Protocol Context:
+     * Upload orders are used to send files and data to the bank. The upload process
+     * follows a multi-phase transaction model:
+     *
+     * 1. Initialization Phase: Client sends upload request with order metadata
+     * 2. Transfer Phase: Client uploads the order data (may be segmented for large files)
+     * 3. Receipt Phase: Bank confirms receipt with transaction status
+     *
+     * The order data is automatically compressed and may be encrypted before transmission.
+     * Large files are automatically segmented according to EBICS protocol limits.
+     *
+     * @param UploadOrderInterface $order The upload order to execute
+     *
+     * @return UploadOrderResult Result containing upload transaction status and bank receipt
      */
     public function executeUploadOrder(UploadOrderInterface $order): UploadOrderResult;
 
     /**
-     * Get Keyring.
+     * Get the keyring containing cryptographic keys and certificates.
+     *
+     * EBICS Protocol Context:
+     * The keyring stores all cryptographic materials required for EBICS communication:
+     * - User signatures (A, E, X) - key pairs for authorization, encryption, and authentication
+     * - Bank signatures - bank's public keys received via HPB order
+     * - X.509 certificates - for certified EBICS communication
+     * - Transaction keys - AES keys for encrypting order data
+     *
+     * The keyring should be persisted between sessions using a KeyringManager.
      *
-     * @return Keyring
+     * @return Keyring The keyring object containing all signatures and certificates
      */
     public function getKeyring(): Keyring;
 
     /**
-     * Get Bank.
+     * Get the bank configuration and connection details.
      *
-     * @return Bank
+     * EBICS Protocol Context:
+     * The Bank object contains:
+     * - Host ID: Unique identifier for the EBICS server
+     * - URL: Endpoint URL for EBICS communication
+     * - Country code: Bank's country code for protocol-specific behavior
+     *
+     * @return Bank The bank configuration object
      */
     public function getBank(): Bank;
 
     /**
-     * Get User.
+     * Get the user (subscriber) configuration.
+     *
+     * EBICS Protocol Context:
+     * The User object represents an EBICS subscriber (participant) and contains:
+     * - Partner ID: Identifies the contracting partner with the bank
+     * - User ID: Identifies the specific user/subscriber within the partner
+     *
+     * Together with the Bank, this forms the unique identification for EBICS sessions.
      *
-     * @return User
+     * @return User The user configuration object
      */
     public function getUser(): User;
 
     /**
-     * Get response handler for manual process response.
+     * Get the response handler for manual response processing.
+     *
+     * EBICS Protocol Context:
+     * The ResponseHandler provides access to the raw XML response from the bank,
+     * allowing custom processing of:
+     * - Response codes and messages
+     * - Transaction IDs
+     * - Order data extraction
+     * - Error handling and diagnostics
+     *
+     * This is primarily useful for advanced use cases requiring direct access
+     * to the EBICS response structure.
      *
-     * @return ResponseHandler
+     * @return ResponseHandler The response handler object
      */
     public function getResponseHandler(): ResponseHandler;
 
     /**
-     * Check keyring is valid.
+     * Validate that the keyring contains valid and complete cryptographic material.
      *
-     * @return bool
+     * EBICS Protocol Context:
+     * Checks whether the keyring has all required signatures and certificates
+     * for EBICS communication. This includes verification of:
+     * - User signature A (authorization) - required for signed orders
+     * - User signature E (encryption) - required for encrypted orders
+     * - User signature X (authentication) - required for all orders
+     * - Bank signatures - required for verifying bank responses
+     *
+     * Should be called after initial setup or when loading a persisted keyring
+     * to ensure the client is ready for EBICS communication.
+     *
+     * @return bool True if keyring is valid, false if initialization is needed
      */
     public function checkKeyring(): bool;
 
     /**
-     * Change password for keyring.
+     * Update the encryption password for the keyring storage.
+     *
+     * EBICS Protocol Context:
+     * The keyring password is used to encrypt the private keys when persisting
+     * them to storage (file, database, etc.). This method allows changing
+     * the password without regenerating the cryptographic key pairs.
+     *
+     * Important: This does NOT change the EBICS signatures known to the bank.
+     * It only changes the local storage encryption password.
      *
-     * @param string $newPassword
+     * @param string $newPassword The new encryption password for keyring storage
      *
      * @return void
      */