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 Mux
- type Response
- type Server
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 Mux ¶ added in v0.6.0
type Mux struct {
// contains filtered or unexported fields
}
Mux is net/http's ServeMux with PHP callables as its handlers, answered on a worker runtime each. It is a facade rather than the ServeMux itself because nothing turns a PHP callable into the func(ResponseWriter, *Request) that HandleFunc declares. docs/use-cases/http-server.md is the surface.
func (*Mux) Handle ¶ added in v0.6.0
Handle registers $handler for $pattern, which is ServeMux.HandleFunc's pattern, with {name} segments the handler reads through $r->path_value($name).
$handler is a callable: a closure, a method read off its receiver as $this->fnName, or the name of a declared function. It is called with the response writer and the request, what it echoes reaches the response, and a throw is answered with a 500. docs/use-cases/http-server.md is the contract.
func (*Mux) ServeHTTP ¶ added in v0.6.0
func (m *Mux) ServeHTTP(w nethttp.ResponseWriter, r *nethttp.Request)
ServeHTTP answers one request, so a Go host can mount a script's router without the script listening on anything.
func (*Mux) UsePoolForTest ¶ added in v0.6.0
UsePoolForTest installs the workers, for a test sizing them itself. The server calls usePool; this is the same thing with a name a test can reach.
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.
type Server ¶ added in v0.6.0
type Server struct {
// contains filtered or unexported fields
}
Server listens and answers, which is what net/http's Server does and what a ServeMux does not. The vocabulary is Go's: listen(), then shutdown() to let the requests in flight finish, or close() to drop them.
func NewServer ¶ added in v0.6.0
NewServer builds a server for $addr answering through $handler, an HTTP\Mux or anything else that answers a request. Building one listens on nothing: listen() does that.
$workers is how many requests are answered at once, the number of cores when omitted, and the argument after it is how deep the queue behind them is, 1024 when omitted. docs/use-cases/http-server.md is what to size them by.
func (*Server) Addr ¶ added in v0.6.0
addr answers the address the server bound, empty until it has listened.
func (*Server) Close ¶ added in v0.6.0
close stops the server at once, dropping whatever was in flight. shutdown() is the one to reach for; this is for a script that has decided the answers no longer matter.
func (*Server) Listen ¶ added in v0.6.0
listen binds the address and starts answering, and returns the address it bound. It does not block: the script goes on, and calls wait() when it has nothing left to do.
func (*Server) Shutdown ¶ added in v0.6.0
func (s *Server) Shutdown()
Shutdown is http.Server.Shutdown with a second of grace, then Close.
It answers nothing and throws nothing: it is written into a register_shutdown_function callback, which runs when the script has already ended and has nowhere to put a failure. Calling it twice, or without having listened, is not an error either.
func (*Server) Wait ¶ added in v0.6.0
func (s *Server) Wait()
wait blocks until the script runs out of time, or the client that started it goes away, and returns. A script with no limit and no client waits until the host's own context ends, which for a command line run is never.
Nothing runs after it in a script the time limit ended: the limit is a fatal, as php's is, so the next statement is where the script stops. Cleanup belongs in a register_shutdown_function callback, which runs with the clock off.
Source Files