laravelista / ekko
Framework agnostic PHP package for marking navigation items active.
Fund package maintenance!
Patreon
Installs: 580 191
Dependents: 5
Suggesters: 0
Security: 0
Stars: 277
Watchers: 12
Forks: 28
Open Issues: 0
Requires
- php: ^8.0
Requires (Dev)
- friendsofphp/php-cs-fixer: ^2.18
- illuminate/routing: ^8.0
- illuminate/support: ^8.0
- mockery/mockery: ^1.4
- phpunit/phpunit: ^9.5
- vimeo/psalm: ^4.6
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.