README

Framework agnostic PHP package for marking navigation items active.

Features

Framework agnostic.
Can be modified for any custom application and UI.
Currently supported frameworks: Laravel (PRs are welcome!).
Global helper functions disabled by default.
Supports default output value.
Backward compatible.
Fully tested using table driven testing (data providers in PHPUnit).

Installation

From the command line:

composer require laravelista/ekko

By default Ekko is initialized with these sensible defaults:

the default output value is active.
it uses GenericUrlProvider ($_SERVER['REQUEST_URI']).
global helper functions are disabled.

Laravel

The only dependency for this package is PHP ^8.0, meaning that you can possibly install it on any Laravel version that supports PHP 8 (I think that for now this is only Laravel 8). The service provider is always going to follow the latest Laravel release and try to be as backward compatible as possible.

Laravel 8 will use the auto-discovery function to register the ServiceProvider and the Facade.

If you are not using auto-discovery, you will need to include the service provider and facade in config/app.php:

'providers' => [
    ...,
    Laravelista\Ekko\Frameworks\Laravel\ServiceProvider::class
];

And add a facade alias to the same file at the bottom:

'aliases' => [
    ...,
    'Ekko' => Laravelista\Ekko\Frameworks\Laravel\Facade::class
];

Overview

To mark a menu item active in Bootstrap, you need to add a active CSS class to the <li> tag:

<ul class="nav navbar-nav">
    <li class="active"><a href="/">Home</a></li>
    <li><a href="/about">About</a></li>
</ul>

You could do it manually with Laravel, but you will end up with a sausage:

<ul class="nav navbar-nav">
    <li class="@if(URL::current() == URL::to('/')) active @endif"><a href="/">Home</a></li>
    <li><a href="/about">About</a></li>
</ul>

With Ekko your code could look like this:

<ul class="nav navbar-nav">
    <li class="{{ Ekko::isActive('/') }}"><a href="/">Home</a></li>
    <li><a href="/about">About</a></li>
</ul>

or like this:

<ul class="nav navbar-nav">
    <li class="{{ Ekko::isActiveRoute('home') }}"><a href="/">Home</a></li>
    <li><a href="/about">About</a></li>
</ul>

or this:

<ul class="nav navbar-nav">
    <li class="{{ $ekko->isActive('/') }}"><a href="/">Home</a></li>
    <li><a href="/about">About</a></li>
</ul>

Default output value

What if you are not using Bootstrap, but some other framework or a custom design? Instead of returning active CSS class, you can make Ekko return anything you want.

<ul class="nav navbar-nav">
    <li class="{{ Ekko::isActive('/', 'highlight') }}"><a href="/">Home</a></li>
    <li><a href="/about">About</a></li>
</ul>

You can alse set the default output value if you don't want to type it everytime:

$ekko = new Ekko;
$ekko->setDefaultValue('highlight');
return $ekko->isActive('/');

or in Laravel you can set the default output value in the config config/ekko.php file:

<?php

return [
    'default_output' => 'highlight'
];

To publish the config for Ekko use this in Laravel:

php artisan vendor:publish --provider="Laravelista\Ekko\Frameworks\Laravel\ServiceProvider"

Using boolean true or false is convenient if you need to display some content depending on which page you are in your layout view:

@if(Ekko::isActive('/about', true))
    <p>Something that is only visible on the `about` page.</p>
@endif

Global helper functions

Global helper functions are disabled by default. To enable them use Ekko::enableGlobalHelpers(); or $ekko->enableGlobalHelpers().

In Laravel add this code to your app/Providers/AppServiceProvider.php file in register method:

\Ekko::enableGlobalHelpers();

Usage

When used outside a framework, this package has only one main method of interest called isActive. The function accepts an input which can be a string or an array of strings, and an output which can be anything. The default output is active.

<li class="{{ $ekko->isActive('/') }}"><a href="/">Home</a></li>
<li class="{{ $ekko->isActive(['/', '/home]) }}"><a href="/">Home</a></li>
<li class="{{ $ekko->isActive(['/', '/home, '*home*']) }}"><a href="/">Home</a></li>
<li class="{{ $ekko->isActive('/home*') }}"><a href="/">Home</a></li>
<li class="{{ $ekko->isActive('/home*feature=slideshow*') }}"><a href="/">Home</a></li>
<li class="{{ $ekko->isActive('/index.php?page=*') }}"><a href="/">Home</a></li>

It supports strings, arrays, wildcards and query parameters.

Laravel usage

Use the facade Ekko::, resolve(Ekko::class) or app(Ekko::class) to obtain the Laravel bootstraped instance.

Laravel comes with few special methods for named routes and other helper methods. Also, there is a lot of backward compatibility here for v1 of this package.

Methods

Ekko::isActive($input, $output = null) This calls the main Ekko method isActive. Described above.

Ekko::isActiveRoute($input, $output = null) For named routes. Supports arrays and wildcards.

Ekko::areActiveRoutes(array $input, $output = null) For arrays of named routes. Supports wildcards. Backward compatibility. Use isActiveRoute and pass it the same array.

Ekko::isActiveURL($input, $output = null) The same as Ekko::isActive. Backward compatibility. Use Ekko::isActive and pass it the same input.

Ekko::areActiveURLs(array $input, $output = null) The same as Ekko::isActiveURL, but accepts only the array of Urls. Backward compatibility. Use Ekko::isActive and pass it the same array.

Ekko::isActiveMatch($input, $output = null) The same as Ekko::isActive. This method encloses the input with wildcard *. Supports string, array and wildcards as input. Backward compatibility. Use Ekko::isActive and pass it the same input, but with wildcard * at the desired place.

Ekko::areActiveMatches(array $input, $output = null) The same as Ekko::isActiveMatch, but accepts only the array of strings. Backward compatibility. Use Ekko::isActive and pass it the same array.

Development

# Install dependencies
composer install

# Run tests
vendor/bin/phpunit

# Run Psalm
vendor/bin/psalm

# Format code (php-cs-fixer)
vendor/bin/php-cs-fixer

Credits

Many thanks to:

@judgej for route wildcards.
@Jono20201 for helper functions.
@JasonMillward for improving wildcards in nested route names.
@it-can for Laravel 5.5+ auto-discovery.
@foo99 for snake_case function names.
@Turboveja for are_active_matches function.

Sponsors & Backers

I would like to extend my thanks to the following sponsors & backers for funding my open-source journey. If you are interested in becoming a sponsor or backer, please visit the Backers page.

Contributing

Thank you for considering contributing to Ekko! The contribution guide can be found Here.

Code of Conduct

In order to ensure that the open-source community is welcoming to all, please review and abide by the Code of Conduct.

License

Ekko is open-source software licensed under the MIT license.

daltcore / ekko

Maintainers

Details