cUri & cUriBuilder

CONTENIDO offers a package of helper classes to work with URIs.

cUri

The cUri class allows to create and parse frontend URIs i.e. URIs to CONTENIDO articles and categories. By default these URIs look like front_content.php?lang=<lang>&idart=<idart>. The cUri allows for totally different URIs e.g. SEO-URIs that contain names of categories and articles instead of the strange looking URI mentioned above. In order to create these URIs independant of the chosen strategy for URI creation it is a good idea to use the cUri class whose functionality will be explained in this article.

Building an URI

The easiest way to build an URI to an arbitrary article is as follows:

$param['idart'] = $idart;
$param['lang'] = $lang;
$url = cUri::getInstance()->build($param);

The called build()-method expects an associative array wich has to have at least a value for the key 'lang' but any parameter can be appended. If another builder than cUriBuilderFrontcontent is used (see below) further keys may be required.

You can give the data as a default URI too. In this case the given URI is parsed (see below) before building it according to the defined builder.

$url = "front_content.php?idart=$idart&lang=$lang";
$url = cUri::getInstance()->build($url);

$url = cUri::getInstance()->build(array(
    'lang' => cRegistry::getLanguageId(),
    'idart' => cRegistry::getArticleId()
));

Relative vs. absolute URIs

By default a relative URI is created but creation of an absolute URI can be forced with a second argument set to true:

$absolute = true;
$url = cUri::getInstance()->build($param, $absolute);

Instead of using this second argument you can use a wrapper method called buildRedirect() which does the same.

Using different configuration

How the URI will be created can be configured in detail. If you want to overwrite this configuration for the creation of a single URI you can pass a third argument:

$config = array();
$url = cUri::getInstance()->build($param, $absolute, $config);

Which options this configuration array may contain will be explained later.

Building an URI by components

Parse an URI

The cUri class also offers a parse() method which allows for splitting any URI (n.b. not only CONTENIDO URIs) into its components (thats what the PHP function parse_url does) which is extended by the key 'params' that contains name, value pairs for each parameter of the given URI.

$components = cUri::getInstance()->parse($url);

A parsed URI can be rebuild using the method composeByComponents().

$url = cUri::getInstance()->composeByComponents($components);

Examine an URI

The method isExternalUrl() allow to examine any URI for being an external URI.

The method isIdentifiableFrontContentUrl() allow to examine any URI for being an internal URI. Following URLs will be identified as an internal URL:

• "/", "/?idart=123", "/?idcat=123", ...
• "front_content.php", "front_content.php?idart=123", "front_content.php?idcat=123", ...
• "/front_content.php", "/front_content.php?idart=123", "/front_content.php?idcat=123", ...
• The path component of an client HTML base path: e. g. "/cms/", "/cms/?idart=123", "/cms/?idcat=123"
• Also possible: "/cms/front_content.php", "/cms/front_content.php?idart=123", "/cms/front_content.php?idcat=123"

All of them prefixed with protocol and client host (e. g. http://host/) will also be identified as a internal URL.

Other URLs, even internal URLs like /unknown/path/to/some/page.html will not be identified as internal URL event if they are real working clean URLs.

Retrieve current builder

The builder that is currently configured can be retrieved like that:

$builder = cUri::getInstance()->getUriBuilder();

cUriBuilderFactory, cUriBuilder & cUriBuilderConfig

The builder defines how URIs look like and implements their creation. CONTENIDO comes with a couple of predefined builder classes but other classes can be implemented to suite your needs. As the class cUriBuilderFactory is a factory allowing to create builder instances all builder classes have to follow the common CONTENIDO naming scheme for classes and their filenames. Furthermore all builder classes should be implemented as singletons. N.b. usually there is no need to use a builder instance directly as the cUri class acts like a facade for it.

HTTP base path

All builder classes hav a member to hold the URL that is used as base for an absolute path (see above), e.g. 'http://contenido.org/'. The abstract class cUriBuilder offers a getter and a setter for this member.

URL

Builders allow to build an URI using the abstract public function buildUrl(). In order to retrieve the built URI the method getUrl() has to be used.

cUriBuilderFrontcontent::getInstance()->buildUrl($param, $absolute);
$url = cUriBuilderFrontcontent::getInstance()->getUrl();

Configuration

Configure cUriBuilder URL style. Per default, configures for style index-a-1.html. If you need another style, extend this class to your needs and pass it to desired cUriBuilder. The cUriBuilderConfig::setConfig() must be called at least once to initialize the desired UriBuilder.

$myCfg['name'] = 'front_content';
$myCfg['config'] = array();
cUriBuilderConfig::setConfig($myCfg);

$myCfg['name'] = 'custom_path';
$myCfg['config'] = array(
	'prefix' => 'rocknroll',
	'suffix' => '.4fb',
	'separator' => ','
);
cUriBuilderConfig::setConfig($myCfg);