Client

Narrowed from {AbstractClient::__construct()}'s ?AbstractSocketConfig, mirroring the covariant {newSocketConfig()} factory below.

The narrowing is the point: new Client(new \CNIC\IBS\SocketConfig()) has to be an analysis error at the call site, not an {\CNIC\Exception\UnsupportedFeatureException} thrown later from {\CNIC\CNR\getSocketConfig()}. PHP exempts constructors from LSP under class inheritance, so a subclass may narrow a parameter here where it could not on any other method; PHPStan and Psalm both accept the declaration and enforce it against callers.

The CNR SocketConfig, narrowed from the shared {AbstractSocketConfig} type of {AbstractClient::$socketConfig}.

The one narrowing point for CNR's platform-specific config state (session, persistent, role separator). A typed property cannot be re-declared with a narrower type in PHP, so the covariant {\CNIC\CNR\newSocketConfig()} factory cannot inform the property's type — this accessor carries that knowledge instead, in exactly one place, rather than each caller asserting.

It is the covariant override of {\CNIC\AbstractClient::getSocketConfig()}, and deliberately the only one: two methods narrowing the same property would be two places to keep in step. Consumers holding CNR\Client therefore reach getSession()/setPersistent() with no narrowing of their own.

The guard is unreachable for correctly-typed callers. There are two writers of the property — the covariant newSocketConfig() above and the constructor parameter (RSRMID-2966) — and both are narrowed to SocketConfig, so neither can seat a foreign config without an analysis error at the call site first. It throws rather than assert()ing because assert() is compiled out when zend.assertions is disabled, which would turn a subclass that returned the wrong config into an undefined-method fatal instead of a named SDK exception.

Perform API request using the given command

Shared request lifecycle (template method). Never reimplement it in a brand; vary it through exactly two hooks — {buildCommand()} (command flattening) and {newResponse()} (covariant Response factory) — plus the {newSocketConfig()} subtype, which is where a brand-mandatory cURL option would go. No brand declares one.

Brand-specific command rewriting belongs behind buildCommand(), not here: CNR's IDN conversion lives in {\CNIC\CNR\IDNCommandRewriter}, and a shared step gated by a flag only one brand sets is the shape that replaced.

Flatten the given command into wire form (CNR uppercase key/value pairs) and convert its IDN parameters to punycode.

The IDN rewrite is CNR's alone — IBS/Moniker convert server-side — so it runs here, in the brand hook, and not on {\CNIC\AbstractClient} behind a flag; see {\CNIC\CNR\IDNCommandRewriter}. It must run after the flattening: the rules match wire keys (NAMESERVER0, OBJECTID), not the caller's nested, arbitrarily-cased input.

Instantiate a CNR Response for the given raw payload.

Instantiate CNR SocketConfig

Instantiate the HTTP transport for this client. Mirrors {newSocketConfig()} — the default is the production cURL transport; override or {setTransport()} to inject a test double so the request() lifecycle can run offline.

Inject a custom HTTP transport (e.g. a record/replay cassette transport for offline tests) in place of the default {HttpTransport}.

The transport this client posts through — the read half of {setTransport()}, mirroring {getSocketConfig()}.

Injecting a canned {\CNIC\TransportInterface} is how an embedding application drives the request() lifecycle offline; this accessor is how it reads the double back afterwards to assert what the client handed over, without reaching past the client for a protected property.

Instantiate the CNR logger writing to the given sink

Route debug output somewhere other than standard output, keeping this brand's format.

This is the seam integrators want: the brand formatter is the part with the logic, the destination is the part that varies per host application. Passing a fresh {\CNIC\EchoSink} restores the shipped default, discarding any logger set via {\CNIC\setCustomLogger()}.

Set custom logger to use instead of the default one — use this to replace the format as well as the destination. Create your own class extending \CNIC\AbstractLogger (format only) or implementing \CNIC\LoggerInterface (format and destination).

The logger this client writes debug records through — the read half of {setCustomLogger()}/{@see setLogSink()}, mirroring {getSocketConfig()}.

Which of the two setters last ran decides what comes back: a brand logger built around the injected sink, or the custom logger supplied verbatim. That composition rule is order-dependent, so an embedding application that installs its own logger needs a way to confirm the one it supplied is the one in place.

Enable debug output to STDOUT

Disable debug output

Serialize given command for POST request including connection configuration data

Get the API connection url that is currently set

Set the request timeout in seconds (default 300).

The only way to change the timeout: CURLOPT_TIMEOUT in the option bag is rejected ({\CNIC\setExtraCurlOptions()}) rather than quietly overriding what {\CNIC\getSocketTimeout()} reports.

Get the request timeout in seconds currently configured.

Set a custom user agent (for platforms that use this SDK)

Get the user agent string — the one set via {setUserAgent()}, or the SDK default when none was.

A pure read — keep it that way. Memoising the default into {$userAgent} would make a getter write during a request, and there is nothing worth memoising: the value is a handful of constants and one php_uname() call.

Merge additional cURL options into the bag, overriding existing values on key collision. Forwards to {AbstractSocketConfig::setExtraCurlOptions()}, whose docblock carries the detail: what reaches the wire, and the two sets of keys that are refused — the SDK-managed settings ({AbstractSocketConfig::MANAGED_OPTIONS}, rejected here and now) and the transport's own ({HttpTransport::PROTECTED_OPTIONS}, rejected on the next request).

