URL Components
Introduction
The \BitFrame\Message\RequestTrait
provides a few useful methods to retrieve the URL endpoints as well as query string.
Request objects created via \BitFrame\Factory\HttpMessageFactory
(which is what's done internally in BitFrame by default) have the RequestTrait
class included by default.
For the examples on this page, let us assume we have the following:
use \Psr\Http\Message\ServerRequestInterface; use \BitFrame\Factory\HttpMessageFactory; $request = HttpMessageFactory::createServerRequest( 'GET', 'https://www.example.com/doc/v1/install?key1=value1&key2=value2' ); $app = new \BitFrame\Application([ ServerRequestInterface::class => $request ]);
Retrieving The Uri
Object
You can retrieve the instance of an object that implements \Psr\Http\Message\UriInterface
via the \Psr\Http\Message\RequestInterface
object instance like so:
// @see: https://github.com/php-fig/http-message/blob/master/src/UriInterface.php $app->getRequest()->getUri();
Retrieving The Endpoints
Endpoints can be retrieved using the following two methods on the request object using the \BitFrame\Message\RequestTrait
:
getEndpoints()
: get all endpoints.getEndpoint()
: get endpoint of interest.
Get All Endpoints As An Array:
$endpoints = $request->getEndpoints(); // output: [0 => 'doc', 1 => 'v1', 2 => 'install']
Get Endpoint Of Interest By Index
You can get an endpoint you're interested in by simply passing in the number/index of the endpoint in the url:
$request->getEndpoint(1); // 'doc' $request->getEndpoint(2); // 'v1' $request->getEndpoint(3); // 'install'
Note that 1 in index param means the first endpoint (as opposed to 0 used by array indexes).
If the specified 'index' is not found, an error is not raised, instead a default null
is returned, which can be used as a check, or alternatively, you can specify your own default value by passing in a second argument to the getEndpoint()
method, for example:
$request->getEndpoint(45, ''); // ''
Validating The Endpoints
There are two methods available on the request object using the \BitFrame\Message\RequestTrait
class to validate endpoints:
hasEndpoint()
: check if any part of specified endpoints match the url endpoints.isEndpoint()
: Check if the specified endpoint matches exactly to the one in the url.
Check If Part Of Endpoints Exist
You can check for a single endpoint like so:
$request->hasEndpoint('doc/'); // true $request->hasEndpoint('v1/'); // true $request->hasEndpoint('install/'); // true
You can check to see if endpoints appear together in the url, one after the other, like so:
$request->hasEndpoint('doc/v1/'); // true $request->hasEndpoint('doc/v1/install'); // true $request->hasEndpoint('v1/install'); // true $request->hasEndpoint('doc/install'); // false
You can specify endpoint(s) to match whilst making sure they always have the same base path like so:
// match single path: $request->hasEndpoint('v1/', 'doc/'); // true $request->hasEndpoint('install', 'v1/'); // true $request->hasEndpoint('install', 'doc/v1/'); // true $request->hasEndpoint('v1/install', 'doc/'); // true $request->hasEndpoint('doc/v1/install', ''); // true // match one of the specified multiple paths: $request->hasEndpoint(['install', 'quickstart'], 'v1/'); // true $request->hasEndpoint(['install', 'quickstart'], 'doc/v1/'); // true $request->hasEndpoint(['v1/install', 'quickstart'], 'doc/'); // true
Check If An Endpoint Matches Exactly
To check if an endpoint matches exactly means the entire path should match the specified path:
$request->hasEndpoint('doc/v1/install', '', true); // true $request->hasEndpoint('', 'doc/v1/install', true); // true $request->hasEndpoint('v1/install', 'doc/', true); // true // ... $request->hasEndpoint('doc/v1/', '', true); // false
The optional third argument to the hasEndpoint
method is a boolean flag to specify whether the match needs to be strict or not. By default this is set to false
, setting this to true
will match the entire path exactly. The isEndpoint
method is an alias for hasEndpoint
method with strict match on, which we can use like so:
$request->isEndpoint('doc/v1/install/'); // true $request->isEndpoint(['install/', 'quickstart'], 'doc/v1/'); // true $request->isEndpoint(['v1/install/', 'v1/quickstart'], 'doc/'); // true $request->isEndpoint('doc/v1/'); // false $request->isEndpoint('v1/install'); // false $request->isEndpoint(['install', 'quickstart'], 'v1/'); // false $request->isEndpoint('v1', 'doc/'); // false
Retrieving Query String Parameters
Query string params can be retrieved using the getQueryParams()
method on the request object instance. This method is a part of the \Psr\Http\Message\ServerRequestInterface
(which is a part of the PSR standard). In addition to this, the \BitFrame\Message\RequestTrait
provides a proprietary (non-standard) getQueryParam()
method to retrieve a single key/value pair from the query string.
Get All Query String Params As An Array
$q = $request->getQueryParams(); // output: ['key1' => 'val1', 'key2' => 'val2']
Get A Single Key/Value Pair From The Query String
You can get an query string parameter you're interested in by simply passing in the key of the parameter in the url query string:
$request->getQueryParam('key1'); // 'val1' $request->getQueryParam('key2'); // 'val2'
If the specified 'key' is not found, an error is not raised, instead a default null
is returned, which can be used as a check, or alternatively, you can specify your own default value by passing in a second argument to the getQueryParam()
method, for example:
$request->getQueryParam('nonExistentKey', ''); // ''