AbstractClient

Constructor

The connection configuration this client uses — the accessor that means a new setting needs no forwarder, and the seam that lets configuration be built and asserted without constructing a client.

Brands narrow the return type covariantly where they have their own config capabilities — {\CNIC\CNR\Client::getSocketConfig()} returns the CNR config, which is the one place the invariant property type is narrowed.

Perform API request using the given command.

The shared request lifecycle lives in {\CNIC\performRequest()}; each brand's public request() is a thin wrapper that pins its default $path and declares a concrete Response return type. Every brand accepts an optional $path appended to the configured base URL to select the endpoint: for IBS/Moniker the path selects the operation (e.g. Domain/Create); for CNR it defaults to the single fixed script path (api/call.cgi) and rarely varies. The signature is symmetric across all brands.

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 and normalise the given command into wire form.

Brand-specific: CNR flattens as-is; IBS injects ResponseFormat=JSON.

Instantiate the brand Response for the given raw payload.

Return type is covariant so each brand pins its concrete Response.

Instantiate the SocketConfig for this client.

Subclasses return their own SocketConfig subtype.

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}.

Instantiate the brand's logger, writing to the given sink. Mirrors {newTransport()}/{@see newSocketConfig()}, and exists so a sink can be chosen without the brand's Logger class being named at the call site. An override must honour $sink — that is what makes {setLogSink()} work for a subclass.

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).

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\SessionCapable::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