Documentation
¶
Overview ¶
Package http provides the HTTP\Client and HTTP\Request bindings, the outbound HTTP surface a script reaches instead of PHP's curl_* family.
The types a script sees are facades over net/http rather than the net/http types themselves. Registration is not a method allowlist: every exported method and field of the value a constructor returns is reachable from PHP, so embedding *net/http.Request would publish the whole of net/http as methods on HTTP\Request. Each facade therefore holds its net/http value in a named unexported field, and the methods below are the whole surface.
Index ¶
- Constants
- func NewRequest(ctx context.Context, method, url string, body ...string) (*nethttp.Request, error)
- func Register(rt *runner.Runtime)
- type Client
- func (c *Client) Get(ctx context.Context, url string) (*Response, error)
- func (c *Client) Parallel(ctx context.Context, requests any) (map[string]*Response, error)
- func (c *Client) Post(ctx context.Context, url string, body ...string) (*Response, error)
- func (c *Client) Send(ctx context.Context, request *nethttp.Request) (*Response, error)
- type Response
Constants ¶
const DefaultTimeout = 30 * time.Second
DefaultTimeout is how long a client waits for a response when the script did not say. A request with no deadline at all is the one failure mode a script cannot recover from, so there is no way to ask for one.
Variables ¶
This section is empty.
Functions ¶
func NewRequest ¶
NewRequest builds a request from $method and $url, with an optional $body. Building a request sends nothing: pass it to a client with $client->send($request).
The value is a net/http request, so a script reads and writes it the way Go does: $request->method, $request->host, and $request->header->set($name, $value) for headers. Methods are written uppercase, "GET" and "POST"; a lowercase one is upper-cased rather than sent as written, because a server treats the method as case-sensitive and would reject it.
Types ¶
type Client ¶
type Client struct {
// contains filtered or unexported fields
}
Client is the PHP-visible HTTP\Client. The net/http client is a named unexported field rather than an embedded one, so a script reaches the methods below and nothing else net/http exports.
func NewClient ¶
NewClient is an HTTP client configured by an associative array of $timeout, $base_url, $follow_redirects, $user_agent, $headers and $insecure. Every key is optional, and `new HTTP\Client` gives a client with a 30 second timeout that follows redirects.
$timeout is in seconds and covers the whole request. $headers are sent with every request the client makes, and a header set on a request replaces the client's. $insecure disables certificate verification, which is for a test server and not for a service. An unrecognised key throws.
func (*Client) Parallel ¶
Parallel sends every request in $requests at once and returns the responses under the same keys, so the call takes as long as the slowest request rather than the sum. $requests is an array of HTTP\Request keyed by a name the script chooses, each bounded by the client's timeout.
One request failing does not fail the others and does not throw: that response reports $response->ok() as false and $response->err() as the reason, so a script sees every outcome. A throw means the argument was not an array of requests.
type Response ¶
type Response struct {
// contains filtered or unexported fields
}
Response is the PHP-visible result of sending a request.
This one is a facade rather than a net/http response, for two reasons. The body is read in full when the response is constructed, because a script has no stream to close and an unread net/http body leaks its connection. And ok() and json() are the two things a script does with a response that net/http has no equivalent for.
func (*Response) Err ¶
Err returns why the request failed, or an empty string when it did not. Only parallel() produces a failed response: send() throws instead, because there is one outcome to report rather than several.
func (*Response) Header ¶
Header returns the value of the named response header, or an empty string when it is not set. Header names are matched case-insensitively.
func (*Response) Headers ¶
Headers returns the response headers as an array of name to value. A header sent more than once is joined with ", ".
func (*Response) JSON ¶
JSON decodes the response body and returns it as arrays and scalars. It throws when the body is not valid JSON.
Source Files