PHP-Navigation

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

useFeskol\Navigation\Link;
useFeskol\Navigation\Navigation;
// create links$navLink = newLink();
$navLink->setTitle('Company')
->setHref('/company');
$subNavLink = newLink();
$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 = newNavigation();
$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 activeforeach($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="":

useFeskol\Navigation\Link;
$link = newLink();
// 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:

useFeskol\Navigation\Link;
class MyCustomLink extends Link
{
private ?string$icon = null;
publicfunctiongetIcon(): ?string {
return$this->icon;
}
publicfunctionsetIcon(?string$icon): static {
$this->icon = $icon;
return$this;
}
}

Then use your MyCustomLink class instead of the Link class:

$link = newMyCustomLink();
$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

useFeskol\Navigation\Link;
useFeskol\Navigation\Navigation;
useSymfony\Component\Translation\TranslatableMessage;
$navigation = newNavigation();
$navigation->setTitle(newTranslatableMessage('MyNavigation', [], 'navigation'));
$navLink = newLink();
$navLink->setTitle(newTranslatableMessage(
'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 }} {% forlinkinnavigation.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!