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 URLs based on a page object
• 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:

<?php

use Kiwa\URL\URLFromFile;

/** This will print `/en/contact-us-now.html` */
echo new URLFromFile('contact-file');

Per default, Kiwa generates relative URLs. You can change that by providing a second argument setting this behaviour to false:

<?php

use Kiwa\URL\URLFromFile;

/** This will print `https://www.example.org/en/contact-us-now.html` */
echo new URLFromFile('contact-file', false);

Building URLs based on a page object

When having a Page object, it is possible to create a URL directly out of it using the URLFromPage class.

<?php

use Kiwa\URL\URLFromPage;

/** This will create a relative url */
echo new URLFromPage($page);

/** This will create an absolute url */
echo new URLFromPage($page, false);

Page objects can be received from the PageList class. You can find out more about how to use it under the section page handling.

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.