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.com/en-gb/contact/imprint.html
. The parts here are
Part | Name |
---|---|
https://www.example.com |
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.
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.