URIs - PhpGt/WebEngine GitHub Wiki

A URI (Universal Resource Identifier) is a sequence of characters that identify the World Wide Web request being made. Sometimes referred to as a URL (Universal Resource Locator) or URN (Universal Resource Name), with extremely subtle differences, we shall use the term URI for consistency with PHP's internal naming conventions.

Parts of a URI

A simple URI https://www.example.com/colour/red is made up of the following parts:

  • https - the URI scheme / protocol being used to make the request
  • www.example.com - the host (otherwise referred to as the hostname)
  • /colour/red - the path

A complex URI https://henry:[email protected]:8301/colour/red?sort=price&filter=new#options is made up of the following parts:

  • https - the URI scheme / protocol being used to make the request
  • henry:s3cr3t - the user info
  • www.example.com - the host (otherwise referred to as the hostname)
  • 8301 - the port
  • /colour/red - the path
  • sort=price&filter=new - the query or querystring
  • options - the fragment

Throughout PHP.Gt, wherever a URI is referenced, an object that implements PSR-7's UriInterface is used. From within WebEngine Page Logic, the current URI can be obtained with $this->server->getRequestUri(). This allows the use of the following PSR-7 functions:

  • getScheme() The trailing ":" character is not part of the scheme
  • getAuthority() [user-info@]host[:port]
  • getUserInfo() The trailing "@" character is not part of the user information
  • getHost() The value returned MUST be normalized to lowercase
  • getPort() The integer port number in the URI, or default for the specified scheme
  • getPath() The absolute requested path
  • getQuery() The leading "?" character is not part of the query
  • getFragment() The leading "#" character is not part of the fragment

Routing a URI to an application page view and logic

In WebEngine, dynamic responses are built using a Page View (HTML) and Page Logic (PHP).

A common technique to match incoming requests with the correct areas of code is to use a concept called "routing". While there is a Router within WebEngine, it's handled for you automatically, so you don't need to write extra logic to "load" your code or link the request to the correct HTML source, for instance.

In WebEngine applications, routing is done by following a naming convention: the URI path that is requested is used to identify which page view and logic to load. For example, a request to https://www.example.com/about has a URI path of /about, which means that the HTML source for the request will be defined in your application source page/about.html, and the optional page logic will be defined in page/about.php.

Having a separate view file for every possible request will only get you so far. When necessary, it is possible to use dynamic URIs and pages to break out parts of the path into variables that can be read by PHP.

Continue reading about Page view and Page logic, and how further repetition can be removed by utilising DOM templates and Headers and footers

Accessing the current URI in a WebEngine application

In WebEngine applications, all superglobals are protected, which means the $_SERVER superglobal is not available. Instead, the values of $_SERVER are exposed through the Server class (part of PHP.Gt/Http) and encapsulated within your Page Logic.

From within any Page Logic class, you can obtain the current requested URI using the getRequestUri() function of the Server object, as follows:

function go() {
	$uri = $this->server->getRequestUri();
	$host = $uri->getHost();
	$path = $uri->getPath();

	$this->doSomethingWithUriParts($host, $path);
}