Download the PHP package mimmi20/mezzio-navigation without Composer

mezzio-navigation

Code Status

Introduction

This component provides a component for managing trees of pointers to web pages. Simply put: It can be used for creating menus, breadcrumbs, links, and sitemaps, or serve as a model for other navigation related purposes.

Unlike in laminas-navigation this library provides a middleware which is required to prepare the navigation.

Installation

You can install the mezzio-navigation library with Composer:

Pages and Containers

There are two main concepts in mezzio-navigation: pages and containers.

Pages

A page in mezzio-navigation, in its most basic form, is an object that holds a pointer to a web page. In addition to the pointer itself, the page object contains a number of other properties that are typically relevant for navigation, such as label, title, etc.

Read more about pages in the pages section.

Containers

A navigation container holds pages. It has methods for adding, retrieving, deleting and iterating pages. It implements the SPL interfaces RecursiveIterator and Countable, and can thus be iterated with SPL iterators such as RecursiveIteratorIterator.

Read more about containers in the containers section.

Pages are containers

Mezzio\Navigation\PageInterface extends Mezzio\Navigation\ContainerInterface, which means that a page can have sub pages.

View Helpers

Separation of data (model) and rendering (view)

Classes in the mezzio-navigation namespace do not deal with rendering of navigational elements. Rendering is done with navigational view helpers. However, pages contain information that is used by view helpers when rendering, such as label, class (CSS), title, lastmod, and priority properties for sitemaps, etc.

We provide one rendering libary.

• The Renderer using Laminas View is provided by mezzio-navigation-laminasviewrenderer.

The renderer is installable via Composer:

Containers

Containers have methods for adding, retrieving, deleting, and iterating pages. Containers implement the SPL interfaces RecursiveIterator and Countable, meaning that a container can be iterated using the SPL RecursiveIteratorIterator class.

Creating containers

Mezzio\Navigation\ContainerInterface can not be instantiated directly. Use Mezzio\Navigation\Navigation if you want to instantiate a container.

Mezzio\Navigation\Navigation can be constructed entirely empty, or take an array or a Traversable object with pages to put in the container. Each page provided via options will eventually be passed to the addPage() method of the container class, which means that each element in the options can be also be an array, Traversable object, or a Mezzio\Navigation\Page\PageInterface instance.

Creating a container using an array

Unlike in Laminas Navigation it is not possible to add an arrray config to Mezzio Navigation directly. Converting an array config into a list of Page objects is made in the Navigation Factories.

Adding pages

Adding pages to a container can be done with the methods addPage(), addPages(), or setPages(). See examples below for explanation.

Unlike in Laminas Navigation only objects implementing the PageInterface are allowed. The PageFactory may be used to use an array config.

Removing pages

Removing pages can be done with removePage() or removePages(). removePage() accepts an instance of a page or an integer. Integer arguments correspond to the order a page has. removePages() will remove all pages in the container.

Remove a page recursively

Removing a page recursively can be done with the second parameter of the removePage() method, which expects a boolean value.

Finding pages

Containers have two finder methods for retrieving pages. Each recursively searches the container testing for properties with values that match the one provided.

• findOneBy($property, $value) : PageInterface|null: Returns the first page found matching the criteria, or null if none was found.
• findAllBy($property, $value) : array<PageInterface>: Returns an array of all page instances matching the criteria.

Unlike in Laminas Navigation the findBy is not available.

The finder methods can also be used magically by appending the property name to findBy, findOneBy, or findAllBy. As an example, findOneByLabel('Home') will return the first matching page with label 'Home'.

Other combinations include findByLabel(...), findOneByTitle(...), findAllByController(...), etc. Finder methods also work on custom properties, such as findByFoo('bar').

Iterating containers

Mezzio\Navigation\ContainerInterface extends RecursiveIterator. iterate a container recursively, use the RecursiveIteratorIterator class.

Other operations

hasPage

Check if the container has the given page.

hasPages

Checks if there are any pages in the container, and is equivalent to count($container) > 0.

toArray

Converts the container and the pages in it to a (nested) array. This can be useful for serializing and debugging.

Pages

mezzio-navigation ships with two page types:

• Route pages, using the class Mezzio\Navigation\Page\Route
• URI pages, using the class Mezzio\Navigation\Page\Uri

Route pages link to on-site web pages, and are defined using Route parameters (route, params). URI pages are defined by a single property uri, which give you the full flexibility to link off-site pages or do other things with the generated links (e.g. a URI that turns into <a href="#">foo<a>).

