HTTP Request (PSR-7)

    Phalcon\Http\Message\Request is an implementation of the HTTP messaging interface as defined by PHP-FIG.

    This implementation has been created to establish a standard between middleware implementations. Applications often need to send requests to external endpoints. To achieve this you can use the object. In return, our application will receive back a response object.

    In the examples below, is the client of your choice which implements PSR-7.

    We are creating a new Phalcon\Http\Message\Request object and a new object with the target URL. Following that we define the method (POST) and additional headers that we need to send with our request. The client then sends the request by using the request object.

    The above example can be implemented by only using the constructor parameters:

    1. <?php
    3. use Phalcon\Http\Message\Request;
    5. $jwtToken = 'abc.def.ghi';
    7. $request = new Request(
    8.     'POST',
    9.     'https://api.phalcon.io/companies/1',
    10.     'php://memory',
    11.     [
    12.         'Authorization' => 'Bearer ' . $jwtToken,
    13.         'Content-Type'  => 'application/json',
    14.     ]
    15. );
    17. $result = $httpClient->send($request);

    The Request object created is immutable, meaning it will never change. Any call to methods prefixed with with* will return a clone of the object to maintain immutability, as per the standard.

    1. public function __construct(
    2.     [string $method = "GET" 
    3.     [, mixed $uri = null 
    4.     [, mixed $body = "php://temp" 
    5.     [, array $headers = [] ]]]]
    6. )
    • method - defaults to GET. The supported methods are: GET, CONNECT, DELETE, HEAD, OPTIONS, PATCH, POST, PUT, TRACE
    • uri - An instance of or a URL.
    • body - It defaults to php://memory. The method accepts either an object that implements the StreamInterface interface or a string such as the name of the stream. The default mode for the stream is w+b. If a non valid stream is passed, an InvalidArgumentException is thrown
    • headers - A key value array, with key as the header name and value as the header value.

    Returns the body as a StreamInterface object

    1. <?php
    3. use Phalcon\Http\Message\Request;
    4. use Phalcon\Http\Message\Stream;
    6. $jwtToken = 'abc.def.ghi';
    7. $fileName = dataFolder('/assets/stream/mit.txt');
    8. $stream   = new Stream($fileName, 'rb');
    10. $request = new Request(
    11.     'POST',
    12.     'https://api.phalcon.io/companies/1',
    13.     $stream,
    14.     [
    15.         'Authorization' => 'Bearer ' . $jwtToken,
    16.         'Content-Type'  => 'application/json',
    17.     ]
    18. );
    20. echo $request->getBody(); // '/assets/stream/mit.txt'

    getHeader()

    Returns an array of all the header values of the passed case insensitive header name. If the string parameter representing the header name requested is not present, an empty array is returned.

    1. <?php
    3. use Phalcon\Http\Message\Request;
    5. $jwtToken = 'abc.def.ghi';
    7. $request = new Request(
    8.     'POST',
    9.     'https://api.phalcon.io/companies/1',
    10.     'php://memory',
    11.     [
    12.         'Authorization' => 'Bearer ' . $jwtToken,
    13.         'Content-Type'  => 'application/json',
    14.     ]
    15. );
    17. echo $request->getHeader('content-Type'); // ['application/json']
    18. echo $request->getHeader('unknown');      // []

    getHeaderLine()

    Returns all of the header values of the given case-insensitive header name as a string concatenated together using a comma. If the string parameter representing the header name requested, an empty string is returned.

    1. <?php
    3. use Phalcon\Http\Message\Request;
    5. $jwtToken = 'abc.def.ghi';
    7. $request = new Request(
    8.     'POST',
    9.     'https://api.phalcon.io/companies/1',
    10.     'php://memory',
    11.     [
    12.         'Authorization' => 'Bearer ' . $jwtToken,
    13.         'Content-Type'  => [
    14.             'application/json',
    15.             'application/html',
    16.         ],
    17.     ]
    18. );
    20. echo $request->getHeaderLine('content-Type'); // 'application/json,application/html'

    getHeaders()

    Returns an array with all the message header values. The keys represent the header name as it will be sent over the wire, and each value is an array of strings associated with the header. While header names are not case-sensitive, this method preserves the exact case in which headers were originally specified.

    getMethod()

    Returns the method as a string

    1. <?php
    2. use Phalcon\Http\Message\Request;
    4. $jwtToken = 'abc.def.ghi';
    6. $request = new Request(
    7.     'POST',
    8.     'https://api.phalcon.io/companies/1',
    9.     'php://memory',
    11.         'Authorization' => 'Bearer ' . $jwtToken,
    12.         'Content-Type'  => 'application/json',
    13.     ]
    14. );
    16. echo $request->getMethod(); // POST

    Returns the protocol version as as string (default 1.1)

    1. <?php
    3. use Phalcon\Http\Message\Request;
    5. $jwtToken = 'abc.def.ghi';
    7. $request = new Request(
    8.     'POST',
    9.     'https://api.phalcon.io/companies/1',
    10.     'php://memory',
    11.     [
    12.         'Authorization' => 'Bearer ' . $jwtToken,
    13.         'Content-Type'  => 'application/json',
    14.     ]
    15. );
    17. echo $request->getProtocolVersion(); // '1.1'

    getRequestTarget()

    Returns a string representing the message’s request-target either as it will appear (for clients), as it appeared at request (for servers), or as it was specified for the instance (see withRequestTarget()). In most cases, this will be the origin-form of the composed URI, unless a value was provided to the concrete implementation (see withRequestTarget()).

    1. <?php
    3. use Phalcon\Http\Message\Request;
    5. $request = new Request();
    6. $request = $request->withRequestTarget('/test');
    8. echo $request->getRequestTarget(); // '/test'

    getUri()

    Returns the Uri as a UriInterface object

    1. <?php
    3. use Phalcon\Http\Message\Request;
    5. $jwtToken = 'abc.def.ghi';
    7. $request = new Request(
    8.     'POST',
    9.     'https://api.phalcon.io/companies/1',
    10.     'php://memory',
    11.     [
    12.         'Authorization' => 'Bearer ' . $jwtToken,
    13.         'Content-Type'  => 'application/json',
    14.     ]
    15. );
    17. echo $request->getUri(); // UriInterface : https://api.phalcon.io/companies/1

    hasHeader()

    1. <?php
    3. use Phalcon\Http\Message\Request;
    5. $jwtToken = 'abc.def.ghi';
    7. $request = new Request(
    8.     'POST',
    9.     'https://api.phalcon.io/companies/1',
    10.     'php://memory',
    11.     [
    12.         'Authorization' => 'Bearer ' . $jwtToken,
    13.         'Content-Type'  => [
    14.             'application/json',
    15.             'application/html',
    16.         ],
    17.     ]
    18. );
    20. echo $request->hasHeader('content-type'); // true

    The Request object is immutable. However there are a number of methods that allow you to inject data into it. The returned object is a clone of the original one.

    withAddedHeader()

    Returns an instance with an additional header appended with the given value. Existing values for the specified header will be maintained. The new value(s) will be appended to the existing list. If the header did not exist previously, it will be added. Throws for invalid header names or values. The header values can be a string or an array of strings.

    Returns an instance with the specified message body which implements StreamInterface. Throws InvalidArgumentException when the body is not valid.

    1. <?php
    3. use Phalcon\Http\Message\Request;
    4. use Phalcon\Http\Message\Stream;
    6. $jwtToken = 'abc.def.ghi';
    7. $fileName = dataFolder('/assets/stream/mit.txt');
    8. $stream   = new Stream($fileName, 'rb');
    10. $request = new Request(
    11.     'POST',
    12.     'https://api.phalcon.io/companies/1',
    13.     'php://memory',
    14.     [
    15.         'Authorization' => 'Bearer ' . $jwtToken,
    16.         'Content-Type'  => 'application/json',
    17.     ]
    18. );
    20. $clone = $request->withBody($stream);
    22. echo $clone->getBody(); // '/assets/stream/mit.txt'

    withHeader()

    Returns an instance with the provided value replacing the specified header. While header names are case-insensitive, the casing of the header will be preserved by this function, and returned from getHeaders(). Throws InvalidArgumentException for invalid header names or values.

    1. <?php
    3. use Phalcon\Http\Message\Request;
    5. $jwtToken = 'abc.def.ghi';
    7. $request = new Request(
    8.     'POST',
    9.     'https://api.phalcon.io/companies/1',
    10.     [
    11.         'Authorization' => 'Bearer ' . $jwtToken,
    12.     ]
    15. var_dump(
    16.     $request->getHeaders()
    17. );
    18. // [
    19. //     'Authorization' => 'Bearer abc.def.ghi',
    20. // ]
    22. $clone = $request->withAddedHeader(
    23.     'Content-Type',
    24.     [
    25.         'application/html',
    26.     ]
    27. );
    29. var_dump(
    30.     $clone->getHeaders()
    31. );
    32. // [
    33. //     'Authorization' => 'Bearer abc.def.ghi',
    34. //     'Content-Type'  => [
    35. //         'application/html',
    36. //     ],
    37. // ]

    withMethod()

    Return an instance with the provided HTTP method as a string. Throws InvalidArgumentException for invalid HTTP methods.

    1. <?php
    3. use Phalcon\Http\Message\Request;
    5. $jwtToken = 'abc.def.ghi';
    7. $request = new Request(
    8.     'POST',
    9.     'https://api.phalcon.io/companies/1',
    10.     'php://memory',
    11.     [
    12.         'Authorization' => 'Bearer ' . $jwtToken,
    13.         'Content-Type'  => 'application/json',
    14.     ]
    15. );
    17. echo $request->getMethod(); // POST
    19. $clone = $request->withMethod('GET');
    21. echo $clone->getMethod(); // GET

    withProtocolVersion()

    Returns an instance with the specified HTTP protocol version (as string).

    1. <?php
    3. use Phalcon\Http\Message\Request;
    5. $request  = new Request();
    7. echo $request->getProtocolVersion(); // '1.1'
    9. $clone = $request->withProtocolVersion('2.0');
    11. echo $clone->getProtocolVersion(); // '2.0'

    withRequestTarget()

    Returns an instance with the specific request-target.

    1. <?php
    3. use Phalcon\Http\Message\Request;
    5. $request = new Request();
    7. echo $request->getRequestTarget(); // "/"
    9. $clone = $request->withRequestTarget('/test');
    11. echo $clone->getRequestTarget(); // '/test'

    Returns an instance with the provided UriInterface URI. This method updates the Host header of the returned request by default if the URI contains a host component. If the URI does not contain a host component, any pre-existing Host header will be carried over to the returned request.

    • If the Host header is missing or empty, and the new URI contains a host component, this method will update the Host header in the returned request.
    • If the Host header is missing or empty, and the new URI does not contain a host component, this method will not update the Host header in the returned request.
    • If a Host header is present and non-empty, this method will not update the Host header in the returned request.

    withoutHeader()

    Return an instance without the specified header.

    1. <?php
    3. use Phalcon\Http\Message\Request;
    5. $jwtToken = 'abc.def.ghi';
    7. $request = new Request(
    8.     'POST',
    9.     'https://api.phalcon.io/companies/1',
    10.     'php://memory',
    11.     [
    12.         'Authorization' => 'Bearer ' . $jwtToken,
    13.         'Content-Type'  => [
    14.             'application/json',
    15.         ],
    16.     ]
    17. );
    19. var_dump(
    20.     $request->getHeaders()
    21. );
    22. // [
    23. //     'Authorization' => 'Bearer abc.def.ghi',
    24. //     'Content-Type'  => [
    25. //         'application/json',
    26. //     ],
    27. // ]
    29. $clone = $request->withoutHeader('Content-Type');
    31. var_dump(
    32.     $clone->getHeaders()
    33. );
    34. // [