View Helper - URL¶
The URL view helper is used to create a string representation of the routes that you define within
your application. The syntax for the view helper is $this->url($name, $params, $options,
$reuseMatchedParameters)
, using the following definitions for the helper arguments:
$name
: The name of the route you want to output.$params
: An array of parameters that is defined within the respective route configuration.$options
: An array of options that will be used to create the URL.$reuseMatchedParams
: A flag indicating if the currently matched route parameters should be used when generating the new URL.
Let’s take a look at how this view helper is used in real-world applications.
Basic Usage¶
The following example shows a simple configuration for a news module. The route is called news
and it has two optional parameters called action
and id
.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 | // In a configuration array (e.g. returned by some module's module.config.php)
'router' => array(
'routes' => array(
'news' => array(
'type' => 'segment',
'options' => array(
'route' => '/news[/:action][/:id]',
'constraints' => array(
'action' => '[a-zA-Z][a-zA-Z0-9_-]*',
),
'defaults' => array(
'controller' => 'news',
'action' => 'index',
),
)
)
)
),
|
First, let’s use the view helper to create the output for the URL /news
without any of the
optional parameters being used:
1 | <a href="<?php echo $this->url('news'); ?>">News Index</a>
|
This will render the output:
1 | <a href="/news">News Index</a>
|
Now let’s assume we want to get a link to display the detail page of a single news entry. For this
task, the optional parameters action
and id
need to have values assigned. This is how you do
it:
1 2 3 | <a href="<?php echo $this->url('news', array('action' => 'details', 'id' =>42)); ?>">
Details of News #42
</a>
|
This will render the output:
1 | <a href="/news/details/42">News Index</a>
|
Query String Arguments¶
Most SEO experts agree that pagination parameters should not be part of the URL path; for example,
the following URL would be considered a bad practice: /news/archive/page/13
. Pagination is more
correctly accomplished using a query string arguments, such as /news/archive?page=13
. To achieve
this, you’ll need to make use of the $options
argument from the view helper.
We will use the same route configuration as defined above:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 | // In a configuration array (e.g. returned by some module's module.config.php)
'router' => array(
'routes' => array(
'news' => array(
'type' => 'segment',
'options' => array(
'route' => '/news[/:action][/:id]',
'constraints' => array(
'action' => '[a-zA-Z][a-zA-Z0-9_-]*',
),
'defaults' => array(
'controller' => 'news',
'action' => 'index',
),
)
)
)
),
|
To generate query string arguments from the view helper, you need to assign them as the third
argument using the query
key like this:
1 2 3 4 5 6 7 8 9 10 11 12 | <?php
$url = $this->url(
'news',
array('action' => 'archive'),
array(
'query' => array(
'page' => 13,
).
)
);
?>
<a href="<?php echo $url; ?>">News Archive Page #13</a>
|
The above code sample would output:
1 | <a href="/news/archive?page=13">News Archive Page #13</a>
|
Fragments¶
Another possible entry within the $options
array is the assignment of URL fragments (typically
used to link to in-page anchors), denoted with using the fragment
key. Let’s assume we want to
enter a link for users to directly jump to the comment section of a details page:
1 2 3 4 5 6 7 8 9 10 | <?php
$url = $this->url(
'news',
array('action' => 'details', 'id' => 42),
array(
'fragment' => 'comments',
)
);
?>
<a href="<?php echo $url; ?>">Comment Section of News #42</a>
|
The above code sample would output:
1 | <a href="/news/details/42#comments">Comment Section of News #42</a>
|
You can use fragment
and query
options at the same time!
1 2 3 4 5 6 7 8 9 10 11 12 13 | <?php
$url = $this->url(
'news',
array('action' => 'details', 'id' => 42),
array(
'query' => array(
'commentPage' => 3,
),
'fragment' => 'comments',
)
);
?>
<a href="<?php echo $url; ?>">Comment Section of News #42</a>
|
The above code sample would output:
1 | <a href="/news/details/42?commentPage=3#comments">Comment Section of News #42</a>
|
Fully Qualified Domain Name¶
Another possible entry within the $options
array is to output a fully qualified domain name (absolute URL), denoted using the force_canonical
key:
1 2 3 4 5 6 7 8 9 10 | <?php
$url = $this->url(
'news',
array(),
array(
'force_canonical' => true,
)
);
?>
<a href="<?php echo $url; ?>">News Index</a>
|
The above code sample would output:
1 | <a href="http://www.example.com/news">News Index</a>
|
Reusing Matched Parameters¶
When you’re on a route that has many parameters, often times it makes sense to reuse currently
matched parameters instead of assigning them new explicitly. In this case, the argument
$reuseMatchedParams
will come in handy.
As an example, we will imagine being on a detail page for our “news” route. We want to display links
to the èdit
and delete
actions without having to assign the ID again. This is how you would
do it:
1 2 3 4 | // Currently url /news/details/777
<a href="<?php echo $this->url('news', array('action' => 'edit'), null, true); ?>">Edit Me</a>
<a href="<?php echo $this->url('news', array('action' => 'delete'), null, true); ?>">Delete Me</a>
|
Notice the true
argument in the fourth position. This tells the view helper to use the matched
id
(777
) when creating the new URL:
1 2 | <a href="/news/edit/777">Edit Me</a>
<a href="/news/delete/777">Edit Me</a>
|
Shorthand¶
Due to the fact that reusing parameters is a use case that can happen when no route options are set,
the third argument for the URL view helper will be checked against its type; when a boolean is
passed, the helper uses it to set the value of the $reuseMatchedParams
flag:
1 2 3 | $this->url('news', array('action' => 'archive'), null, true);
// is equal to
$this->url('news', array('action' => 'archive'), true);
|