README

Overview

A simple and effective Navigation to manage active states in navigation structures.
For Symfony integration, check out the NavigationBundle.

Features

• Automatically tracks a link's active status and makes it easy to check if a parent navigation item has active child links.
• Easy to set up and integrate into existing projects.
• Flexible and extensible for complex navigation structures.

Installation

Install via Composer:

composer require feskol/php-navigation

Usage

Building Your Navigation Structure

use Feskol\Navigation\Link;
use Feskol\Navigation\Navigation;

// create links
$navLink = new Link();
$navLink->setTitle('Company')
    ->setHref('/company');
    
$subNavLink = new Link();
$subNavLink->setTitle('About us')
    ->setHref('/company/about-us')
    ->setIsActive(true);
    
// add the $subNavLink as $navLinks Child
$navLink->addChild($subNavLink);


// To have all links in one place you can use the provided Navigation class:
$navigation = new Navigation();
$navigation->setTitle('MyNavigation');

// add the created $navLink to the Navigation
$navigation->addLink($navLink);

Iterating through Navigation links:

foreach ($navigation->getLinks() as $link){
    echo $link->getTitle(); // "Company"
    echo $link->hasActiveChildren(); // "true" - because the child is active
    
    foreach($link->getChildren() as $subLink){
        echo $link->getTitle(); // "About us"
        echo $link->isActive(); // "true"
    }
}

Common link data

The Link class provides setter and getter methods for the common attributes of an <a>-tag.
The most commonly used ones are href="" and target="":

use Feskol\Navigation\Link;

$link = new Link();

// href
$link->setHref('/company/about-us');
$link->getHref(); // "/company/about-us"

// target
$link->setTarget(Link::TARGET_BLANK);
$link->getTarget(); // "_blank"

To view all available methods for the common link data, check out the AbsctractHyperLink class.

Additional Data

There are often situations where you need additional data for your navigation, such as icons or images.
The best approach is to create your own class (e.g. MyCustomLink) that extends the Link class:

use Feskol\Navigation\Link;

class MyCustomLink extends Link
{
    private ?string $icon = null;
    
    public function getIcon(): ?string {
        return $this->icon;
    }
    
    public function setIcon(?string $icon): static {
        $this->icon = $icon;
        return $this;
    }
}

Then use your MyCustomLink class instead of the Link class:

$link = new MyCustomLink();
$link->setTitle('Company')
    ->setHref('/company')
    ->setIcon('bi bi-user'); // For example, using Bootstrap-Icon classes

Handling translations in your frontend

Symfony

In Symfony, you can use the TranslatableMessage class to hold translation infos which you can use in your frontend.
In Twig, apply the |trans filter to translate the TranslatableMessage.

Both the Navigation and Link classes accept any object implementing the \Stringable interface in their setTitle() methods. This allows you to pass objects like TranslatableMessage or custom classes with a __toString() method.

Example in Symfony

use Feskol\Navigation\Link;
use Feskol\Navigation\Navigation;
use Symfony\Component\Translation\TranslatableMessage;

$navigation = new Navigation();
$navigation->setTitle(new TranslatableMessage('MyNavigation', [], 'navigation'));

$navLink = new Link();
$navLink->setTitle(new TranslatableMessage(
    'Nav-Item for %customerName%',
    ['%customerName%' => $customer->getName()], // Dynamic translation parameters 
    'navigation' // Translation domain
));

$navigation->addLink($navLink);

And then in your Twig template:

{# @var \Feskol\Navigation\Navigation navigation #}  

Translated Navigation Title: {{ navigation.title|trans }}  

{% for link in navigation.links %}  
    Translated Link Title: {{ link.title|trans }}  
{% endfor %}  

Contribution Guidelines

We welcome contributions to this project! To ensure clarity and fairness for all contributors, we require that all contributors sign our Contributor License Agreement (CLA).

By signing the CLA, you confirm that:

1. You grant us the perpetual, worldwide, non-exclusive, royalty-free, irrevocable right to use, modify, sublicense, and distribute your contribution as part of this project or any other project.
2. You retain ownership of your contribution, but grant us the rights necessary to use it without restriction.
3. Your contribution does not violate the rights of any third party.

How to Sign the CLA

Before submitting a pull request, please sign the CLA using the following link:
Sign the CLA

Contributions cannot be merged unless the CLA is signed.

Thank you for your contributions and for helping us build something great!

Testing

We're using phpunit.

Run tests:

php vendor/bin/phpunit

❤️ Support This Project

If you find this project helpful and would like to support my work:

• 🌟 Star the repository to show your appreciation.
• 💸 Donate via:
  • Buy Me a Coffe:
  • PayPal:

Thank you for your support!