PHPackages                             equidna/laravel-toolkit - 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. equidna/laravel-toolkit

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

equidna/laravel-toolkit
=======================

Multi-context Laravel helpers, middleware, and utilities.

1.0.4(5mo ago)07483MITPHPPHP ^8.2CI failing

Since Sep 10Pushed 5mo ago1 watchersCompare

[ Source](https://github.com/EquidnaMX/laravel-toolkit)[ Packagist](https://packagist.org/packages/equidna/laravel-toolkit)[ RSS](/packages/equidna-laravel-toolkit/feed)WikiDiscussions master Synced 1mo ago

READMEChangelog (10)Dependencies (6)Versions (22)Used By (3)

Equidna Laravel Toolkit
=======================

[](#equidna-laravel-toolkit)

A Laravel 11/12 package that unifies response patterns, pagination utilities, and route detection across web, API, hook, IoT, and console entry points. The toolkit ships helpers, middleware, traits, and a service provider so host applications can enforce consistent behavior without rewriting boilerplate.

[![CI status](https://github.com/EquidnaMX/laravel-toolkit/actions/workflows/ci.yml/badge.svg)](https://github.com/EquidnaMX/laravel-toolkit/actions/workflows/ci.yml/badge.svg)

At a Glance
-----------

[](#at-a-glance)

- **Context-aware routing**: Detect API, hook, IoT, JSON-only, and console flows with configurable matchers.
- **Unified responses**: Generate JSON, redirects, or console output through a single helper API and swappable strategies.
- **Validation-friendly requests**: `EquidnaFormRequest` surfaces validation failures as HTTP exceptions instead of redirects.
- **Pagination utilities**: Build length-aware or cursor paginators from arrays, collections, or queries with sanitized query strings.
- **Pluggable middleware**: Force JSON, disable Debugbar, or exclude requests from session history as needed.
- **Composite key support**: `HasCompositePrimaryKey` removes boilerplate for multi-column primary keys.

Compatibility
-------------

[](#compatibility)

- **PHP:** 8.2 or 8.3 (validated in CI)
- **Laravel:** 11.x or 12.x
- **Composer:** 2.5+ recommended (for `composer audit`)

Installation
------------

[](#installation)

```
composer require equidna/laravel-toolkit
php artisan vendor:publish --tag=equidna:config
```

Auto-discovery registers the service provider. For manual registration add to `config/app.php`:

```
'providers' => [
    Equidna\Toolkit\Providers\EquidnaLaravelToolkitServiceProvider::class,
],
```

Configuration
-------------

[](#configuration)

`config/equidna.php` (publish to your app) exposes the main touchpoints:

```
return [
    'paginator' => [
        'page_items' => 15,
        'strategy' => null, // bind PaginationStrategyInterface to override
    ],
    'route' => [
        'api_matchers' => ['api*', '*-api*'],
        'hook_matchers' => ['hooks/*'],
        'iot_matchers'  => ['iot/*'],
        'json_matchers' => [],
        'detector' => null,           // RouteDetectorInterface
        'request_resolver' => null,   // RequestResolverInterface
    ],
    'responses' => [
        'allowed_headers' => ['Cache-Control', 'Retry-After'],
        'strategies' => [], // console/json/redirect => class names
    ],
];
```

- Matchers feed directly into `Request::is()`. Align them with your route prefixes (e.g., `services/api/*`).
- JSON preference is inferred from API/hook/IoT matchers, additional `json_matchers`, or `Request::expectsJson()`.
- To override behavior, either bind the related interface or set the fully qualified class in config; boot will fail fast if a class is missing or does not implement the expected interface.
- **Allowed headers** (`equidna.responses.allowed_headers`): When JSON responses are sent, only headers in this allow-list are passed to the client. By default, `Cache-Control` and `Retry-After` are allowed. In non-debug mode, the header filtering is enforced to prevent accidental leakage of sensitive internal headers (e.g., X-Debug-Token). Customize this list in config if your application depends on additional headers for caching or rate-limiting.

### Mandatory configuration and failure modes

[](#mandatory-configuration-and-failure-modes)

The service provider validates critical bindings during boot. Laravel throws an `InvalidArgumentException` when a configured class is missing or does not implement its interface (e.g., `RouteDetectorInterface`, `RequestResolverInterface`, `PaginationStrategyInterface`, `ResponseStrategyInterface`). This keeps deployments from silently misbehaving.

The toolkit ships default pagination and response strategies; leaving `equidna.paginator.strategy` and `equidna.responses.strategies` empty uses the built-ins. Misconfigured or missing classes raise a `ConfigurationException` at runtime. Ensure `paginator.page_items` remains a positive integer to avoid boot-time failures.

### Swap strategies for org-specific policies

[](#swap-strategies-for-org-specific-policies)

Use container overrides or config to customize detection, pagination, or responses without editing package code:

```
// In your application's service provider
$this->app->singleton(\Equidna\Toolkit\Contracts\RouteDetectorInterface::class, fn($app) =>
    $app->make(App\Routing\SubdomainRouteDetector::class)
);

$this->app->singleton('equidna.responses.json_strategy', fn($app) =>
    $app->make(App\Http\Responses\AuditJsonResponse::class)
);
```

Usage
-----

[](#usage)

### RouteHelper

[](#routehelper)

```
use Equidna\Toolkit\Helpers\RouteHelper;

if (RouteHelper::isApi()) { /* ... */ }
if (RouteHelper::wantsJson()) { /* return an API-friendly payload */ }
```

### ResponseHelper

[](#responsehelper)

```
use Equidna\Toolkit\Helpers\ResponseHelper;

// JSON for API/hook/IoT, redirect with flash for web, text for console
return ResponseHelper::success('Saved', ['id' => $model->id]);

// Custom status and headers (filtered through the allow-list for JSON)
return ResponseHelper::unprocessableEntity(
    message: 'Invalid input',
    errors: ['email' => ['Already taken']],
    headers: ['Retry-After' => '30'],
);
```

### Pagination

[](#pagination)

```
use Equidna\Toolkit\Helpers\PaginatorHelper;

$paginator = PaginatorHelper::buildPaginator($collection, page: 2, items_per_page: 20, set_full_url: true);
PaginatorHelper::appendCleanedRequest($paginator, request());
```

Cursor and length-aware pagination helpers proxy to the configured `PaginationStrategyInterface` and accept optional transformations via `through()`.

### Composite primary keys

[](#composite-primary-keys)

```
use Equidna\Toolkit\Traits\Database\HasCompositePrimaryKey;

class UserRole extends Model
{
    use HasCompositePrimaryKey;

    public function getKeyName()
    {
        return ['user_id', 'role_id'];
    }
}
```

### Middleware

[](#middleware)

Register in your host app's `Http\Kernel` when desired:

- `Http\Middleware\ForceJsonResponse` – forces JSON responses for matched requests.
- `Http\Middleware\ExcludeFromHistory` – skips adding requests to browser history.
- `Http\Middleware\DisableDebugbar` – disables Laravel Debugbar for the request lifecycle.

### Exceptions

[](#exceptions)

HTTP-friendly exceptions (`src/Exceptions/*`) are container-bound by the service provider and render context-aware responses. Use them in controllers/services to standardize error handling (e.g., `throw new UnauthorizedException();`).

### Traits & Requests

[](#traits--requests)

- `Traits\Database\HasCompositePrimaryKey` – declare composite key columns via `getKeyName()`.
- `Traits\Database\Paginator` – integrates pagination helpers inside models.
- `Http\Requests\EquidnaFormRequest` – extends Laravel's `FormRequest` to emit HTTP exceptions instead of redirects on validation failure.

### Technical overview

[](#technical-overview)

- `Helpers/` — context-aware utilities (RouteHelper, ResponseHelper, PaginatorHelper)
- `Http/Middleware/` — ForceJsonResponse, ExcludeFromHistory, DisableDebugbar
- `Exceptions/` — custom HTTP exceptions auto-bound by the service provider
- `Traits/Database/` — HasCompositePrimaryKey, Paginator (for Eloquent)
- `Providers/` — EquidnaLaravelToolkitServiceProvider

Development
-----------

[](#development)

- Coding standard: PSR-12 (`vendor/bin/phpcs --standard=ruleset.xml`).
- Static analysis: `vendor/bin/phpstan analyse -c phpstan.neon --memory-limit=512M`.
- Tests: `vendor/bin/phpunit`.
- Run `composer audit --locked` before releases.

### Release hygiene

[](#release-hygiene)

- Keep `CHANGELOG.md` updated for every user-facing change and reset the `Unreleased` section when tagging.
- Align the package version in `composer.json` with the release tag and changelog entry.
- Run audits, linters, static analysis, and tests (above) before publishing.

### PHPStan note

[](#phpstan-note)

Running PHPStan against the library can surface `trait.unused` warnings for `Traits/Database/HasCompositePrimaryKey.php` and `Traits/Database/Paginator.php` because they are consumed by downstream apps. Options:

- Leave the warning (informational).
- Add an `ignoreErrors` rule for these messages in `phpstan.neon`.
- Add minimal unit tests or example usage files that reference the traits so PHPStan recognizes they are used.

Enterprise readiness checklist
------------------------------

[](#enterprise-readiness-checklist)

- **Compatibility matrix:** PHP 8.2/8.3, Laravel 11/12. Defaults work without custom strategies; failures raise `ConfigurationException`.
- **Quality gates (run before release):** `composer install`, `vendor/bin/phpunit`, `vendor/bin/phpstan analyse -c phpstan.neon --memory-limit=512M`, `vendor/bin/phpcs --standard=ruleset.xml`, `composer audit --locked` (add `--no-dev` for production builds).
- **Configuration safety:** Toolkit ships default pagination/response strategies; boot-time validation prevents misconfiguration. `paginator.page_items` must be a positive integer.
- **Security posture:** No remote calls or telemetry; header allow-list enforced for JSON/redirect contexts. Use GitHub issues for security contact until a SECURITY.md is published.
- **Release discipline:** Semantic Versioning; align `composer.json` version, tag, and `CHANGELOG.md` entry. Run quality gates and audits before tagging.

License & compliance
------------------------

[](#license--compliance)

- **License:** MIT (see [`LICENSE`](LICENSE)).
- **Dependencies:** Laravel Framework, Illuminate Support, and Laravel Helpers (MIT licensed).
- **Packaging:** Ships as a Composer library with no bundled telemetry or proprietary services.

###  Health Score

44

—

FairBetter than 92% of packages

Maintenance73

Regular maintenance activity

Popularity18

Limited adoption so far

Community14

Small or concentrated contributor base

Maturity61

Established project with proven stability

 Bus Factor1

Top contributor holds 81.5% 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 ~23 days

Recently: every ~5 days

Total

20

Last Release

153d ago

Major Versions

0.6.5 → 1.0.02025-11-17

PHP version history (2 changes)0.1.0PHP ^8.0

1.0.4PHP ^8.2

### Community

Maintainers

![](https://www.gravatar.com/avatar/21aa1f99daa17783331e507c7fa7ffd1fb5d9e93450069209d2c43e6d5c8ca1a?d=identicon)[gruelas](/maintainers/gruelas)

---

Top Contributors

[![gruelasjr](https://avatars.githubusercontent.com/u/40619710?v=4)](https://github.com/gruelasjr "gruelasjr (119 commits)")[![Copilot](https://avatars.githubusercontent.com/in/1143301?v=4)](https://github.com/Copilot "Copilot (27 commits)")

###  Code Quality

TestsPHPUnit

Static AnalysisPHPStan

Code StylePHP\_CodeSniffer

### Embed Badge

![Health badge](/badges/equidna-laravel-toolkit/health.svg)

```
[![Health](https://phpackages.com/badges/equidna-laravel-toolkit/health.svg)](https://phpackages.com/packages/equidna-laravel-toolkit)
```

###  Alternatives

[tomshaw/electricgrid

A feature-rich Livewire package designed for projects that require dynamic, interactive data tables.

116.6k](/packages/tomshaw-electricgrid)[aedart/athenaeum

Athenaeum is a mono repository; a collection of various PHP packages

255.2k](/packages/aedart-athenaeum)

PHPackages © 2026

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