HttpClientRequest

Represents a client-side HTTP request.

Instances are created by an @see \io\vertx\jphp\core\http\HttpClient instance, via one of the methods corresponding to the specific HTTP methods, or the generic request methods. On creation the request will not have been written to the wire.

Once a request has been obtained, headers can be set on it, and data can be written to its body if required. Once you are ready to send the request, one of the @see \io\vertx\jphp\core\http\HttpClientRequest::end methods should be called.

Nothing is actually sent until the request has been internally assigned an HTTP connection.

The @see \io\vertx\jphp\core\http\HttpClient instance will return an instance of this class immediately, even if there are no HTTP connections available in the pool. Any requests sent before a connection is assigned will be queued internally and actually sent when an HTTP connection becomes available from the pool.

The headers of the request are queued for writing either when the @see \io\vertx\jphp\core\http\HttpClientRequest::end method is called, or, when the first part of the body is written, whichever occurs first.

This class supports both chunked and non-chunked HTTP.

It implements @see \io\vertx\jphp\core\streams\WriteStream so it can be used with

see

to pump data with flow control.

An example of using this class is as follows:

package

Default

Methods

__construct

__construct() 

absoluteURI

absoluteURI() : string

Response

string

the absolute URI corresponding to the the HTTP request

A Throwable describing failure. This will be null if the operation succeeded.

cause() : \Exception

Response

\Exception

the cause or null if the operation succeeded.

Compose this future with a <code>mapper</code> function.<p>

compose( $arg0) : \io\vertx\jphp\core\http\Future<U>

When this future (the one on which compose is called) succeeds, the mapper will be called with the completed value and this mapper returns another future object. This returned future completion will complete the future returned by this method call.

If the mapper throws an exception, the returned future will be failed with this exception.

When this future fails, the failure will be propagated to the returned future and the mapper will not be called.

Arguments

$arg0

callable

Response

\io\vertx\jphp\core\http\Future

the composed future

connection

connection() : \io\vertx\jphp\core\http\HttpConnection

Response

\io\vertx\jphp\core\http\HttpConnection

the {@link HttpConnection} associated with this request

Set a connection handler called when an HTTP connection has been established.

connectionHandler( $arg0) : $this

Arguments

$arg0

callable

Response

$this

a reference to this, so the API can be used fluently

If you send an HTTP request with the header <code>Expect</code> set to the value <code>100-continue</code> and the server responds with an interim HTTP response with a status code of <code>100</code> and a continue handler has been set using this method, then the <code>handler</code> will be called.

continueHandler( $arg0) : $this

You can then continue to write data to the request body and later end it. This is normally used in conjunction with the @see \io\vertx\jphp\core\http\HttpClientRequest::sendHead method to force the request header to be written before the request has ended.

Arguments

$arg0

callable

Response

$this

a reference to this, so the API can be used fluently

drainHandler

drainHandler( $arg0) : $this

Arguments

$arg0

callable

Response

$this

Same as @see \io\vertx\jphp\core\http\HttpClientRequest::end but with an <code>handler</code> called when the operation completes

end( $arg0,  $arg1 = null,  $arg2 = null) : void

param $handler [callable] end($handler)

Same as @see \io\vertx\jphp\core\http\HttpClientRequest::end but with an handler called when the operation completes

param $chunk [string] param $handler [callable] end($chunk, $handler)

Same as @see \io\vertx\jphp\core\http\HttpClientRequest::end but with an handler called when the operation completes

param $chunk [Buffer] param $handler [callable] end($chunk, $handler)

Same as @see \io\vertx\jphp\core\http\HttpClientRequest::end but with an handler called when the operation completes

param $chunk [string] param $enc [string] param $handler [callable] end($chunk, $enc, $handler)

Arguments

$arg0

Buffer | callable | string

$arg1

callable | string

$arg2

callable

exceptionHandler

exceptionHandler( $arg0) : $this

Arguments

$arg0

callable

Response

$this

Did it fail?

failed() : boolean

Response

boolean

true if it failed or false otherwise

getHandler

getHandler() : callable

Response

callable

the handler for the result

getHost

getHost() : string

Response

string

the request host. For HTTP/2 it returns the {@literal :authority} pseudo header otherwise it returns the {@literal Host} header

getRawMethod

getRawMethod() : string

Response

string

the raw value of the method this request sends

getStreamPriority

getStreamPriority() : array

Response

array

the priority of the associated HTTP/2 stream for HTTP/2 otherwise {@code null}

headers

headers() : \io\vertx\jphp\core\MultiMap

Response

\io\vertx\jphp\core\MultiMap

The HTTP headers

