Documentation

Request extends AbstractRequest
in package

HTTP client request class

Tags
category

Pop

author

Nick Sagona, III nick@popphp.org

copyright

Copyright (c) 2009-2026 Nick Sagona, III

license

https://www.popphp.org/license New BSD License

version
6.0.0

Table of Contents

Constants

JSON  = 'application/json'
MULTIPART  = 'multipart/form-data'
URLENCODED  = 'application/x-www-form-urlencoded'
Request type constants
XML  = 'application/xml'

Properties

$body  : Body|null
Body
$data  : Data|null
Client request data object
$headerIndex  : array<string|int, mixed>
Case-folded header name index (lowercase name => actual stored key), kept in sync by addHeader()/removeHeader()/setHeaders()/removeHeaders() so resolveHeaderName() - used by every PSR-7 case-insensitive lookup (getHeader()/withHeader()/withAddedHeader()/ withoutHeader()) - is an O(1) lookup instead of a linear strcasecmp() scan of every header.
$headers  : array<string|int, mixed>
Headers
$method  : string|null
Request method
$noContentLength  : bool
No Content-Length header flag
$protocolVersion  : string
HTTP protocol version, per PSR-7
$query  : Data|null
Client request query data object
$rawData  : bool
Raw data flag
$requestTargetOverride  : string|null
Explicit request-target override, per PSR-7 (null = derive from the URI)
$requestType  : string|null
Request type
$uri  : Uri|null
Request URI object

Methods

