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:

1. getEndpoints(): get all endpoints.
2. 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:

1. hasEndpoint(): check if any part of specified endpoints match the url endpoints.
2. 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', ''); // ''