Download the PHP package vinogradsoft/navigator without Composer

[](https://codecov.io/gh/vinogradsoft/navigator)

What is Navigator?

👉 Navigator is a url generator. Works with internal application navigation and is able to generate URLs to external resources. Internal navigation is based on named route definitions. Named routes allow you to conveniently create URLs without being tied to a domain or route definition.

General Information

The library is intended for applications that use the FastRoute router in their code. FastRoute uses regular expression route definitions, and Navigator creates URLs that match those route definitions.

For code consistency, route definitions are assigned names.

This allows URLs to be manipulated without making changes to existing code. For example, to create a URL for a named definition 'user' => '/user/{id:\d+}', you could use the following code:

If for any reason you need to change the address from /user/100 to /employee/100, you will simply need to change the route setting from '/user/{id:\d+}' to '/employee/{id:\d+}'. The code above will then create the relative URL /employee/100 and the absolute URL http://mydomain.ru/employee/100.

The Navigator\UrlBuilder class object has two methods for generating URLs: build and buildExternal. The build method is used for navigation within the application, and buildExternal creates URLs for external resources and can only generate absolute URLs.

Install

To install with composer:

Requires PHP 8.0 or newer.

🚀 Quick Start

Constructor

The constructor has six parameters, perhaps the most important are the first two. The first parameter is $baseUrl - in this example its value is 'https://vinograd.soft' - this is the base URL, which is used to generate absolute URLs within the application.

The second parameter $rulesProvider accepts an implementation instance of the Navigator\RulesProvider interface. The example uses the Navigator\ArrayRulesProvider implementation, which operates on a regular array of registered routes. It is essentially a source of named route definitions.

Parameters Of The build(...) Method

Parameter $name

With the $name parameter you pass the name of the route. Based on the value of this parameter, the system understands which definition it is working with and converts it into a URL. The example uses two cases 'user' and '/user'. It is worth noting that the “/” character at the beginning of the transmitted name does not affect the route search in any way; it indicates to the system that this character should be included at the beginning of the generated URL. The system recognizes this symbol and then searches for the route by name, excluding this symbol from it. The “/” is then used by the system as an indicator that it should be included at the beginning of the relative URL being generated.

Parameter $placeholders

Can be array of placeholder settings or null.

Array Of Placeholder Settings

From the example, $urlBuilder works with the route definition '/user[/{var_name}]', where var_name is the dynamic part, in other words a variable.

We passed the following array to the build method ['var_name' => 'var_value'], where 'var_name' is a variable from the route definition, and 'var_value' is its value, i.e. then what 'var_name' will be replaced with as a result, in our case the result for the absolute URL is https://vinograd.soft/user/var_value.

NULL

NULL is used in cases of generating static URLs that do not need settings in the path directories, such as this definition 'user' => '/user'.

Example:

$absolute parameter

This Boolean parameter tells the system whether to create an absolute or relative URL. Passing true will create an absolute address, otherwise a relative address will be created. The default value is false.

Route Configuration

Definition names do not have a rigid format, so what names you give is up to you. You can use the format <controller>/<action> example: post/view. Or add the name of the module blog/post/view to the beginning.

It is important to remember one thing: the first character cannot be /. This name is not correct /blog/post/view when the URL is generated by the build method, a route with this name will not be found, since the system will look for it without the / character at the beginning, then a Navigator\RoutConfigurationException will be thrown.

Example of a correct route name:

Example of an ILLEGAL route name:

The / symbol is not required in names; the name can be blog.post.view or something else that has no delimiters at all.

You can read how to create routes in the documentation for the FastRoute library.

Placeholders

The scheme shows which placeholder is responsible for which part of the URL

Not all placeholders are available for both generation methods. The table below shows the availability of each placeholder and the data type of the value.

⚡ Examples Of Using Placeholders

First, let's configure $urlBuilder this way:

👉 Variable Name From Definition

Optional parameters in definitions not enclosed in curly braces have a placeholder type of bool.

Example 1.

The "about" page has a suffix in its definition - an optional parameter .html without curly braces. You need to generate a URL with this suffix.

Example 2.

Generate an absolute URL using the optional placeholder to specify 'user' => '/user[/{var_name}]'.

Example 3.

You need to generate a relative URL with a leading / to define 'user' => '/user[/{var_name}]'.

Example 4.

Create a relative URL without the leading / to define 'user' => '/user[/{var_name}]'.

Example 5.

The definition 'user' => '/user[/{var_name}]' has an optional parameter var_name. You need to generate an absolute URL without this parameter.

👉 :src

Example 1.

The application has a variable that contains the URL of an external resource. There are a few changes you need to make to the URL:

• change its scheme from http to ftp
• add username grigor and password password123
• change port to 21.

Example 2.

Add the path blog/post/41 to the other site's homepage URL http://another.site.

👉 :scheme

Example 1.

Change the URL scheme of http://another.site from http to https.

Example 2.

Create a URL https://another.site/path/to/resource from the parts available in the application with the scheme https.

👉 :user

Example.

Add the username user for the URL http://another.site.

👉 :password

This placeholder only works when paired with the :user placeholder. The :user part either must be present in the original URL passed in the :src placeholder, or must be passed in pairs with the :password placeholder; if :user is not present in the URL, a Navigator\BadParameterException will be thrown.

Example.

Add the username grigor and password password123 for the URL ftp://another.site:21.

👉 :host

The :host placeholder is used in conjunction with the :scheme placeholder. In the case where you do not use the :src placeholder and want to create a URL from parts, then :host and ':scheme' will be required; if either of them is missing, a Navigator\BadParameterException will be thrown. :host is the only placeholder that does not override its portion of the URL with the passed :src placeholder.

Example.

You need to create the URL http://another.site.

👉 :port

Example.

Create a URL http://another.site with port 5000.

👉 :path

Example 1.

You need to create a URL https://another.site/path/to using a placeholder value of type array.

Example 2.

Generate the URL https://another.site/path/to using a placeholder value of type string.

👉 :suffix

There is one caveat with suffixes, if you pass a URL with a suffix using the :src placeholder, you cannot override it with the :suffix placeholder, you can only add it, since the suffix can be any string, it is not parsed and will be part of the path.

Example 1.

Add a .html extension to the https://another.site/path/to URL.

Example 2.

Add the suffix -city to the URL https://another.site/path/to?q=value#news.

👉 Placeholder ?

Example 1.

Add the s parameter with the value Hello world to the https://another.site URL.

Example 2.

The system has a prepared parameter s=Hello world, you need to add it to the URL https://another.site.

Example 3.

You need to create a URL to link to the search results of another site https://another.site with the following parameters:

Code:

👉 Placeholder #

Example 1.

The task is to generate an address for a link to the documentation of the vinogradsoft/compass library, quick start paragraph.

👉 :strategy

To use URL generation strategies, you must either implement the Compass\UrlStrategy interface or inherit from the Compass\DefaultUrlStrategy class. More details about the principles of operation of strategies can be found in the documentation for the Compass library.

Example 1.

The task is to create a strategy for generating referral link URLs with the refid parameter equal to 222.

Strategy code:

Let's add a strategy to the $urlBuilder constructor:

Generating the URL:

Example 2.

Let's take the strategy from Example 1 of this paragraph and make it the default strategy for generating external URLs.

Let's replace the strategy in the instance of the Compass\Url class and pass it to the constructor of our $urlBuilder with the fifth parameter ($externalUrl):

Generating the URL:

👉 :idn

Example 1.

The task is to convert the URL https://россия.рф into panycode.

Testing

Contributing

Please see CONTRIBUTING for details.

License

The MIT License (MIT). Please see License File for more information.