__call()  : bool
Magic method to check the is[Method](), i.e. $request->isPost();
__clone()  : void
Deep-clone the query and data objects so a with*() clone never shares mutable Data state (or its back-reference) with the instance it was cloned from
__construct()  : mixed
Constructor
__get()  : mixed
Magic method to get either the headers or body
addData()  : Request
Add data
addHeader()  : Request
Add a header
addHeaders()  : AbstractRequestResponse
Add all headers
addQuery()  : Request
Add query data
clearMethod()  : Request
Clear method
clearUri()  : AbstractRequest
Clear URI
create()  : Request
Factory method to create a Request object
createAsCustomType()  : Request
Create request as custom content type
createAsJson()  : Request
Create request as JSON
createAsMultipart()  : Request
Create request as a multipart form
createAsUrlEncoded()  : Request
Create request as a URL-encoded form
createAsXml()  : Request
Create request as XML
createJson()  : Request
Factory method to create a JSON Request object
createMultipart()  : Request
Factory method to create a multipart Request object
createUrlEncoded()  : Request
Factory method to create a URL-encoded Request object
createXml()  : Request
Factory method to create an XML Request object
decodeBodyContent()  : Body
Decode the body
getBody()  : Body
Get the body, per PSR-7 (a transient, never-stored empty Body when none is set, so hasBody() remains unaffected by calling this)
getBodyContent()  : mixed
Get body content
getBodyContentLength()  : int
Get body content length
getData()  : Data|null
Get data
getDataContent()  : string|null
Get the data content
getDataContentLength()  : int|null
Get the data content length
getHeader()  : array<string|int, mixed>
Get all string values for a header, per PSR-7 (empty array if absent, case-insensitive)
getHeaderAsString()  : mixed
Get a header
getHeaderLine()  : string
Get a header's values comma-joined into one string, per PSR-7
getHeaderObject()  : mixed
Get a header
getHeaderObjects()  : array<string|int, mixed>
Get all headers
getHeaders()  : array<string|int, mixed>
Get all headers, per PSR-7 (each header's values array-wrapped)
getHeadersAsArray()  : array<string|int, mixed>
Get all header values as associative array
getHeadersAsString()  : string
Get all header values formatted string
getHeaderValue()  : mixed
Get header value
getHeaderValueAsString()  : string|null
Get header value as string
getMethod()  : string
Get method
getProtocolVersion()  : string
Get the HTTP protocol version, per PSR-7
getQuery()  : Data|null
Get query data
getRequestTarget()  : string
Get the request target, per PSR-7 (path + query, or '/' with no URI, unless overridden)
getRequestType()  : string|null
Get request type
getUri()  : Uri
Get URI, per PSR-7 (a transient, never-stored empty Uri when none is set, so hasUri() remains unaffected by calling this)
getUriAsString()  : string
Get full URI as string
hasBody()  : bool
Has a body
hasBodyContent()  : bool
Has body content
hasData()  : bool
Has data
hasDataContent()  : bool
Has data content
hasHeader()  : bool
Has a header
hasHeaders()  : bool
Determine if there are headers
hasMethod()  : bool
Has method
hasQuery()  : bool
Has query data
hasRequestType()  : bool
Has request type
hasUri()  : bool
Has URI
isCustomType()  : bool
Check if request is a custom content type
isJson()  : bool
Check if request is JSON
isMultipart()  : bool
Check if request is a multipart form
isNoContentLength()  : bool
Is no Content-Length header flag
isUrlEncoded()  : bool
Check if request is a URL-encoded form
isValidMethod()  : bool
Is valid method
isXml()  : bool
Check if request is XML
prepareData()  : Request
Prepare request data
removeAllData()  : Request
Remove all data
removeAllQuery()  : Request
Remove all query data
removeBody()  : AbstractRequestResponse
Remove the body
removeData()  : Request
Remove data
removeHeader()  : AbstractRequestResponse
Remove a header
removeHeaders()  : AbstractRequestResponse
Remove all headers
removeQuery()  : Request
Remove query data
removeRequestType()  : Request
Remove request type
setBody()  : AbstractRequestResponse
Set the body
setData()  : Request
Set data
setHeaders()  : AbstractRequestResponse
Set all headers (clear out any existing headers)
setMethod()  : Request
Set method
setNoContentLength()  : Request
Set no Content-Length header flag
setQuery()  : Request
Set query data
setRawData()  : Request
Set raw data flag
setRequestType()  : Request
Set request type
setUri()  : AbstractRequest
Set URI
useRawData()  : bool
Use raw data
withAddedHeader()  : static
Return an instance with the specified header value(s) appended, per PSR-7
withBody()  : static
Return an instance with the specified body, per PSR-7
withHeader()  : static
Return an instance with the specified header, replacing any existing values, per PSR-7
withMethod()  : static
Return an instance with the specified method, per PSR-7
withoutHeader()  : static
Return an instance without the specified header, per PSR-7
withProtocolVersion()  : static
Return an instance with the specified HTTP protocol version, per PSR-7
withRequestTarget()  : static
Return an instance with the specified request target, per PSR-7
withUri()  : static
Return an instance with the specified URI, per PSR-7
resetDataIfAlreadyPrepared()  : void
Reset the data object's prepared state if it was already prepared

Constants

JSON

public mixed JSON = 'application/json'

MULTIPART

public mixed MULTIPART = 'multipart/form-data'

URLENCODED

Request type constants

public string URLENCODED = 'application/x-www-form-urlencoded'

XML

public mixed XML = 'application/xml'

Properties

$data

Client request data object

protected Data|null $data = null

Can be any type of supported request data:

  • URL-encoded query string on the URI (GET method)
  • URL-encoded body (any method other than GET)
  • JSON-encoded body
  • XML-encoded body
  • Multipart/form body

$headerIndex

Case-folded header name index (lowercase name => actual stored key), kept in sync by addHeader()/removeHeader()/setHeaders()/removeHeaders() so resolveHeaderName() - used by every PSR-7 case-insensitive lookup (getHeader()/withHeader()/withAddedHeader()/ withoutHeader()) - is an O(1) lookup instead of a linear strcasecmp() scan of every header.

protected array<string|int, mixed> $headerIndex = []

$method

Request method

protected string|null $method = null

$noContentLength

No Content-Length header flag

protected bool $noContentLength = false

$protocolVersion

HTTP protocol version, per PSR-7

protected string $protocolVersion = '1.1'

$query

Client request query data object

protected Data|null $query = null

Can only be a URL-encoded query string on the URI

$rawData

Raw data flag

protected bool $rawData = false

$requestTargetOverride

Explicit request-target override, per PSR-7 (null = derive from the URI)

protected string|null $requestTargetOverride = null

$requestType

Request type

protected string|null $requestType = null

Methods

__call()

Magic method to check the is[Method](), i.e. $request->isPost();

public __call(string $methodName[, array<string|int, mixed>|null $arguments = null ]) : bool
Parameters
$methodName : string
$arguments : array<string|int, mixed>|null = null
Tags
throws
Exception
Return values
bool

__clone()

Deep-clone the query and data objects so a with*() clone never shares mutable Data state (or its back-reference) with the instance it was cloned from

public __clone() : void

__construct()

Constructor

public __construct([Uri|string|null $uri = null ][, string|null $method = 'GET' ][, mixed $data = null ][, string|null $type = null ][, bool $strict = false ]) : mixed

Instantiate the request data object

Parameters
$uri : Uri|string|null = null
$method : string|null = 'GET'
$data : mixed = null
$type : string|null = null
$strict : bool = false
Tags
throws
Exception|Exception

__get()

Magic method to get either the headers or body

public __get(string $name) : mixed
Parameters
$name : string

addData()

Add data

public addData(mixed $name, mixed $value) : Request
Parameters
$name : mixed
$value : mixed
Return values
Request

addHeader()

Add a header

public addHeader(Header|string|int $header[, string|null $value = null ]) : Request
Parameters
$header : Header|string|int
$value : string|null = null
Return values
Request

addQuery()

Add query data

public addQuery(mixed $name, mixed $value) : Request
Parameters
$name : mixed
$value : mixed
Return values
Request

create()

Factory method to create a Request object

public static create([Uri|string|null $uri = null ][, string $method = 'GET' ][, mixed $data = null ][, string|null $type = null ][, bool $strict = false ]) : Request
Parameters
$uri : Uri|string|null = null
$method : string = 'GET'
$data : mixed = null
$type : string|null = null
$strict : bool = false
Tags
throws
Exception|Exception
Return values
Request

createAsCustomType()

Create request as custom content type

public createAsCustomType(string $type[, bool $addHeader = true ]) : Request
Parameters
$type : string
$addHeader : bool = true
Return values
Request

createAsJson()

Create request as JSON

public createAsJson([string $type = self::JSON ][, bool $addHeader = true ]) : Request
Parameters
$type : string = self::JSON
$addHeader : bool = true
Return values
Request

createAsMultipart()

Create request as a multipart form

public createAsMultipart([string $type = self::MULTIPART ]) : Request
Parameters
$type : string = self::MULTIPART
Return values
Request

createAsUrlEncoded()

Create request as a URL-encoded form

public createAsUrlEncoded([string $type = self::URLENCODED ][, bool $addHeader = true ]) : Request
Parameters
$type : string = self::URLENCODED
$addHeader : bool = true
Return values
Request

createAsXml()

Create request as XML

public createAsXml([string $type = self::XML ][, bool $addHeader = true ]) : Request
Parameters
$type : string = self::XML
$addHeader : bool = true
Return values
Request

createJson()

Factory method to create a JSON Request object

public static createJson([Uri|string|null $uri = null ][, string $method = 'POST' ][, mixed $data = null ][, bool $strict = false ]) : Request
Parameters
$uri : Uri|string|null = null
$method : string = 'POST'
$data : mixed = null
$strict : bool = false
Tags
throws
Exception|Exception
Return values
Request

createMultipart()

Factory method to create a multipart Request object

public static createMultipart([Uri|string|null $uri = null ][, string $method = 'POST' ][, mixed $data = null ][, bool $strict = false ]) : Request
Parameters
$uri : Uri|string|null = null
$method : string = 'POST'
$data : mixed = null
$strict : bool = false
Tags
throws
Exception|Exception
Return values
Request

createUrlEncoded()

Factory method to create a URL-encoded Request object

public static createUrlEncoded([Uri|string|null $uri = null ][, string $method = 'GET' ][, mixed $data = null ][, bool $strict = false ]) : Request
Parameters
$uri : Uri|string|null = null
$method : string = 'GET'
$data : mixed = null
$strict : bool = false
Tags
throws
Exception|Exception
Return values
Request

createXml()

Factory method to create an XML Request object

public static createXml([Uri|string|null $uri = null ][, string $method = 'POST' ][, mixed $data = null ][, bool $strict = false ]) : Request
Parameters
$uri : Uri|string|null = null
$method : string = 'POST'
$data : mixed = null
$strict : bool = false
Tags
throws
Exception|Exception
Return values
Request

decodeBodyContent()

Decode the body

public decodeBodyContent([string|null $body = null ]) : Body
Parameters
$body : string|null = null
Return values
Body

getBody()

Get the body, per PSR-7 (a transient, never-stored empty Body when none is set, so hasBody() remains unaffected by calling this)

public getBody() : Body
Return values
Body

getBodyContentLength()

Get body content length

public getBodyContentLength([bool $mb = false ]) : int
Parameters
$mb : bool = false
Return values
int

getDataContent()

Get the data content

public getDataContent() : string|null
Return values
string|null

getDataContentLength()

Get the data content length

public getDataContentLength([bool $mb = false ]) : int|null
Parameters
$mb : bool = false
Return values
int|null

getHeader()

Get all string values for a header, per PSR-7 (empty array if absent, case-insensitive)

public getHeader(string $name) : array<string|int, mixed>
Parameters
$name : string
Return values
array<string|int, mixed>

getHeaderAsString()

Get a header

public getHeaderAsString(string $name) : mixed
Parameters
$name : string

getHeaderLine()

Get a header's values comma-joined into one string, per PSR-7

public getHeaderLine(string $name) : string
Parameters
$name : string
Return values
string

getHeaderObject()

Get a header

public getHeaderObject(string $name) : mixed
Parameters
$name : string

getHeaderObjects()

Get all headers

public getHeaderObjects() : array<string|int, mixed>
Return values
array<string|int, mixed>

getHeaders()

Get all headers, per PSR-7 (each header's values array-wrapped)

public getHeaders() : array<string|int, mixed>
Return values
array<string|int, mixed>

getHeadersAsArray()

Get all header values as associative array

public getHeadersAsArray([bool $asStrings = true ]) : array<string|int, mixed>
Parameters
$asStrings : bool = true
Return values
array<string|int, mixed>

getHeadersAsString()

Get all header values formatted string

public getHeadersAsString([mixed $status = null ][, string $eol = " " ]) : string
Parameters
$status : mixed = null
$eol : string = " "
Return values
string

getHeaderValue()

Get header value

public getHeaderValue(string $name[, int $i = 0 ]) : mixed
Parameters
$name : string
$i : int = 0

getHeaderValueAsString()

Get header value as string

public getHeaderValueAsString(string $name[, int $i = 0 ]) : string|null
Parameters
$name : string
$i : int = 0
Return values
string|null

getMethod()

Get method

public getMethod() : string
Return values
string

getProtocolVersion()

Get the HTTP protocol version, per PSR-7

public getProtocolVersion() : string
Return values
string

getQuery()

Get query data

public getQuery() : Data|null
Return values
Data|null

getRequestTarget()

Get the request target, per PSR-7 (path + query, or '/' with no URI, unless overridden)

public getRequestTarget() : string
Return values
string

getRequestType()

Get request type

public getRequestType() : string|null
Return values
string|null

getUri()

Get URI, per PSR-7 (a transient, never-stored empty Uri when none is set, so hasUri() remains unaffected by calling this)

public getUri() : Uri
Return values
Uri

getUriAsString()

Get full URI as string

public getUriAsString([bool $query = true ]) : string
Parameters
$query : bool = true
Return values
string

hasData()

Has data

public hasData() : bool
Return values
bool

hasDataContent()

Has data content

public hasDataContent() : bool
Return values
bool

hasHeader()

Has a header

public hasHeader(string $name) : bool
Parameters
$name : string
Return values
bool

hasMethod()

Has method

public hasMethod() : bool
Return values
bool

hasQuery()

Has query data

public hasQuery() : bool
Return values
bool

hasRequestType()

Has request type

public hasRequestType() : bool
Return values
bool

isCustomType()

Check if request is a custom content type

public isCustomType() : bool
Return values
bool

isJson()

Check if request is JSON

public isJson() : bool
Return values
bool

isMultipart()

Check if request is a multipart form

public isMultipart() : bool
Return values
bool

isNoContentLength()

Is no Content-Length header flag

public isNoContentLength() : bool
Return values
bool

isUrlEncoded()

Check if request is a URL-encoded form

public isUrlEncoded() : bool
Return values
bool

isValidMethod()

Is valid method

public isValidMethod(string $method) : bool
Parameters
$method : string
Return values
bool

isXml()

Check if request is XML

public isXml() : bool
Return values
bool

removeData()

Remove data

public removeData(string $key) : Request
Parameters
$key : string
Return values
Request

removeQuery()

Remove query data

public removeQuery(string $key) : Request
Parameters
$key : string
Return values
Request

removeRequestType()

Remove request type

public removeRequestType([bool $removeHeader = false ]) : Request
Parameters
$removeHeader : bool = false
Return values
Request

setData()

Set data

public setData(mixed $data[, mixed $filters = null ]) : Request
Parameters
$data : mixed
$filters : mixed = null
Return values
Request

setMethod()

Set method

public setMethod(string $method[, bool $strict = false ]) : Request
Parameters
$method : string
$strict : bool = false
Tags
throws
Exception
Return values
Request

setNoContentLength()

Set no Content-Length header flag

public setNoContentLength(bool $noContentLength) : Request
Parameters
$noContentLength : bool
Return values
Request

setQuery()

Set query data

public setQuery(mixed $query[, mixed $filters = null ]) : Request
Parameters
$query : mixed
$filters : mixed = null
Return values
Request

setRawData()

Set raw data flag

public setRawData(bool $rawData) : Request
Parameters
$rawData : bool
Return values
Request

setRequestType()

Set request type

public setRequestType([string|null $type = null ][, bool $handleHeader = true ]) : Request
Parameters
$type : string|null = null
$handleHeader : bool = true
Return values
Request

useRawData()

Use raw data

public useRawData() : bool
Return values
bool

withAddedHeader()

Return an instance with the specified header value(s) appended, per PSR-7

public withAddedHeader(string $name, mixed $value) : static

Parameter is typed mixed (rather than string|array) only to satisfy PSR-7's untyped MessageInterface::withAddedHeader() signature per PHP's LSP variance rules; the supported values remain a string or an array of strings.

Parameters
$name : string
$value : mixed
Return values
static

withBody()

Return an instance with the specified body, per PSR-7

public withBody(Body|StreamInterface $body) : static
Parameters
$body : Body|StreamInterface
Return values
static

withHeader()

Return an instance with the specified header, replacing any existing values, per PSR-7

public withHeader(string $name, mixed $value) : static

Parameter is typed mixed (rather than string|array) only to satisfy PSR-7's untyped MessageInterface::withHeader() signature per PHP's LSP variance rules; the supported values remain a string or an array of strings.

Parameters
$name : string
$value : mixed
Return values
static

withMethod()

Return an instance with the specified method, per PSR-7

public withMethod(string $method) : static
Parameters
$method : string
Return values
static

withoutHeader()

Return an instance without the specified header, per PSR-7

public withoutHeader(string $name) : static
Parameters
$name : string
Return values
static

withProtocolVersion()

Return an instance with the specified HTTP protocol version, per PSR-7

public withProtocolVersion(string $version) : static
Parameters
$version : string
Return values
static

withRequestTarget()

Return an instance with the specified request target, per PSR-7

public withRequestTarget(string $requestTarget) : static
Parameters
$requestTarget : string
Return values
static

withUri()

Return an instance with the specified URI, per PSR-7

public withUri(UriInterface $uri[, bool $preserveHost = false ]) : static
Parameters
$uri : UriInterface
$preserveHost : bool = false
Return values
static

resetDataIfAlreadyPrepared()

Reset the data object's prepared state if it was already prepared

protected resetDataIfAlreadyPrepared() : void

Guards against Data::setData() having eagerly prepared its content against whatever request type was set before this createAsXxx() call - without this, the stale Content-Type/dataContent baked in at that earlier setData() time would survive, since the handlers only re-prepare when isPrepared() is false.


        

        
    




    

    

                                

                

                                
    

        On this page

        
    


                

                            

            

    

        

            
Search results