From 518560eefcf3bfd1207211584fa48e687fec62b5 Mon Sep 17 00:00:00 2001 From: "coderabbitai[bot]" <136622811+coderabbitai[bot]@users.noreply.github.com> Date: Mon, 22 Sep 2025 23:20:02 +0000 Subject: [PATCH] =?UTF-8?q?=F0=9F=93=9D=20Add=20docstrings=20to=20`fix-upd?= =?UTF-8?q?ate-in-pohoda`?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Docstrings generation was requested by @Vitexus. * https://github.com/VitexSoftware/PHP-Pohoda-Connector/pull/19#discussion_r2370599336 The following files were modified: * `src/mServer/Client.php` * `src/mServer/Response.php` --- src/mServer/Client.php | 35 ++++++++++++++++--- src/mServer/Response.php | 73 +++++++++++++++++++++++++++++++++++----- 2 files changed, 95 insertions(+), 13 deletions(-) diff --git a/src/mServer/Client.php b/src/mServer/Client.php index 4f456da..b3b30e9 100644 --- a/src/mServer/Client.php +++ b/src/mServer/Client.php @@ -322,7 +322,10 @@ public function setAuth(): bool } /** - * Set Instance http header. + * Set the STW-Instance HTTP header for subsequent requests. + * + * @param string $instance Identifier of the mServer instance to send in the `STW-Instance` header. + * @return self Fluent interface. */ public function setInstance(string $instance): self { @@ -331,6 +334,15 @@ public function setInstance(string $instance): self return $this; } + /** + * Set an external identifier in the payload under identity->extId->ids. + * + * Stores the provided external ID into the internal data structure so it + * will be included in the next Pohoda request. + * + * @param string $extId External identifier to assign. + * @return self Fluent interface. + */ public function setExtId(string $extId): self { $this->data['identity']['extId']['ids'] = $extId; @@ -666,6 +678,16 @@ public function addToPohoda($data = []): self return $this; } + /** + * Finalizes the current Pohoda XML payload and sends it to the server. + * + * Closes the current Pohoda document, loads the generated XML from the temporary + * cache into the next request body, and performs an HTTP POST to the server's + * "/xml" endpoint. In debug mode, adds a status message suggesting an xmllint + * validation command for the cached XML. + * + * @return bool True when the server response indicates success or warning; false otherwise. + */ public function commit(): bool { $this->pohoda->close(); @@ -679,10 +701,15 @@ public function commit(): bool } /** - * Update prepared record in Pohoda. + * Prepare and queue an update for the current agenda object in Pohoda. + * + * If $data is provided, it is taken as the current record (via takeData). If a request XML is present, + * the method marks it with an "update" action (using the provided $filter or filterToMe() when $filter is empty) + * and adds the item to the Pohoda engine for later commit. * - * @param array $data extra data - * @param null|mixed $filter + * @param array $data Data to prepare as the current record (optional). + * @param mixed $filter Filter to apply for the update; when empty, filterToMe() is used. + * @return $this */ public function updateInPohoda(array $data = [], $filter = null): self { diff --git a/src/mServer/Response.php b/src/mServer/Response.php index f0fb100..ac91303 100644 --- a/src/mServer/Response.php +++ b/src/mServer/Response.php @@ -78,19 +78,26 @@ public function __construct(Client $caller) $this->useCaller($caller); } + /** + * Associate a Caller with this Response and initialize state from its last HTTP response. + * + * If the caller has a lastCurlResponse, stores it in $rawXML, attempts to load it as XML, + * reads the root `rsp` attributes `state` and `note`, and processes each child `rsp` element + * by delegating to processResponsePackItem(). + * + * If there is no lastCurlResponse, sets the response state to "error" and the note to the + * caller's lastCurlError. + */ public function useCaller(Client $caller): void { $this->caller = $caller; if ($caller->lastCurlResponse) { $this->rawXML = $caller->lastCurlResponse; - $xml = simplexml_load_string($this->rawXML, 'SimpleXMLElement', \LIBXML_NONET | \LIBXML_NOCDATA); + $xml = simplexml_load_string($this->rawXML); if ($xml) { - $attrsRsp = $xml->attributes('rsp', true); - $attrs = $xml->attributes(); - $this->state = (string) (($attrsRsp['state'] ?? $attrs['state'] ?? '') ); - $this->note = (string) (($attrsRsp['note'] ?? $attrs['note'] ?? '') ); - $children = iterator_to_array($xml->children('rsp', true) ?: $xml->children()); - foreach ($children as $responsePackItem) { + $this->state = (string) $xml->attributes('rsp', true)->state; + $this->note = (string) $xml->attributes('rsp', true)->note; + foreach ($xml->children('rsp', true) as $responsePackItem) { $this->processResponsePackItem($responsePackItem); } } @@ -100,11 +107,28 @@ public function useCaller(Client $caller): void } } + /** + * No-op placeholder for processing a responsePack XML element; retained for compatibility. + * + * This method intentionally does nothing and is deprecated — response pack items are processed + * via processResponsePackItem() when XML is loaded. + * + * @param \SimpleXMLElement $responsePackData The XML element (ignored). + * @deprecated Use processResponsePackItem(\SimpleXMLElement $responsePackItem) or let useCaller() handle response pack processing. + */ public function processResponsePack(\SimpleXMLElement $responsePackData): void { // This method is no longer used } + /** + * Process a single XML node: update the overall state and handle its child response nodes. + * + * Reads the node's "state" attribute into the instance state and delegates each child element to + * processResponseData(), which may populate parsed data, producedDetails, and messages. + * + * @param \SimpleXMLElement $responsePackItem XML element representing one responsePackItem. + */ public function processResponsePackItem(\SimpleXMLElement $responsePackItem): void { $this->state = (string) $responsePackItem->attributes()->state; @@ -113,12 +137,36 @@ public function processResponsePackItem(\SimpleXMLElement $responsePackItem): vo } } + /** + * Extracts produced detail ID from an `rdc` namespaced XML node and stores it. + * + * Reads the `` child of the provided SimpleXMLElement, casts it to int, + * sets $this->producedDetails to ['id' => (int)], and synchronizes $this->parsed + * with the same value. + * + * @param \SimpleXMLElement $productDetails XML node containing an `rdc:id` child (uses the `rdc` namespace) + */ public function processProducedDetails(\SimpleXMLElement $productDetails): void { $this->producedDetails = ['id' => (int) $productDetails->children('rdc', true)->id]; $this->parsed = $this->producedDetails; } + /** + * Process import-detail nodes from a Pohoda response and record their messages. + * + * Iterates over children in the `rdc` namespace of the provided import details element, + * collects each detail's child elements into an associative array (element name => string value), + * groups those arrays into $this->messages keyed by each detail's `state` value, and updates + * the response state and parsed representation accordingly. + * + * Side effects: + * - Appends parsed detail arrays into $this->messages (keys like 'error' or 'warning'). + * - Sets $this->state to 'error' if any error messages exist, otherwise to 'warning' if any warnings exist. + * - Updates $this->parsed to reference the messages array. + * + * @param \SimpleXMLElement $importDetails XML element containing import detail entries (expects children in the `rdc` namespace) + */ public function processImportDetails(\SimpleXMLElement $importDetails): void { foreach ($importDetails->children('rdc', true) as $detail) { @@ -138,8 +186,15 @@ public function processImportDetails(\SimpleXMLElement $importDetails): void } /** - * @param \SimpleXMLElement $responseData - */ + * Process a single XML node. + * + * Updates the object's overall state from the node's `state` attribute and, when present, + * delegates processing of child elements `producedDetails` and `importDetails` to + * processProducedDetails() and processImportDetails() respectively. Those handlers + * update internal parsed data, messages, and producedDetails. + * + * @param \SimpleXMLElement $responseData The element to process. + */ public function processResponseData(\SimpleXMLElement $responseData): void { $this->state = (string) $responseData->attributes()->state;