Route Pages replace the MVC Pages from Laminas Navigation.

Unlike in Laminas Navigation the options controller and action are not supported,

Common page features

All page classes must extend Mezzio\Navigation\Page\PageInterface, and will thus share a common set of features and properties. Most notably, they share the options in the table below and the same initialization process.

Option keys are mapped to set*() methods. This means that the option order maps to the method setOrder(), and reset_params maps to the method setResetParams(). If there is no setter method for the option, it will be set as a custom property of the page.

Read more on extending Mezzio\Navigation\Page\PageInterface in the section "Creating custom page types".

Common page options

Custom properties

All pages support setting and retrieval of custom properties by use of the magic methods __set($name, $value), __get($name), __isset($name) and __unset($name). Custom properties may have any value, and will be included in the array that is returned from $page->toArray(), which means that pages can be serialized/deserialized successfully even if the pages contains properties that are not native in the page class.

Both native and custom properties can be set using $page->set($name, $value) and retrieved using $page->get($name), or by using magic methods.

The following example demonstrates custom properties:

Route pages

Routes can be used with Route pages. If a page has a route, this route will be used in getHref() to generate href attributes, and the isActive() method will compare the Mezzio\Router\RouteResult params with the page's params to determine if the page is active.

useRouteMatch flag

If you want to re-use any matched route parameters when generating a link, you can do so via the useRouteMatch flag. This is particularly useful when creating segment routes that include the currently selected language or locale as an initial segment, as it ensures the links generated all include the matched value.

Route page options

isActive() determines if page is active

This example demonstrates that Route pages determine whether they are active by using the params found in the route match object.

URI Pages

Pages of type Mezzio\Navigation\Page\Uri can be used to link to pages on other domains or sites, or to implement custom logic for the page. In addition to the common page options, a URI page takes only one additional option, a uri. The uri will be returned when calling $page->getHref(), and may be a string or null.

No auto-determination of active status

Mezzio\Navigation\Page\Uri will not try to determine whether it should be active when calling $page->isActive(); it merely returns what currently is set. In order to make a URI page active, you must manually call $page->setActive() or specify the active as a page option during instantiation.

URI page options

Creating custom page types

When implementing Mezzio\Navigation\Page\PageInterface and using the Mezzio\Navigation\Page\PageTrait, there is usually no need to override the constructor or the setOptions() method. The page constructor takes a single parameter, an iterable, which is then passed to setOptions(). That method will in turn call the appropriate set*() methods based on the options provided, which in turn maps the option to native or custom properties. If the option internal_id is given, the method will first look for a method named setInternalId(), and pass the option to this method if it exists. If the method does not exist, the option will be set as a custom property of the page, and be accessible via $internalId = $page->internal_id; or $internalId = $page->get('internal_id');.

Basic custom page example

The only thing a custom page class needs to implement is the getHref() method.

A custom page with properties

When adding properties to an extended page, there is no need to override/modify setOptions().

Creating pages using the page factory

All pages (also custom classes), can be created using the page factory, Mezzio\Navigation\Page\PageFactory. The factory accepts either an iterable set of options. Each key in the options corresponds to a page option, as seen earlier. If the option uri is given and no Route options are provided (route), a URI page will be created. If any of the Route options are given, an Route page will be created.

If type is given, the factory will assume the value to be the name of the class that should be created. If the value is route or uri, an Route or URI page will be created, respectively.

Creating an Route page using the page factory

Creating a URI page using the page factory

Creating a custom page type using the page factory

To create a custom page type using the factory, use the option type to specify a class name to instantiate.

Quick Start

Usage in a mezzio-based application

The fastest way to get up and running with mezzio-navigation is:

• Register mezzio-navigation or use the Component Installer.
• Add the Middleware to the Pipeline.
• Define navigation container configuration under the top-level navigation key in your application configuration.
• Render your container using a navigation view helper within your view scripts.

Register mezzio-navigation

Edit the application configuration file config/config.php:

Add the NavigationMiddleware to the pipeline

If you need the Navigation inside the Layout, and the Layout is used also for the Not-Found-Page, you have to add the Middleware in the Pipeline before the Routing.

Navigation container configuration

Add the container definition to your configuration file, e.g. config/autoload/global.php:

Render the navigation

Mezzio support multiple view renders.

One renderer is available:

• mezzio-navigation-laminasviewrenderer, which implements (Mezzios LaminasViewRenderer)

License

This package is licensed using the MIT License.

Please have a look at LICENSE.md.