isChunked

isChunked() : boolean

Response

boolean

Is the request chunked?

Has the future completed? <p> It's completed if it's either succeeded or failed.

isComplete() : boolean

Response

boolean

true if completed, false if not

Apply a <code>mapper</code> function on this future.<p>

map( $arg0) : \io\vertx\jphp\core\http\Future<U>

When this future succeeds, the mapper will be called with the completed value and this mapper returns a value. This value will complete the future returned by this method call.

If the mapper throws an exception, the returned future will be failed with this exception.

When this future fails, the failure will be propagated to the returned future and the mapper will not be called.

param $mapper [callable] the mapper function map($mapper)

Map the result of a future to a specific value.

When this future succeeds, this value will complete the future returned by this method call.

When this future fails, the failure will be propagated to the returned future.

param $value [mixed] the value that eventually completes the mapped future map($value)

Arguments

$arg0

callable | mixed

Response

\io\vertx\jphp\core\http\Future

the mapped future

Map the result of a future to <code>null</code>.<p>

mapEmpty() : \io\vertx\jphp\core\http\Future<V>

This is a conveniency for future.map((T) null) or future.map((Void) null).

When this future succeeds, null will complete the future returned by this method call.

When this future fails, the failure will be propagated to the returned future.

Response

\io\vertx\jphp\core\http\Future

the mapped future

The HTTP method for the request.

method() : string

Response

string

Apply a <code>mapper</code> function on this future.<p>

otherwise( $arg0) : \io\vertx\jphp\core\http\Future<HttpClientResponse>

When this future fails, the mapper will be called with the completed value and this mapper returns a value. This value will complete the future returned by this method call.

If the mapper throws an exception, the returned future will be failed with this exception.

When this future succeeds, the result will be propagated to the returned future and the mapper will not be called.

param $mapper [callable] the mapper function otherwise($mapper)

Map the failure of a future to a specific value.

When this future fails, this value will complete the future returned by this method call.

When this future succeeds, the result will be propagated to the returned future.

param $value [HttpClientResponse] the value that eventually completes the mapped future otherwise($value)

Arguments

$arg0

callable | HttpClientResponse

Response

\io\vertx\jphp\core\http\Future

the mapped future

Map the failure of a future to <code>null</code>.<p>

otherwiseEmpty() : \io\vertx\jphp\core\http\Future<HttpClientResponse>

This is a convenience for future.otherwise((T) null).

When this future fails, the null value will complete the future returned by this method call.

When this future succeeds, the result will be propagated to the returned future.

Response

\io\vertx\jphp\core\http\Future

the mapped future

path

path() : string

Response

string

The path part of the uri. For example /somepath/somemorepath/someresource.foo

Set a push handler for this request.<p/>

pushHandler( $arg0) : $this

The handler is called when the client receives a push promise from the server. The handler can be called multiple times, for each push promise.

The handler is called with a read-only @see \io\vertx\jphp\core\http\HttpClientRequest, the following methods can be called:

  • @see \io\vertx\jphp\core\http\HttpClientRequest::method
  • @see \io\vertx\jphp\core\http\HttpClientRequest::uri
  • @see \io\vertx\jphp\core\http\HttpClientRequest::headers
  • @see \io\vertx\jphp\core\http\HttpClientRequest::getHost

In addition the handler should call the @see \io\vertx\jphp\core\http\HttpClientRequest::setHandler method to set an handler to process the response.

Arguments

$arg0

callable

Response

$this

a reference to this, so the API can be used fluently

Put an HTTP header

putHeader( $arg0,  $arg1) : $this

Arguments

$arg0

string

$arg1

string

Response

$this

a reference to this, so the API can be used fluently

query

query() : string

Response

string

the query part of the uri. For example someparam=32&someotherparam=x

Handles a failure of this Future by returning the result of another Future.

recover( $arg0) : \io\vertx\jphp\core\http\Future<HttpClientResponse>

If the mapper fails, then the returned future will be failed with this failure.

Arguments

$arg0

callable

Response

\io\vertx\jphp\core\http\Future

A recovered future

Reset this stream with the error code <code>0</code>.

reset( $arg0 = null) : boolean

reset()

Reset this request:

  • for HTTP/2, this performs send an HTTP/2 reset frame with the specified error code
  • for HTTP/1.x, this closes the connection when the current request is inflight

When the request has not yet been sent, the request will be aborted and false is returned as indicator.

param $code [integer] the error code reset($code)

Arguments

$arg0

integer

Response

boolean

The result of the operation. This will be null if the operation failed.

result() : \io\vertx\jphp\core\http\HttpClientResponse

Response

