PHPackages                             spyglasses/spyglasses - 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. [Logging & Monitoring](/categories/logging)
4. /
5. spyglasses/spyglasses

ActiveDrupal-module[Logging & Monitoring](/categories/logging)

spyglasses/spyglasses
=====================

Spyglasses AI Traffic Analytics for Drupal - Detect, block and log your website's AI traffic using Drupal's middleware API.

v1.0.13(9mo ago)024GPL-2.0-or-laterPHPPHP >=7.4

Since Sep 15Pushed 9mo agoCompare

[ Source](https://github.com/orchestra-code/spyglasses-drupal)[ Packagist](https://packagist.org/packages/spyglasses/spyglasses)[ Docs](https://www.spyglasses.io)[ RSS](/packages/spyglasses-spyglasses/feed)WikiDiscussions main Synced today

READMEChangelogDependencies (1)Versions (15)Used By (0)

Spyglasses for Drupal
=====================

[](#spyglasses-for-drupal)

[![License: GPL v2+](https://camo.githubusercontent.com/4c3bbb2162df305f1122d9aecffe3ac70c0464a1a77ba5b35bb83269084815a4/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4c6963656e73652d47504c25323076322b2d626c75652e737667)](https://www.gnu.org/licenses/gpl-2.0)[![Drupal](https://camo.githubusercontent.com/e1695958ecbd946b03cfbbe082d3672dcdb5554ec6ae87b71ad3f0260efe1d29/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f44727570616c2d3825323025374325323039253230253743253230313025323025374325323031312d626c7565)](https://www.drupal.org)

Spyglasses provides AI traffic analytics for Drupal by detecting, blocking, and logging bot traffic from AI assistants and crawlers using Drupal's middleware API.

Features
--------

[](#features)

- **AI Bot Detection**: Detect traffic from ChatGPT, Claude, Perplexity, and other AI assistants
- **AI Referrer Tracking**: Track visitors coming from AI platforms
- **Model Training Crawler Detection**: Identify and optionally block AI training crawlers like GPTBot, CCBot, and ClaudeBot
- **Middleware-Based**: Uses Drupal's StackPHP middleware for high-performance request processing
- **Configurable Blocking**: Block or allow specific bots based on your preferences
- **Real-time Analytics**: Log all detected traffic to the Spyglasses platform for analysis
- **Automatic Pattern Updates**: Keep bot detection patterns up-to-date automatically
- **Cache-Aware**: Properly handles caching to avoid false positives

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

[](#installation)

### Via Composer (Recommended)

[](#via-composer-recommended)

```
composer require spyglasses/drupal
```

### Manual Installation

[](#manual-installation)

1. Download the module from [GitHub](https://github.com/orchestra-code/spyglasses-drupal)
2. Extract to your `modules/contrib` directory
3. Enable the module via Drupal admin or drush:

```
drush en spyglasses
```

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

[](#configuration)

### 1. Get Your API Key

[](#1-get-your-api-key)

Sign up for a free account at [spyglasses.io](https://www.spyglasses.io) to get your API key.

### 2. Configure the Module

[](#2-configure-the-module)

1. Navigate to **Configuration > Web Services > Spyglasses** (`/admin/config/services/spyglasses`)
2. Enter your API key
3. Configure your settings:
    - **Debug Mode**: Enable for troubleshooting (logs detailed information)
    - **Auto-sync Patterns**: Automatically update bot patterns daily
    - **Advanced Settings**: Customize endpoints and cache settings if needed

### 3. Sync Patterns

[](#3-sync-patterns)

Click "Sync Patterns Now" to fetch the latest bot detection patterns from the Spyglasses API.

How It Works
------------

[](#how-it-works)

Spyglasses uses Drupal's middleware API to intercept HTTP requests early in the request lifecycle. For each request:

1. **Pattern Matching**: Checks the User-Agent against known AI bot patterns
2. **Referrer Detection**: Analyzes the HTTP Referer for AI platform origins
3. **Blocking Decision**: Applies your blocking rules (if configured)
4. **Logging**: Sends detection data to Spyglasses for analytics
5. **Cache Headers**: Sets appropriate cache headers to prevent false positives

### Detected Traffic Types

[](#detected-traffic-types)

- **AI Assistants**: ChatGPT-User, Claude-User, Perplexity-User, etc.
- **AI Crawlers**: GPTBot, ClaudeBot, CCBot, Applebot-Extended, etc.
- **AI Referrers**: Traffic from chat.openai.com, claude.ai, perplexity.ai, etc.

Performance
-----------

[](#performance)

- **Minimal Overhead**: Middleware runs before full Drupal bootstrap
- **Efficient Caching**: Patterns cached for 24 hours by default
- **Non-blocking Logging**: API calls don't slow down your site
- **Smart Exclusions**: Skips static files and admin pages automatically

Blocking Configuration
----------------------

[](#blocking-configuration)

Configure blocking rules in your Spyglasses dashboard:

- **Block AI Model Trainers**: Block crawlers that train AI models
- **Custom Block Rules**: Block specific bots, categories, or patterns
- **Custom Allow Rules**: Always allow specific bots (overrides blocks)

Debugging
---------

[](#debugging)

Enable debug mode in the module settings to see detailed logs:

```
# View Drupal logs
drush watchdog:show --filter=spyglasses

# Or check the database
SELECT * FROM watchdog WHERE type = 'spyglasses' ORDER BY timestamp DESC;
```

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

[](#requirements)

- **Drupal**: 8.8+ | 9.x | 10.x | 11.x
- **PHP**: 7.4+
- **Extensions**: cURL, JSON
- **Permissions**: `administer site configuration` to configure

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

[](#compatibility)

### Cache Compatibility

[](#cache-compatibility)

- **Drupal Core Cache**: ✅ Full support
- **Varnish**: ✅ Uses Vary headers
- **Cloudflare**: ✅ Compatible
- **Redis/Memcache**: ✅ Compatible

### Module Compatibility

[](#module-compatibility)

- **BigPipe**: ✅ Compatible
- **Dynamic Page Cache**: ✅ Compatible
- **Internal Page Cache**: ✅ Compatible
- **Ban Module**: ✅ Can be used together

API Reference
-------------

[](#api-reference)

### Services

[](#services)

```
// Get the Spyglasses client
$client = \Drupal::service('spyglasses.client');

// Detect bot traffic
$result = $client->detect($user_agent, $referrer);

// Sync patterns manually
$sync_service = \Drupal::service('spyglasses.pattern_sync');
$sync_service->syncIfNeeded();
```

### Configuration

[](#configuration-1)

```
// Get configuration
$config = \Drupal::config('spyglasses.settings');
$api_key = $config->get('api_key');
$debug_mode = $config->get('debug_mode');
```

Troubleshooting
---------------

[](#troubleshooting)

### Common Issues

[](#common-issues)

**No API Key Error**

- Ensure your API key is set in the configuration
- Check that the key doesn't contain invalid characters

**Patterns Not Syncing**

- Verify your API key is valid
- Check network connectivity to spyglasses.io
- Enable debug mode to see detailed error messages

**High Memory Usage**

- Reduce cache TTL if you have many patterns
- Check for conflicting modules that might interfere

### Debug Information

[](#debug-information)

```
# Check module status
drush pm:list | grep spyglasses

# View recent logs
drush watchdog:show --filter=spyglasses --count=20

# Clear caches
drush cache:rebuild

# Test pattern sync
drush php:eval "\Drupal::service('spyglasses.pattern_sync')->syncIfNeeded();"
```

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

[](#development)

### Running Tests

[](#running-tests)

```
# PHPUnit tests
vendor/bin/phpunit modules/contrib/spyglasses/tests/

# Code standards
vendor/bin/phpcs --standard=Drupal modules/contrib/spyglasses/
```

### Contributing

[](#contributing)

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

Security
--------

[](#security)

This module processes HTTP requests and makes external API calls. Security considerations:

- **API Key**: Store securely, never commit to version control
- **Input Validation**: All user input is sanitized
- **HTTPS**: All API communication uses HTTPS
- **Permissions**: Requires admin permissions to configure

Support
-------

[](#support)

- **Documentation**: [docs.spyglasses.io](https://www.spyglasses.io/docs/platforms/drupal)
- **Issues**: [GitHub Issues](https://github.com/orchestra-code/spyglasses-drupal/issues)
- **Email**:
- **Community**: [Drupal.org](https://www.drupal.org/project/spyglasses)

License
-------

[](#license)

This project is licensed under the GPL-2.0-or-later license. See the [LICENSE](LICENSE) file for details.

---

Made with ❤️ by [Orchestra AI](https://www.spyglasses.io)

###  Health Score

30

—

LowBetter than 62% of packages

Maintenance56

Moderate activity, may be stable

Popularity6

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity44

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 ~0 days

Total

14

Last Release

289d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/234620130ee10b051af10cd66b794c208b087b59b8b2bcf361807188c6ce319e?d=identicon)[spyglasses](/maintainers/spyglasses)

---

Top Contributors

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

---

Tags

middlewareaidrupalcrawleranalyticsbotdetectionclaudeChatGptperplexity

### Embed Badge

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

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

###  Alternatives

[helsingborg-stad/municipio

A bootstrap theme for creating municipality sites.

4028.5k10](/packages/helsingborg-stad-municipio)[sbsaga/toon

🧠 TOON for Laravel — a compact, human-readable, and token-efficient data format for AI prompts & LLM contexts. Perfect for ChatGPT, Gemini, Claude, Mistral, and OpenAI integrations (JSON ⇄ TOON).

6753.8k](/packages/sbsaga-toon)[claude-php/claude-php-sdk-laravel

Laravel integration for the Claude PHP SDK - Anthropic Claude API

5223.2k](/packages/claude-php-claude-php-sdk-laravel)

PHPackages © 2026

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