Skip to content

📝 Add docstrings to fix-update-in-pohoda #20

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
coderabbitai wants to merge 1 commit into
base: fix-update-in-pohoda
Choose a base branch
from
Open

📝 Add docstrings to fix-update-in-pohoda #20

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
35 changes: 31 additions & 4 deletions src/mServer/Client.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
{
Expand All @@ -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;
Expand Down Expand Up @@ -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();
Expand All @@ -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<string, string> $data extra data
* @param null|mixed $filter
* @param array<string,mixed> $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
{
Expand Down
73 changes: 64 additions & 9 deletions src/mServer/Response.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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);
}
}
Expand All @@ -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 <responsePack> 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 <responsePackItem> 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;
Expand All @@ -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 `<rdc:id>` 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) {
Expand All @@ -138,8 +186,15 @@ public function processImportDetails(\SimpleXMLElement $importDetails): void
}

/**
* @param \SimpleXMLElement $responseData
*/
* Process a single <responseData> 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 <responseData> element to process.
*/
public function processResponseData(\SimpleXMLElement $responseData): void
{
$this->state = (string) $responseData->attributes()->state;
Expand Down