KO | EN

GitLite

Minimalist Open Source Repository Search Engine

gitlite — search

#dsh #dsh-plugin #ai-agents #developer-tools #typescript #codex #cli #claude-code #mcp #rust #deepseek-harness #ai-agent

Breadcrumbs

★ 12 Open GitHub ↗

PHP classes to implement a common breadcrumb navigation into a web application.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

naucon Breadcrumbs Package
==========================

About
-----

The breadcrumb package helps to integrate a common breadcrumb navigation into a web application. The package includes two components: A breadcrumbs class to add breadcrumb elements and a breadcrumbs helper to render html markup in php or smarty templates.

### Features

* add breadcrumbs with a title and a optional URL
* breadcrumb handler (null - default, session)
* breadcrumb helper to render html markup 
* smarty plugins for breadcrumb helper
* reverse breadcrumb (fifo, lifo)
* fluent interface
** Breadcrumbs (add)
** BreadcrumbsHelper (setTag, setSeparator, setReverse, setOptions)

### Compatibility

* PHP7.2+

### Dependencies

* naucon Utility
* naucon Html Elements

Installation
------------

install the latest version via composer

composer require naucon/breadcrumbs

Usage
-----

### initialize

To build a breadcrumb menu create a instance of `Breadcrumbs`.

use Naucon\Breadcrumbs\Breadcrumbs;
    $breadcrumbs = new Breadcrumbs();

Afterwards you can add breadcrumbs to that instance with the method `add()`. This the first parameter a title of the breadcrumb must be defined. With the second parameter a URL can be defined (optional).

$breadcrumbs->add('home', '/home/');
    $breadcrumbs->add('profile', '/profile/');
    $breadcrumbs->add('address');
    
Another way is with the fluent interface.

$breadcrumbs->add('home', '/home/');
        ->add('profile', '/profile/');
        ->add('address');

With `foreach` you can iterate through the added breadcrumbs. The value is a instance of `Breadcrumb` which have methodes to access breadcrumb title and URL. The breadcrumbs a in the order they are added (FIFO).

foreach ($breadcrumbs as $breadcrumb)
    {
        if ($breadcrumb->hasUrl()) {
            echo '<a href="' . $breadcrumb->getUrl() . '">' . $breadcrumb->getTitle() . '</a>';
        } else {
            echo $breadcrumb->getTitle();
        }
    }
    
The output of the example would be

<a href="/home/">home</a><a href="/profile/">profile</a>address

To reverse the order of the breadcrumb use the method `getReverseIterator()`. The breadcrumbs will be interated in the reverse order they are added (LIFO).

$breadcrumbsIterator = $breadcrumbs->getReverseIterator();
    foreach ($breadcrumbsIterator as $breadcrumb)
    {
        if ($breadcrumb->hasUrl()) {
            echo '<a href="' . $breadcrumb->getUrl() . '">' . $breadcrumb->getTitle() . '</a>';
        } else {
            echo $breadcrumb->getTitle();
        }
    }
    
The output of the example would be

address<a href="/profile/">profile</a><a href="/home/">home</a>

### Breadcrumb Handler

Breadcrumb items are collected in a instance of `BreadcrumbCollection`. To read and write into the collection a handler is used.
The default handler is `BreadcrumbHandlerNull` which only adds or remove entries to the collection.

In some use cases the breadcrumb entries must persist between page loads. In this cases the `BreadcrumbHandlerSession` can be set. The Handler will read and write into the $_SESSION variable.

// start session
    session_start();

...

use Naucon\Breadcrumbs\Breadcrumbs;
    use Naucon\Breadcrumbs\Handler\BreadcrumbHandlerSession;
    $breadcrumbs = new Breadcrumbs();
    $breadcrumbs->setBreadcrumbHandler(new BreadcrumbHandlerSession());
    
    ...
    
    // add breadcrumb entry
    $breadcrumbs->add('Home', '/home/');

...

// close session
    session_write_close();

Make sure that you started and close session befor and after you use the breadcrumb.

### Breadcrumb helper

With the breadcrumb helper a instance of `Breadcrumbs` can be rendered in HTML Markup.

To use the helper create a instance of `BreadcrumbsHelper` and give the constructor a instance of `Breadcrumbs`.

use Naucon\Breadcrumbs\Helper\BreadcrumbsHelper;
    $breadcrumbsHelper = new BreadcrumbsHelper($breadcrumbs);

With the method `render()` the html markup will be generated an returned.

echo $breadcrumbsHelper->render();

