File: _docs/Request.md

Documentation for the "Request" class.

Used by CIDRAM and phpMussel to send outbound requests through cURL.

How to use:

• DefaultTimeout property.
• Channels property.
• Disabled property.
• SendToOut property.
• ObjLogger property.
• ObjLoggerFile property.
• Proxy property.
• ProxyAuth property.
• UserAgent property.
• MostRecentStatusCode property.
• request method.
• inCsv method.
• sendMessage method.

DefaultTimeout property.

Sets the default timeout to use for any requests which don't specify their own timeout.

public $DefaultTimeout = 12;

Channels property.

Can be used to specify alternative channels to use for requests matching specific patterns.

public $Channels = ['Triggers' => []];

Example data (YAML):

Triggers:
 GitHub: "https://raw.githubusercontent.com/"
 BitBucket: "https://bitbucket.org/"
GitHub:
 X example:
  GitHub: "https://raw.githubusercontent.com/foo/bar/x/"
  BitBucket: "https://bitbucket.org/foo/bar/raw/x/"
  NotABug: "https://notabug.org/foo/bar/raw/x/"
 Y example:
  GitHub: "https://raw.githubusercontent.com/foo/bar/y/"
  BitBucket: "https://bitbucket.org/foo/bar/raw/y/"
  NotABug: "https://notabug.org/foo/bar/raw/y/"
 Hello world:
  GitHub: "https://raw.githubusercontent.com/hello/world"
  BitBucket: "https://bitbucket.org/hello/world/raw"
  NotABug: "https://notabug.org/hello/world/raw"
BitBucket:
 Lorem ipsum:
  BitBucket: "https://bitbucket.org/lorem/ipsum/raw"
  GitHub: "https://raw.githubusercontent.com/lorem/ipsum"
  NotABug: "https://notabug.org/lorem/ipsum/raw"

"Channels" is an array, containing at least one sub-array, "Trigger". Stored in that sub-array, each "pattern" matches against the beginning of the URL of the request, serving as a "trigger" for identifying alternative channels. Each "trigger" should have its own corresponding sub-array, containing any number of groups of potential sub-matches, each containing any potential alternative channels. The provided "alternative channels" will replace the part of the URL of the request which matches the corresponding sub-match, and a subsequent new request will be made using the amended URL.

You can also just ignore this property entirely if you don't want to utilise alternative channels at your implementation.

Disabled property.

A CSV listing any alternative channels that should be disabled for the request (useful, for example, if you have a static list of alternative channels for your implementation, but provide the ability for end-users to optionally disable channels of their choice).

public $Disabled = '';

Example (per the earlier provided example):

X example,Y example,Hello world,Lorem ipsum

SendToOut property.

Whether to send the results of outbound requests to stdout (useful for debugging, but most likely won't ever be needed in production).

public $SendToOut = false;

ObjLogger property.

Object-level logger for the results of outbound requests (useful for debugging potential problems with outbound requests at the implementation).

public $ObjLogger = '';

ObjLoggerFile property.

Whether to dump the object-level logger to a file (and where to find it).

public $ObjLoggerFile = '';

Proxy property.

The URL of a proxy to use if required by the instance.

public $Proxy = '';

ProxyAuth property.

The username and password to use if required by the specified proxy URL.

#[Context(Sensitive: true)]
public $ProxyAuth = '';

UserAgent property.

The default user agent to cite when sending requests (for the sake of good netiquette and politeness towards any endpoints you intend to communicate with, this should definitely be populated when implementing the class according to your implementation).

public $UserAgent = 'Request class (https://github.com/Maikuolan/Common)';

MostRecentStatusCode property.

Whenever a request is performed, the status code returned by that request will be populated to this property (e.g., 200, 403, 404, etc).

public $MostRecentStatusCode = 0;

request method.

The main request method (this is what you'll want to use to actually perform a request).

public function request(string $URI, $Params = [], int $Timeout = -1, array $Headers = [], int $Depth = 0, string $Method = ''): string;

The first parameter ($URI) is the URL, URI, resource, etc that you want to request.

The second parameter ($Params) is for any parameters you want to send along with your request. If empty or omitted, CURLOPT_POST is false. Otherwise, CURLOPT_POST is true, and the parameter is used to supply CURLOPT_POSTFIELDS. Normally an associative array of key-value pairs, but can be any kind of value supported by CURLOPT_POSTFIELDS. Optional.

The third parameter ($Timeout) is an optional timeout limit for the request. When omitted, DefaultTimeout is used instead.

The fourth parameter ($Headers) is an optional array of headers to send with the request.

The fifth parameter ($Depth) represents the recursion depth of the current request instance, is populated automatically by request, and shouldn't be populated manually by the implementation (other than when needing access to the sixth parameter).

The sixth parameter ($Method) can be used to specify the intended request method in the event that the method intended isn't GET or POST. When the intended request method is GET or POST, it shouldn't be populated manually by the implementation (the method will determine automatically whether GET or POST is needed, based on factors like request parameters). This can be useful when methods such as CONNECT or DELETE are needed.

The method returns a string (either the returned resource, or an empty string on failure).

The class also implements the magic method __invoke, as a way to alias back to request when the instance is utilised as a callable or function.

public function __invoke(...$Params): string;

inCsv method.

Checks for a value within comma-separated values (CSV). Returns true when the value is found and false otherwise. This is used internally to process the Disabled property, and also made public for the benefit of use at the implementation elsewhere.

public function inCsv(string $Value, string $CSV): bool;

sendMessage method.

When SendToOut is true, this method sends messages to stdout whenever a request is performed, in a manner similar to the entries seen within standard access logs (this can sometimes be useful for debugging).

public function sendMessage(string $Message): void;

Last Updated: 2 July 2025 (2025.07.02).