PHPackages                             tonka/spark - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Utility & Helpers](/categories/utility)
4. /
5. tonka/spark

ActiveLibrary[Utility & Helpers](/categories/utility)

tonka/spark
===========

Tonka Spark is a PHP library that provides Ziggy-like functionality for Laravel applications, allowing you to generate URLs to named routes in your JavaScript code.

v1.2.7(1mo ago)0141MITPHPPHP >=8.0

Since Feb 24Pushed 1mo agoCompare

[ Source](https://github.com/clicalmani/spark)[ Packagist](https://packagist.org/packages/tonka/spark)[ RSS](/packages/tonka-spark/feed)WikiDiscussions main Synced 1w ago

READMEChangelog (5)DependenciesVersions (6)Used By (1)

Tonka/Spark 🌩️
==============

[](#tonkaspark-️)

The secure bridge between your [**Tonka Framework**](https://clicalmani.github.io/tonka) backend and your frontend router.

`Spark` is the server-side package responsible for exposing, filtering, and formatting your named routes for the `tonka-router` package. It features dynamic access control through **Policies**, allowing you to hide sensitive routes from unauthorized users effortlessly.

🌟 Why use Spark?
----------------

[](#-why-use-spark)

Exposing *all* your backend routes to the browser is a security risk. `Spark` solves this by giving you fine-grained control over what is visible to the frontend, leveraging your existing **Policy** classes to determine visibility based on the current user's role.

✨ Features
----------

[](#-features)

- 🛡️ **Dynamic Access Control**: Integrate with your existing Policy classes to show/hide routes (e.g., hide `admin.*` from regular users) automatically.
- 📦 **JSON Output**: Generates a structured JSON object ready for JavaScript consumption.
- 🖥️ **Template Directive**: Injects routes directly into your HTML (via a `data-routes` attribute or global variable).
- 🔌 **Groups**: Organize your routes by group (e.g., `public`, `auth`) and expose them selectively for better performance.
- 🚀 **Flexible Filtering**: Use Whitelist (`only`) or Blacklist (`except`) modes with wildcard support.

⚙️ Configuration
----------------

[](#️-configuration)

Publish the configuration file:

```
php tonka spark:config
```

This will create `config/spark.php`:

```
return [
    /*
    |--------------------------------------------------------------------------
    | Route Filtering (Whitelist Mode)
    |--------------------------------------------------------------------------
    | By default, no routes are exposed for security.
    | You must explicitly allow routes.
    |
    | You can attach a 'policy' class to any rule. If provided, Spark will
    | instantiate it and call the authorize() method. If it returns false,
    | the route will be hidden from the JSON output.
    */
    'only' => [
        // Public routes (accessible to everyone)
        [
            'name' => 'home',
            'policy' => null
        ],
        [
            'name' => 'posts.*', // Wildcard support
            'policy' => null
        ],

        // Protected routes (Only visible if the Policy returns true)
        [
            'name' => 'users.profile',
            'policy' => \App\Contracts\Spark\UserContract::class
        ],

        // Admin routes (Only visible if AdminContract authorizes)
        [
            'name' => 'admin.*',
            'policy' => \App\Contracts\Spark\AdminContract::class
        ],
    ],

    /*
    |--------------------------------------------------------------------------
    | Route Filtering (Blacklist Mode)
    |--------------------------------------------------------------------------
    | Use this to expose everything EXCEPT specific patterns.
    | Policies are also supported here to enforce further restrictions.
    */
    // 'except' => [
    //     [
    //         'name' => '_debugbar.*',
    //         'policy' => \App\Contracts\Spark\SuperAdminContract::class
    //     ],
    // ],

    /*
    |--------------------------------------------------------------------------
    | Groups
    |--------------------------------------------------------------------------
    | Define route groups for selective exposure via @routes('group_name').
    */
    'groups' => [
        'public' => ['home', 'about', 'contact'],
        'auth' => ['dashboard', 'profile', 'settings'],
    ],
];
```

### 🧭 Groups vs. Policies: Why Use Both?

[](#-groups-vs-policies-why-use-both)

You might wonder: *"If Policies handle security, are Groups necessary?"*

The short answer is **yes**. They serve distinct but complementary purposes:

- **Policies (The "Who am I?"):** Handle **Security**. They determine if the current user is *authorized* to see a specific route (e.g., hiding `admin.*` from regular users).
- **Groups (The "Where am I?"):** Handle **Context & Performance**. They determine which routes are *relevant* to the current page (e.g., only sending auth routes to the Dashboard page, not the Login page).

**Why combine them?**

1. **Performance:** Without groups, sending *all* authorized routes (which could be hundreds) to a simple login page is wasteful. Using groups keeps the JSON payload small and fast.
2. **Maintainability:** Groups allow you to update route lists in one place (`config/spark.php`) instead of hardcoding arrays in every Blade file.

🚀 Usage
-------

[](#-usage)

### 1. Injection in Views (Recommended)

[](#1-injection-in-views-recommended)

Use the `@routes` directive in your main layout.

```
>

    @routes('auth')
    @inertia

```

**How it works with Policies:**When the page loads, `Spark` iterates through your configuration. For every route matching your rules, it checks the associated `Policy`.

- If the **Policy** authorizes the request → The route is included in the JSON.
- If the **Policy** denies the request → The route is excluded.
- If no **Policy** is defined → The route is included (default behavior).

### 2. File Generation

[](#2-file-generation)

Generate a static routes file for SPAs:

```
php tonka spark:generate
```

This creates a `routes.json` file reflecting the current user's permissions.

### 3. API Endpoint

[](#3-api-endpoint)

For dynamic fetching:

```
Route::get('/api/spark-routes', function () {
    return \Tonka\Spark\Spark::toJson();
});
```

🔐 Security Best Practices
-------------------------

[](#-security-best-practices)

1. **Use Policies for Sensitive Routes**: Do not rely solely on frontend hiding. Use the `policy` key to ensure backend logic prevents unauthorized routes from ever reaching the browser.
2. **Avoid `except` if possible**: Whitelisting (`only`) is generally safer than blacklisting (`except`) for API exposure.
3. **Validate Policy Methods**: Ensure your Policy classes have a public `authorize()` method that returns a boolean.

📚 Integration with Tonka Router
-------------------------------

[](#-integration-with-tonka-router)

Once exposed, your frontend consumes the routes seamlessly:

```
import { route } from 'tonka-router';

// This link will only be generated if the 'admin.users' route was authorized by the backend Policy
const url = route('admin.users', { id: 1 }); // Or simply route('admin.users', [1])
```

###  Health Score

39

—

LowBetter than 84% of packages

Maintenance92

Actively maintained with recent releases

Popularity6

Limited adoption so far

Community8

Small or concentrated contributor base

Maturity43

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~15 days

Total

5

Last Release

44d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/7316d2003f9fbef5b19aaa8caa3983f37742f2b1872e72a5390077c2975fc2e6?d=identicon)[honorable85](/maintainers/honorable85)

---

Top Contributors

[![clicalmani](https://avatars.githubusercontent.com/u/16488123?v=4)](https://github.com/clicalmani "clicalmani (4 commits)")

### Embed Badge

![Health badge](/badges/tonka-spark/health.svg)

```
[![Health](https://phpackages.com/badges/tonka-spark/health.svg)](https://phpackages.com/packages/tonka-spark)
```

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)