Restore the cURL option bag to the brand defaults, discarding anything previously handed to {setExtraCurlOptions()}. Options only — the proxy and referer are separate state and survive; see {AbstractSocketConfig::resetCurlOptions()}.

Set proxy to use for API communication

Get proxy configuration for API communication

Set Referer to use for API communication

Get Referer configuration for API communication

Get the current module version

Set another connection url to be used for API communication

Set Credentials to be used for API communication.

On CNR this discards any active API session: CNR\SocketConfig::setLogin()/ setPassword() clear the session id, because a session and a password are alternative credentials on the wire and the newer one is authoritative. The invariant is deliberate and pinned by a test — CNR\Client::reuseSession() depends on it, restoring the login first and the session second. Set the session after the credentials, never before.

Activate High Performance Setup — route requests through the co-located proxy on loopback.

Brand-agnostic and therefore shared — the caller supplies the local proxy, so IBS/Moniker may opt in too. It records a flag on the config rather than rewriting the URL, so the selected system survives it; see {\CNIC\AbstractSocketConfig::useHighPerformanceConnectionSetup()}.

Convert domain names to idn + punycode.

Brand-agnostic and therefore shared: a thin pass-through to the vendor converter for callers who want to normalise a name explicitly. The automatic rewrite of an outbound command is a different thing and is deliberately not here — which parameters carry a domain name is CNR knowledge, and it lives in {\CNIC\CNR\IDNCommandRewriter}.

Delegate cURL execution to the transport layer.

The configured options are handed over as they are, and beat the transport's own defaults in {\CNIC\HttpTransport::post()} (PHP's + keeps the left operand on a duplicate key).

Do not re-add a per-request options argument here: it would be a route into the option set that skips {\CNIC\AbstractSocketConfig::MANAGED_OPTIONS}, and so a way for a subclass to put a second answer behind getProxy(). A per-request option belongs on the config before the request, or on a transport the caller drives themselves.

Close all cURL connections

Get LIVE system URL.

There is deliberately no matching getOTEUrl() here: a configuration value no longer needs a hand-written forwarder, so read the OT&E endpoint from {\CNIC\getSocketConfig()}.

Get the API system in use, or null when the configured URL is neither of the brand's two known endpoints.

Derived from the URL rather than stored beside it, which is what makes it impossible for the two to disagree — and why the return type is nullable: after a setURL() to some other host there is no honest OT&E-or-LIVE answer to give. See {\CNIC\AbstractSocketConfig::getSystem()}.

Check whether the OT&E system is in use

Set OT&E System for API communication

Set LIVE System for API communication (this is the default setting)

Set context data for the client

Get the API Session ID that is currently set, or null when there is none.

CNR-only: IBS/Moniker have no session concept, so the method is absent there rather than present and answering null.

Set an API session id to be used for API communication.

Setting a session clears the stored password: the two are alternative credentials on the wire, and CNR's SocketConfig treats the newer one as authoritative. That holds on the reset path too — setSession("") leaves neither, so re-set the credentials to go back to password authentication (see {\CNIC\CNR\SocketConfig::setSession()}).

Perform API login to start session-based communication.

The connection is made persistent for the duration of the login request only, then put back: the session id, not the socket, is what the following requests reuse.

"For the duration" includes a duration that ends in a throw, which is why the reset sits in a finally rather than on the line after the call (RSRMID-2980). request() is not throw-free — a transport-owned cURL option or a restated transport-owned header raises {\CNIC\Exception\UnsupportedFeatureException} out of {\CNIC\HttpTransport::post()}, and setExtraCurlOptions() deliberately does not pre-empt that check. An unconditional reset on the following line was therefore skippable, and a skipped reset leaves persistent stuck true, so every later request on this client silently asks the API for a session.

Only the reset is unconditional. The session write stays inside the success branch: a login that threw established nothing.

Perform API logout to close the API session in use.

The transport is closed whether or not the command succeeded — a failed StopSession still leaves a connection this client will not reuse.

"Whether or not it succeeded" includes "whether or not it returned at all", which is why the close sits in a finally (RSRMID-2980). A throw out of request() — see {\CNIC\CNR\login()} for the reachable path — used to skip the close on the following line and leak the transport's connection handle for the rest of this client's lifetime. Clearing the session stays on the success branch: an unconfirmed StopSession is no reason to forget a session id that may still be live server-side.

Apply session data to a PHP session object

Rebuild connection settings from a PHP session object.

The two calls are ordered, not interchangeable: setCredentials() clears the session id (a session and a password are alternative credentials, and CNR's SocketConfig treats the newer one as authoritative), so restoring the session second is what makes this work.

Set Role Credentials to be used for API communication.

CNR-only capability (see {\CNIC\RoleCredentialsInterface}): a role login is the account id, the ":" role separator and the role user id, authenticated with that role user's own password.

Request the next page of list entries for the current list query

The continuation is assembled from two sources, deliberately: the command that produced $currentPage ({\CNIC\CNR\continuationCommand()}) and $currentPage's own pagination state. Response data — LIMIT, LAST — is not masked and is read straight off the response; command parameters are not.

Request all pages/entries for the given query command