gaze-laravel

Laravel adapter for the gaze CLI contract.

gaze-laravel wraps the pipe-mode gaze clean / gaze restore workflow for Laravel apps. It sends raw UTF-8 text to clean, keeps the returned session_blob encrypted at rest, and restores model output through restore with typed exceptions and queue-aware retry helpers.

Use it when you need to:

• send pseudonymized text to an LLM instead of raw PII;
• restore model output back into owner-side text;
• keep encrypted session blobs out of logs and public component state;
• classify subprocess failures into caller, config, integrity, and infra buckets.

Detection modes: Regex + rulepack runs by default. Optional NER (ONNX-backed) is an opt-in second install — run php artisan gaze:install-ner to download model artifacts. See docs/ner.md for trade-offs.

New here? Start with the getting started guide.

Requirements

• PHP ^8.2
• Laravel ^11.0 || ^12.0
• The gaze binary on PATH, in vendor/bin/gaze, or configured via GAZE_BINARY

Install

composer require empiretwo/gaze-laravel
php artisan vendor:publish --tag=gaze-config
php artisan vendor:publish --tag=gaze-policy

The package ships as a Composer plugin (Naoray\GazeLaravel\Install\GazeInstallerPlugin). On first install your Composer will ask whether to allow it — pick y to enable automatic binary download, or pick n and provide GAZE_BINARY yourself.

Non-interactive (CI) installs: Composer 2.2+ requires plugins be allow-listed before they execute. Add this once before installing in CI:

composer config allow-plugins.empiretwo/gaze-laravel true

Or pre-seed composer.json:

"config": {
  "allow-plugins": {
    "empiretwo/gaze-laravel": true
  }
}

Without this, the binary auto-download step is silently skipped on first install.

Installer env overrides:

• GAZE_SKIP_BINARY_DOWNLOAD=1 — skip the download entirely when you manage the binary out-of-band.
• GAZE_VERSION=x.y.z — install a different gaze version than the one pinned by this release; use cautiously because the pinned version is contract-tested.
• GAZE_RELEASE_BASE=https://... — release base override for fixture or staging release hosts.

See Configuration for the full env var + config publishing reference.

Usage

use Naoray\GazeLaravel\Gaze;

$session = $gaze->clean($request->string('body'));
$reply = $llm->complete($session->cleanText);

return $gaze->restore($session, $reply);

See Exceptions for the exit bucket and typed exception reference.

See Testing for fakes, assertions, and integration-test setup.

Documentation

• Getting started
• Configuration
• Architecture
• Audit query / export
• Blob lifecycle
• NER install
• Livewire integration
• Conversational-loop patterns
• Operations
• Retry discipline
• Diagnostics
• Exceptions
• Queue integration
• Security model
• Testing

Security

Session blobs are encrypted at rest with Laravel's encrypter, keyed by GAZE_ENCRYPTION_KEY or APP_KEY. Only pseudonymized $session->cleanText should cross the model boundary; restore happens owner-side. See Security model for guarantees, responsibilities, and compliance boundaries.

Known limitations

• Pre-built binary auto-downloads currently cover Linux x86_64 and macOS arm64. Intel Mac users must install gaze from source and set GAZE_BINARY.
• NER model artifacts are not bundled in the Composer package. Install them explicitly with php artisan gaze:install-ner when you need NER-backed detection.

License

Apache-2.0 — see LICENSE.