\io\vertx\jphp\core\http\HttpClientResponse

the result or null if the operation failed.

Forces the head of the request to be written before @see \io\vertx\jphp\core\http\HttpClientRequest::end is called on the request or any data is written to it.

sendHead( $arg0 = null) : $this

This is normally used to implement HTTP 100-continue handling, see for more information. sendHead() Like @see \io\vertx\jphp\core\http\HttpClientRequest::sendHead but with an handler after headers have been sent. The handler will be called with the \io.vertx.core.http.HttpVersion if it can be determined or null otherwise.

param $completionHandler [callable] sendHead($completionHandler)

Arguments

$arg0

callable

Response

$this

a reference to this, so the API can be used fluently

If chunked is true then the request will be set into HTTP chunked mode

setChunked( $arg0) : $this

Arguments

$arg0

boolean

Response

$this

a reference to this, so the API can be used fluently

Set the request to follow HTTP redirects up to @see \io\vertx\jphp\core\http\HttpClientOptions.

setFollowRedirects( $arg0) : $this

Arguments

$arg0

boolean

Response

$this

a reference to this, so the API can be used fluently

setHandler

setHandler( $arg0) : $this

Arguments

$arg0

callable

Response

$this

Set the request host.<p/>

setHost( $arg0) : $this

For HTTP/2 it sets the pseudo header otherwise it sets the header

Arguments

$arg0

string

Response

$this

Set the max number of HTTP redirects this request will follow. The default is <code>0</code> which means no redirects.

setMaxRedirects( $arg0) : $this

Arguments

$arg0

integer

Response

$this

a reference to this, so the API can be used fluently

Set the value the method to send when the method is used.

setRawMethod( $arg0) : $this

Arguments

$arg0

string

Response

$this

a reference to this, so the API can be used fluently

Sets the priority of the associated stream.

setStreamPriority( $arg0) : $this

This is not implemented for HTTP/1.x.

Arguments

$arg0

array

Response

$this

Set's the amount of time after which if the request does not return any data within the timeout period an {@link java.util.concurrent.TimeoutException} will be passed to the exception handler (if provided) and the request will be closed.

setTimeout( $arg0) : $this

Calling this method more than once has the effect of canceling any existing timeout and starting the timeout from scratch.

Arguments

$arg0

integer

Response

$this

a reference to this, so the API can be used fluently

setWriteQueueMaxSize

setWriteQueueMaxSize( $arg0) : $this

Arguments

$arg0

integer

Response

$this

streamId

streamId() : integer

Response

integer

the id of the stream of this response, {@literal -1} when it is not yet determined, i.e the request has not been yet sent or it is not supported HTTP/1.x

Did it succeed?

succeeded() : boolean

Response

boolean

true if it succeded or false otherwise

uri

uri() : string

Response

string

The URI of the request.

Same as but with an <code>handler</code> called when the operation completes

write( $arg0,  $arg1,  $arg2 = null) : void

param $data [Buffer] param $handler [callable] write($data, $handler)

Same as @see \io\vertx\jphp\core\http\HttpClientRequest::write but with an handler called when the operation completes

param $chunk [string] param $handler [callable] write($chunk, $handler)

Same as @see \io\vertx\jphp\core\http\HttpClientRequest::write but with an handler called when the operation completes

param $chunk [string] param $enc [string] param $handler [callable] write($chunk, $enc, $handler)

Arguments

$arg0

Buffer | string

$arg1

callable | string

$arg2

callable

Like @see \io\vertx\jphp\core\http\HttpClientRequest::writeCustomFrame but with an @see \io\vertx\jphp\core\http\HttpFrame.

writeCustomFrame( $arg0,  $arg1 = null,  $arg2 = null) : $this

param $frame [HttpFrame] the frame to write writeCustomFrame($frame)

Write an HTTP/2 frame to the request, allowing to extend the HTTP/2 protocol.

The frame is sent immediatly and is not subject to flow control.

This method must be called after the request headers have been sent and only for the protocol HTTP/2. The @see \io\vertx\jphp\core\http\HttpClientRequest::sendHead should be used for this purpose.

param $type [integer] the 8-bit frame type param $flags [integer] the 8-bit frame flags param $payload [Buffer] the frame payload writeCustomFrame($type, $flags, $payload)

Arguments

$arg0

integer | HttpFrame

$arg1

integer

$arg2

Buffer

Response

$this

This will return <code>true</code> if there are more bytes in the write queue than the value set using @see \io\vertx\jphp\core\http\HttpClientRequest::setWriteQueueMaxSize

writeQueueFull() : boolean

Response

boolean

true if write queue is full