// <a href="/home/">home</a><a href="/profile/">profile</a>address

With the method `setSeparator()` a separator between the breadcrumbs can be defined.

$breadcrumbsHelper->setSeparator(' / ');
    echo $breadcrumbsHelper->render();

// <a href="/home/">home</a> / <a href="/profile/">profile</a> / address

With the method `setReverse()` the order of the breadcrumbs can be reversed.

$breadcrumbsHelper->setReversed(); // or $breadcrumbsHelper->setReversed(true);
    echo $breadcrumbsHelper->render();

// address / <a href="/profile/">profile</a> / <a href="/home/">home</a>

With the method `setSkipLinks()` links will be skipped in render.

$breadcrumbsHelper->setSkipLinks(); // or $breadcrumbsHelper->setSkipLinks(true);
    echo $breadcrumbsHelper->render();

// home / profile / home

With the method `setTag()` a html element can be set surround the breadcrumb. The following html element are supported: span, div, li, ul, ol

Example with `span` element:

$breadcrumbsHelper->setTag('span');
    $breadcrumbsHelper->setSeparator(' / ');
    echo $breadcrumbsHelper->render();
    
    // <span><a href="/home/">home</a></span> / <span><a href="/profile/">profile</a></span> / <span>address</span>

Example with `div` element:

$breadcrumbsHelper->setTag('div');
    $breadcrumbsHelper->setSeparator(' / ');
    echo $breadcrumbsHelper->render();
    
    // <div><a href="/home/">home</a></div> / <div><a href="/profile/">profile</a></div> / <div>address</div>

Example with `li` element:

$breadcrumbsHelper->setTag('div');
    $breadcrumbsHelper->setSeparator(' / ');
    echo $breadcrumbsHelper->render();
    
    // <li><a href="/home/">home</a></li> / <li><a href="/profile/">profile</a></li> / <li>address</li>

When using the tag `ul` or `ol` also the attributes `id`, `class`, `style` can be defined.

Example with `ul` element:

$breadcrumbsHelper->setTag('ul');
    $breadcrumbsHelper->setOptions(array('id' => 'breadcrumb', 'class' => 'breadcrumbs'));
    echo $breadcrumbsHelper->render();
    
    // <ul id="breadcrumb" class="breadcrumbs"><li><a href="/home/">home</a></li><li><a href="/profile/">profile</a></li><li>address</li></ul>

Example with `ol` element:

$breadcrumbsHelper->setTag('ol');
    $breadcrumbsHelper->setOptions(array('id' => 'breadcrumb', 'class' => 'breadcrumbs'));
    echo $breadcrumbsHelper->render();

// <ol id="breadcrumb" class="breadcrumbs"><li><a href="/home/">home</a></li><li><a href="/profile/">profile</a></li><li>address</li></ol>

### Breadcrumb Smarty Plugin

When using the Smarty Template Engine the breadcrumb helper can be integrated with a smarty plugin.

First have hook up the smarty plugins to smarty.

$smartyObject->plugins_dir[] = PATH_LIBRARY . 'vendor/naucon/Breadcrumbs/SmartyPlugins';

Next assign the instance of `Breadcrumbs` class to smarty.

$smarty->assign('breadcrumbs', $breadcrumbs);

Then add the plugin to the template.

{ncbreadcrumbs from=$breadcrumbs tag='span' separator=' / '}
    
or
    
    {ncbreadcrumbs from=$breadcrumbs tag='div' separator=' / '}

or
    
    {ncbreadcrumbs from=$breadcrumbs tag='ul' id='breadcrumb' class='breadcrumbs'}

{ncbreadcrumbs from=$breadcrumbs tag='ol' id='breadcrumb' class='breadcrumbs'}

{ncbreadcrumbs from=$breadcrumbs tag='ol' id='breadcrumb' class='breadcrumbs' reverse=true}

{ncbreadcrumbs from=$breadcrumbs separator=' / ' skip-links=true}

The smarty plugin supports the following parameters

* from = assigned breadcrumbs variable (MUST)
* tag = define html tag surrounding the breadcrumb elements (optional)
* separator = define separator between the breadcrumb elements (optional)
* reverse = define the order that the breadcrumbs is iterated (optional)
* skip-links = links will not be rendered (optional)
* id = define a id attribute on a surrounding html element like ul and ol but not div, span or li (optional)
* class = define a id attribute on a surrounding html element like ul and ol but not div, span or li (optional)
* style = define a id attribute on a surrounding html element like ul and ol but not div, span or li (optional)

Breadcrumbs

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README