URLs and Links

This page is about the functions to read and write URLs.

Table of contents

• URL structure
• Building URLs based on a file
• Building custom URLs
• Page suffix
• Reading URLs

URL structure

Because of SEO reasons, a URL should not have more than three hierarchies. So Kiwa handles three parts:

• The first hierarchy. This URL fragment is called page.
• The second hierarchy. This URL fragment is called subpage.
• Additionally, there can be set a language code. This URL fragment is called languageCode.

So imagine the URL https://www.example.org/en-gb/contact/imprint.html. The parts here are

This naming is important to know when creating custom URLs.

Building URLs based on a file

The easiest way to build a URL is by using the URLFromFile class.

If you want to create a link to your contact page, this page may be defined in your config like that:

<?php

use Kiwa\Config\Generator\PageGenerator;
use Kiwa\Config\Generator\ConfigGenerator;

$config = new ConfigGenerator();
$config
    ->setMainURL('https://www.example.org')
    ->setURLStructure('languageCode', 'name', 'subname')
    ->setPageSuffix('html')
    ->addPage(PageGenerator::create()
        ->setName('contact-us-now')
        ->setFile('contact-file')
        ->setLanguageCode('en')
    )
;

Here we have a page named contact-us-now, which uses the file contact-file.phtml.

Now we can create a URL by writing echo new URLFromFile('contact-file') and will receive: /en/contact-us-now.html.

Building custom URLs

Sometimes there is no phtml to link with (for example, when using an asset), or a URL may have parts coming from variables. In this case, there can be used the URLBuilder class.

<?php

use Kiwa\URL\URLBuilder;

echo new URLBuilder([
    'languageCode' => 'en',
    'name' => 'contact',
    'subname' => 'imprint'
]);

Taken the config from our example above, the output will be: /en/contact/imprint.html. If the config changes the URL fragments, all URLs will also change and be valid.

The URLBuilder can link to assets too:

<?php

use Kiwa\URL\URLBuilder;

/** This will print `/build/images/hello.jpg` */
echo new URLBuilder(['build/images/hello.jpg']);

Adding a second parameter and setting it to false will result in an absolute URL:

<?php

use Kiwa\URL\URLBuilder;

/** This will print `https://www.example.org/build/images/hello.jpg` */
echo new URLBuilder(['build/images/hello.jpg'], false);

If Kiwa detects a manifest.json inside /public/build and there is a versioned file, it will print the versioned URL:

<?php

use Kiwa\URL\URLBuilder;

/** This will print `/build/template.b678fce1.css` */
echo new URLBuilder(['build/template.css']);

/** This will print `https://www.example.org/build/template.b678fce1.css` */
echo new URLBuilder(['build/template.css'], false);

Page suffix

Kiwa may handle page URLs without a suffix or with a suffix like .htm, .html or .php. You can define this setting in your config.php:

<?php

use Kiwa\Config\Generator\ConfigGenerator;

$config = new ConfigGenerator();

/** This disables a suffix. */
$config->setPageSuffix(false);

/** Sets the suffix to `.html`. */
$config->setPageSuffix('html');

Reading URLs

Want to know which current URL parts your request has? Use the URLFragment class.