ziglite
v1.0.1
Published
A Laravel route name translator for Javascript
Downloads
19
Maintainers
Readme
Ziglite - A Laravel route name translator for Javascript
What is Ziglite?
Ziglite provides a way for Laravel developers to use their route names in the front end.
This package is inspired by, and a lightweight minimalistic alternative to, the excellent and feature-rich Ziggy by Tighten.co.
- Quick Start
- Why Ziglite?
- Usage in a Package
- Route Filtering
- The Routes Manifest
- The Blade Directive
- The Front-end Helpers
- Contributing
- Credits
- License
Quick Start
Install Ziglite in your Laravel application or package with Composer:
composer require spatian-dev/ziglite
yarn install ziglite
Include the default directive in your Blade @ziglite("*")
:
⚠️Warning: This will expose all the named routes and their parameters in your application to the front-end, which may not be desirable.
See Route filtering to learn about including and excluding routes.
Configure the javascript helpers:
import { configureRouter } from 'ziglite';
configureRouter(ziglite_data);
Use the route()
helper to translate named routes to URLs:
import { route } from 'ziglite';
route('users.update', {user: 5});
⚠️Warning: Ziglite does not support Encoded Forward Slashes. See strict mode for more information.
Why Ziglite?
Ziglite is intended to be a simplified alternative to Ziglite. By omitting some of Ziggy's more advanced features, Ziglite offers a focused feature set aimed at ease of use. One notable difference is in filtering: Ziglite opts for a simplified and stricter approach by default.
Additionally, Ziglite boasts seamless integration into Laravel packages, providing developers with the ability to:
- Define custom aliases for the default Blade directive
- Utilize custom output generators
- Exert greater control over route filtering.
We hope Ziglite delivers simplicity and versatility for your Laravel projects and packages.
If you have ideas or suggestions, please see Contributing.
Usage in a Package
Register Ziglite's service provider inside the register()
method of your package's service provider:
$this->app->register(\Spatian\Ziglite\Providers\ZigliteServiceProvider::class);
You can then use the package the same way you would from a regular Laravel Application.
Route Filtering
Ziglite only includes named routes that match explicitly provided filters. The filtering is based on pattern-matching capabilities provided by Laravel's Str helper.
Exclusion can be defined by starting the pattern with a !
ℹ️ Exclusions patterns are always prioritized over inclusion patterns, regardless of the order in which they are defined.
For example:
*
will include all named routes!users.*
will exclude all named routes starting withusers.
!*.index
will exclude all named routes ending with.index
home
will include the route namedhome
You can provide as many inclusion or exclusion patterns as necessary
use Spatian\Ziglite\Routes\Manifest;
new Manifest(["*", "!admin.*", "!api.*"]);
// in blade
@ziglite(["*", "!admin.*", "!api.*"]);
The Routes Manifest
The core of Ziglite revolves around the \Spatian\Ziglite\Routes\Manifest
class. This class collects and caches your application's named routes, and generates a list of named routes that match the provided filters.
Filters
By default, a Manifest
instance will only include named routes that match the provided filters. If no filters are provided, then no routes are included.
Filtering patterns can be provided as the first argument to the constructor.
use Spatian\Ziglite\Routes\Manifest;
new Manifest(); // No routes included
new Manifest("*"); // A single pattern
new Manifest(["*", "!admin.*", "!api.*"]); // A list of patterns
See Route filtering to learn more about filtering.
Custom Origin
You can specify a custom origin to be included in the manifest.
use Spatian\Ziglite\Routes\Manifest;
new Manifest(base: 'https://example.test');
Caching
The Manifest
class caches previously generated manifests for the duration of a request. Subsequent calls with the same filtering patterns simply return the previously calculated result.
If this is not desirable, you can clear this cache using :
use Spatian\Ziglite\Routes\Manifest;
Manifest::clearRoutes();
Serializing to JSON
The Manifest
class implements JsonSerializable
and a toJson()
function to simplify serializing to JSON.
use Spatian\Ziglite\Routes\Manifest;
json_encode(new Manifest());
(new Manifest())->toJson();
The Blade Directive
By default, Ziglite defines a @ziglite
blade directive. This directive uses the default JavascriptDataTagGenerator
to include a manifest as a JSON object in a blade.
The JSON object is assigned to a ziglite_data
variable on the window
global.
// home.blade.php
@ziglite("*")
// home.js
console.log(ziglite_data);
/*
Should print an object similar to :
{
base: ...,
defaults: { ... },
routes: [ ... ],
}
*/
Custom Directives and Custom Generators
You can define your custom generators by implementing the OutputGeneratorInterface
. This requires implementing a make()
function that generates the output as a string.
make(array|string $filters = [], string $base = null, string $nonce = ''): string
$filters
pattern or list of patterns for filtering$base
custom origin to be included in the output$nonce
a CSP nonce to be included in the output.
You can also define a custom blade directive that uses your custom generator. In your AppServiceProvider
:
app('ziglite')->setupBladeDirective('mydirective', new MyCustomOutputGenerator());
The Front-end Helpers
The javascript library is published to a separate NPM package.
yarn install ziglite
By default, Ziglite does not globally import its javascript helpers. Instead, it defers to the developer to include them and use them as they see fit.
The library does, however, create an internal default instance of the Router
class. You can interact with this instance through the helper functions below.
The configureRouter()
helper
Use this function to set the configuration for the default Router
instance.
import { configureRouter } from 'ziglite';
configureRouter(ziglite_data);
configureRouter({
strict: false,
absolute: true,
base: 'https://example.test',
});
The route()
and hasRoute()
helpers
The route()
function translates a named route to a URL using the default Router
instance. This function works similarly to Laravel's route()
.
import { route } from 'ziglite';
route('home');
route('users.show', {user: 5});
The hasRoute()
function checks if the default Router
instance has a configured route that matches the given name.
import { hasRoute } from 'ziglite';
hasRoute('home'); // assuming a route named 'home' exits, return true;
hasRoute('inexistant'); // assuming no route named 'inexistant' exits, return false;
Default Parameters
Ziglite supports Laravel's default parameters.
import { route } from 'ziglite';
/*
Given a route named 'users.show' defined as /{locale}/users/{user},
and configured route default ['locale' => 'en']
*/
route('users.show', {user: 5}); // https://example.test/en/users/5
Generating Absolute URLs
By default, Ziglite will generate relative URLs. To generate absolute URLs instead, set the absolute
configuration to true
;
import { configureRouter, route } from 'ziglite';
configureRouter({
absolute: true,
base: 'https://example.test',
// ...
});
route('users.show', {user: 5}); // https://example.test/users/5
Extra Query Parameters
Ziglite will automatically add any unmatched parameters as a query string to the resulting URL:
import { route } from 'ziglite';
route('users.show', {user: 5, extra: 2}); // https://example.test/users/5?extra=2
If you need to add query-string parameters that have the same name as your route's parameter, you can do so under a _query
object:
import { route } from 'ziglite';
route('users.show', {
user: 5,
extra: 2,
_query: {
user: 'Tony'
},
}); // https://example.test/users/5?extra=2&user=Tony
By default, booleans are converted to integers
import { route } from 'ziglite';
route('users.show', {
user: 5,
locked: true,
}); // https://example.test/users/5?locked=1
The Router Class
The Router
provides the core of Ziglite's javascript functionality.
If you would like to use Ziglite's features without modifying the default instance, you might create your own Router
instance:
import { Router } from 'ziglite';
const config = {
absolute: true,
base: 'https://example.test',
defaults: {
locale: 'en',
},
routes: [ /* ... */],
};
const myRouter = new Router();
myRouter.config = config;
// or
const myRouter = new Router(config);
// check if the given named route exists
myRouter.has('home');
// translate the given named route and parameters to a URL
myRouter.compile('users.show', {user: 5}); // https://example.test/users/5
Strict Mode
Ziglite does not support Encoded Forward Slashes. This has historically been buggy, inconsistent and overall not a reliable feature to implement.
By default, Ziglite will issue a warning in your console if it encounters a forward slash, plain (/
) or encoded (%2F
), in a parameter value.
If you enable strict mode, Ziglite will throw an error instead.
import { configureRouter, route } from 'ziglite';
configureRouter({
strict: true,
// ...
});
route('users.show', {user: 'test/test'}); // throws
Contributing
Please consult the contribution guide.
Credits
- This package is heavily inspired by the excellent and feature-rich Ziggy by Tighten.co. Shout out to them.
- Saad Sidqui
- All the contributors
License
Ziglite is free and open-source software released under the Apache 2.0 license. See LICENSE for more information.