PHPackages                             shugoi/shugoi-php - 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. shugoi/shugoi-php

ActiveLibrary

shugoi/shugoi-php
=================

Shugoi anti-abuse protection — PHP/Laravel middleware

01↑2900%PHP

Since Jul 28Pushed todayCompare

[ Source](https://github.com/RoxasYTB/shugoi-php)[ Packagist](https://packagist.org/packages/shugoi/shugoi-php)[ RSS](/packages/shugoi-shugoi-php/feed)WikiDiscussions master Synced today

READMEChangelogDependenciesVersions (1)Used By (0)

Shugoi PHP — Anti-abuse protection for Laravel & PHP
========================================================

[](#shugoi-php--anti-abuse-protection-for-laravel--php)

[![PHP](https://camo.githubusercontent.com/5ed842996550cad148e16d3ad4738491b8319d2fbf7bba88eeeee0cb4bf9b736/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f5048502d382e322532422d373737626234)](https://camo.githubusercontent.com/5ed842996550cad148e16d3ad4738491b8319d2fbf7bba88eeeee0cb4bf9b736/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f5048502d382e322532422d373737626234)[![Laravel](https://camo.githubusercontent.com/c4e1537e5bb3958e0752596ff6da6660e674a8d33d08b1a2e4e5a66f82898661/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4c61726176656c2d31312532422d666632643230)](https://camo.githubusercontent.com/c4e1537e5bb3958e0752596ff6da6660e674a8d33d08b1a2e4e5a66f82898661/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4c61726176656c2d31312532422d666632643230)

Shugoi is a full-featured anti-abuse protection layer for PHP applications. It combines edge-level request blocking, client-side browser fingerprinting via Web Workers, split-render technology with single-use tokens, code obfuscation, and multi-layered detection to protect your web apps from bots, scrapers, automated attacks, and fraud.

### Features

[](#features)

- **Edge blocking** — Headless browser detection (curl, wget, python, puppeteer, etc.), fake browser detection (missing Sec-Fetch headers), rate limiting with configurable thresholds
- **Client-side fingerprinting** — Tor Browser detection, VM/machine detection, anti-detect browser detection, headless Chrome/Puppeteer detection via Web Worker
- **Whitelist** — machineId-based whitelist managed from the Shugoi dashboard, bypasses all client-side checks
- **Split-render** — Original HTML is stored server-side with a signed single-use token; the client receives an eval bootcode skeleton. Guards run, and if the browser is legitimate, `rd()` fetches the real HTML via `/__shugoi/render`
- **Content replacement detection** — If the render endpoint is called with an invalid/consumed token and `enableContentReplacementCheck` is enabled, a block card "Remplacement de contenu client détecté" is shown with full neobrutalist styling
- **CSP injection** — Automatic Content-Security-Policy header with proper origins for scripts, fonts, images; optionally extensible via `extraDirectives`
- **Bot verification** — Reverse DNS (FCrDNS) verification for Googlebot, Bingbot, YandexBot, Applebot, etc.
- **Obfuscation** — The eval bootcode is obfuscated (function renaming, line shuffling, XOR string encryption, decoder injection) before Unicode encoding
- **Block page** — Full neobrutalist shield page with Alex Brush font, favicon + brand images, pink h2, noise SVG background, countdown timer for rate limits. Consistent ASCII block page for non-browser clients
- **Multi-process support** — Shared disk-based HTML token storage for PHP built-in server, Laravel Octane, or any multi-worker setup
- **PSR-15 middleware** — Framework-agnostic, compatible with any PSR-15 implementation
- **Laravel integration** — ServiceProvider with auto-wiring, HTTP middleware wrapper, Facade, Blade directives (`@shugoiHead`, `@shugoiBody`), Artisan commands (`shugoi:setup`, `shugoi:check`)
- **Localization** — Full FR/EN support for block pages and error messages

Requirements
------------

[](#requirements)

- PHP 8.2+
- Laravel 11+ (for Laravel integration)
- Guzzle 7+
- PSR-15 compatible middleware (for standalone usage)

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

[](#installation)

```
composer require shugoi/shugoi-php
```

Quick Start (Laravel)
---------------------

[](#quick-start-laravel)

```
composer require shugoi/shugoi-php
```

Add to `.env`:

```
SHUGOI_SITE_KEY=sg_sk_live_xxxx
SHUGOI_SECRET=your_site_secret
```

Add to `bootstrap/app.php`:

```
->withMiddleware(function (Middleware $middleware) {
    $middleware->append(\Shugoi\Laravel\ShugoiMiddleware::class);
})
```

Verify:

```
php artisan shugoi:setup
```

Done. All HTTP requests are now protected.

Demo
----

[](#demo)

A complete demo script is available in `demo/setup.sh`:

```
cd demo && bash setup.sh
```

This creates a fresh Laravel project with Shugoi pre-configured.

Quick Start (PSR-15 standalone)
-------------------------------

[](#quick-start-psr-15-standalone)

```
use Shugoi\Config;
use Shugoi\Core;
use Shugoi\ApiClient;
use Shugoi\ConfigCache;
use Shugoi\GuardCache;
use Shugoi\HtmlStore;
use Shugoi\CspBuilder;
use Shugoi\GuardInjector;
use Shugoi\TokenSigner;
use Shugoi\Middleware;
use Nyholm\Psr7\ServerRequest;
use Nyholm\Psr7\Response;

$config = new Config([
    'siteKey' => 'sg_sk_live_xxx',
    'secret' => '80a320ee3904...',
    'allowlist' => ['/api', '/__shugoi'],
    'autoInject' => true,
    'csp' => true,
    'verifyBots' => false,
]);

$api = new ApiClient($config);
$configCache = new ConfigCache($api);
$guardCache = new GuardCache($api);
$htmlStore = new HtmlStore('/tmp/shugoi-render-shared');
$tokenSigner = new TokenSigner($config);
$cspBuilder = new CspBuilder($config);
$core = new Core($config, $api, $configCache);
$injector = new GuardInjector($config, $tokenSigner, $htmlStore, $guardCache, $configCache);

$middleware = new Middleware(
    config: $config, core: $core, api: $api,
    configCache: $configCache, guardCache: $guardCache,
    htmlStore: $htmlStore, cspBuilder: $cspBuilder,
    injector: $injector, tokenSigner: $tokenSigner,
);

$request = new ServerRequest('GET', '/', getallheaders(), file_get_contents('php://input'), '1.1', $_SERVER);

$handler = new class($uri) implements \Psr\Http\Server\RequestHandlerInterface {
    public function handle(\Psr\Http\Message\ServerRequestInterface $request): \Psr\Http\Message\ResponseInterface
    {
        return new Response(200, ['Content-Type' => 'text/html'], 'OK');
    }
};

$response = $middleware->process($request, $handler);
```

### Important: Shared disk store

[](#important-shared-disk-store)

When using the PHP built-in server (new process per request), the HtmlStore must use a SHARED disk path so tokens persist across requests:

```
$htmlStore = new HtmlStore('/tmp/shugoi-render-shared');
```

For Laravel with a persistent process (Octane, Swoole), the in-memory store works.

How it works
------------

[](#how-it-works)

### Request flow

[](#request-flow)

1. **Request arrives** → Middleware evaluates the request (UA, headers, IP, rate limits)
2. **If blocked** → Returns `BLOCKED BY SHUGOI` (text for bots) or shield page (HTML for browsers)
3. **If allowed** → Injects guard scripts into the HTML response
4. **Split-render** → Original HTML is stored with a signed token; the client receives an eval bootcode skeleton
5. **Client boots** → Guards run fingerprinting (Tor, VM, headless, anti-detect checks)
6. **If guards pass** → `rd()` fetches `/__shugoi/render?token=...` to get the real HTML
7. **If guards detect issue** → `__sg_showBlock()` displays a neobrutalist card with block reason

### Content Replacement Check

[](#content-replacement-check)

When `detectionFlags.enableContentReplacementCheck` is:

- **`true`** (default) — If the render token is invalid/expired, the block card "Remplacement de contenu client détecté" is shown
- **`false`** — The render endpoint skips token validation and returns any available stored HTML

Configuration reference
-----------------------

[](#configuration-reference)

OptionTypeDefaultDescription`siteKey`string**required**Your Shugoi site key`secret`string-Site secret for key validation`signingSecret`string`secret`HMAC secret for token signing`allowlist`string\[\]`['/api', '/legal']`Paths bypassing protection`headlessPatterns`RegExp\[\]curl, wget, python, ...UA patterns to block`botWhitelist`RegExp\[\]Googlebot, Bingbot, ...Legit bots exempt from blocking`baseUrl`string`https://shugoi.com/api/v1`API base URL`internalUrl`string`baseUrl`Internal URL for server-to-server calls`autoInject`bool`true`Auto-inject guard scripts`csp`bool`true`Enable CSP header`splitRender`bool`true`Enable skeleton/eval injection`multiProcess`bool`false`Disk-based HTML storage for PM2`verifyBots`bool`true`Reverse DNS bot verification`debug`bool`false`Console logs`restrictedAccess`bool`false`Show restricted block page`blockStatus`int`403`HTTP status for blocks`locale`string-Block page language (`fr`/`en`)`extraDirectives`array-Additional CSP directives`blockPage`callable-Custom block page HTMLInternal route
--------------

[](#internal-route)

The middleware serves `/__shugoi/render` which returns stored HTML by token. This route MUST be excluded from the Shugoi middleware to avoid recursion.

For Laravel, we already handle this in the ServiceProvider. For standalone, add the route before the middleware.

Testing
-------

[](#testing)

```
$ curl http://localhost:3100/
+---------------------------------------------+
|           BLOCKED BY SHUGOI                 |
+---------------------------------------------+
|  Bots, scrapers and headless clients        |
|  are blocked by Shugoi protection.          |
|                                             |
|  Use a standard browser to access           |
|  this site.                                 |
|                                             |
|  - contact: support@shugoi.com -            |
+---------------------------------------------+
```

All automated requests (curl, wget, python, etc.) are blocked. Only legitimate browsers with proper fingerprint signals pass through the protection.

Architecture
------------

[](#architecture)

```
Request → Middleware → Core::evaluate()
  ├── Blocked → BLOCK_PAGE text or shield HTML + CSP
  └── Allowed → GuardInjector → store HTML → skeleton (eval bootcode)
       └── Browser executes skeleton → guards → rd() → render endpoint → HTML

```

License
-------

[](#license)

MIT

###  Health Score

21

—

LowBetter than 17% of packages

Maintenance65

Regular maintenance activity

Popularity2

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity11

Early-stage or recently created project

 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.

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/72387595?v=4)[RoxasYTB](/maintainers/RoxasYTB)[@RoxasYTB](https://github.com/RoxasYTB)

---

Top Contributors

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

### Embed Badge

![Health badge](/badges/shugoi-shugoi-php/health.svg)

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

PHPackages © 2026

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