URLs and Links

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

Table of contents

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

Part Name
https://www.example.org The main URL
en-gb Fragment languageCode
contact Fragment name
imprint (.html) Fragment subname

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.

Please note that the URLBuilder may create URLs to pages not existing.

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.