Download the PHP package webcrafts-studio/lens-for-laravel without Composer

Lens for Laravel

A local-first accessibility auditor for Laravel applications.

Lens for Laravel scans your application with axe-core, renders JavaScript through Spatie Browsershot, maps violations back to source files, and can generate AI-assisted fixes for Blade, React, and Vue code.

v3.5 development line: adds an optional explicit AI model override and dashboard info about the active AI Fix model. The v3.4 authenticated scans, additional providers, v3.3 Ollama support, and earlier v3 foundations remain unchanged.

v3.4: adds authenticated scans for pages behind login plus four additional AI Fix providers (OpenRouter, xAI, DeepSeek, Mistral).

v3.3: adds local AI Fix models through Ollama.

Documentation & full feature overview -> lens.webcrafts.pl

Features

• Axe-core scanning - WCAG 2.x and best-practice checks through the industry-standard axe engine.
• Selectable WCAG standard - run cumulative WCAG 2.0, 2.1, or 2.2 rule sets in the dashboard and CLI; 2.0 remains the default for backward compatibility.
• JavaScript rendering - scans the hydrated browser DOM through Browsershot/Chromium.
• Blade, Livewire, React, and Vue source locator - maps DOM violations back to resources/views/**/*.blade.php and frontend files under resources/js, using named Blade routes, nested element signatures, nearby selector context, rendered filenames, and positional hints to disambiguate dynamic or repeated elements.
• Source type labels - results include sourceType values: blade, react, or vue.
• Inertia-aware file discovery - React/Vue pages under resources/js/Pages/** are included automatically.
• Optional AI Fix assistant - on PHP 8.3+ and Laravel 12+, generates reviewable fixes for Blade, React, and Vue through Gemini, OpenAI, Anthropic, OpenRouter, xAI, DeepSeek, Mistral, or a local Ollama model using the optional laravel/ai SDK.
• Editable AI Fix review - inspect the live diff, edit the replacement with line numbers and indentation shortcuts, or restore the original AI proposal before applying.
• Progressive Fix All A/AA queues - generate up to three suggestions concurrently, review ready fixes while later items continue loading, and apply every ready suggestion with one bulk action.
• Honest AI verification state - applied suggestions remain counted and are marked as pending until a fresh axe-core scan verifies the result.
• Fresh re-scans - cache-busted browser navigation and current-result action identities prevent stale markup or late AI responses from remaining attached to an older issue.
• Whole-site crawler - discovers pages from sitemaps and internal links.
• SPA crawler mode - optionally renders JavaScript while crawling React/Vue/Inertia apps.
• Multi-URL scans - scan selected URLs in a single dashboard or CLI run.
• Interactive state scans - execute clicks, waits, typing, select changes, and checkbox states before scanning.
• Authenticated scans - scan pages behind login by impersonating an existing user id resolved server-side (--as-user, dashboard user ID field); raw cookies and passwords are never accepted.
• Local HTTPS support - optionally ignore self-signed certificate errors in local environments.
• Scan history - stores scan runs, issue counts, affected URLs, source locations, and trend data.
• URL-aware scan comparison - compare two historical scans by rule, normalized URL, interactive state, and selector to see new, fixed, and remaining issues without conflating the same selector across pages.
• Baseline quality gate - fail CI only when new accessibility regressions appear.
• Element preview - screenshot the page with the failing element highlighted.
• PDF reports - export audit results as a PDF.
• CLI audits - run php artisan lens:audit with WCAG selection, reusable state scripts, crawl mode, thresholds, and baseline gates.
• IDE links - open source locations in VS Code, Cursor, PhpStorm, or Sublime Text.
• Developer dashboard - zero build step dashboard using Alpine.js and Tailwind CSS via CDN.
• Five interface languages - package-owned dashboard, history, comparison, modal, recorder, PDF, and error text in English, Polish, Spanish, French, and German.

Requirements

Lens uses Browsershot to control Chromium. Install Puppeteer in the host application:

If your environment requires a custom Chromium, Node, or npm path, configure Browsershot through your application environment as you normally would.

AI Fix has a narrower runtime matrix than the core scanner:

Laravel 10/11 and PHP 8.2 applications retain scanning, crawling, history, PDF, preview, source location, interactive states, and CLI support. The dashboard hides AI Fix actions and explains why they are unavailable.

Installation

Install Lens as a development dependency:

The service provider is auto-discovered.

The core package intentionally does not require an AI SDK. On a supported runtime, install AI Fix separately when you want generated fixes:

AI Fix is optional. Lens continues to work without this package.

Run migrations if you want scan history:

Publish the config when you want to customize behavior:

Optionally publish package views:

Quick Start

Start your Laravel app and open:

Enter a URL from the same host as APP_URL, then run a scan. Results include:

• WCAG level and impact
• failing DOM snippet
• CSS selector
• source file, line number, and source type when located
• Deque/WCAG documentation links

Choose WCAG 2.0, 2.1, or 2.2 before starting the scan. Later versions include the rules from earlier versions plus axe-core rules for the newer success criteria. Existing installations continue to default to WCAG 2.0.

• element preview screenshot
• optional AI fix workflow

Supported Frontends

Blade

Blade support is the most direct path. Lens scans the rendered DOM and searches resources/views/**/*.blade.php for matching elements, IDs, names, classes, attributes, and selectors.

Since v3.2, the Blade locator also:

• resolves a rendered local URL back to its named Laravel route and matches helpers such as route('home')
• keeps attributes from nested DOM children separate from the failing element
• compares bounded multiline element content, including recognizable descendant filenames and classes
• uses nearby ancestor classes and IDs from the axe selector to distinguish similar elements

AI Fix can modify located .blade.php files under resources/views.

Livewire

Livewire works through the rendered DOM and the same structural Blade source locator, including named route helpers, nested markup, and nearby selector context. For delayed hydration or UI updates, use:

Automated scans only inspect the current browser state after page load. Interactive states such as open modals, validation errors, dropdowns, and tabs still need targeted URLs or manual review.

React

Lens locates React source files under:

It supports common JSX/TSX patterns such as:

• static attributes: id="logo", name="email"
• JSX expressions: href={'/pricing'}
• className
• selector variants like primary-button, primaryButton, and PrimaryButton
• dynamic props when nested source markup and nearby selector context provide a stable match
• Inertia pages under resources/js/Pages/**

AI Fix can modify supported React files under resources/js.

Vue

Lens locates Vue single-file components under:

It supports common Vue template patterns such as:

• static attributes: class="logo", href="/pricing"
• bindings: :href="'/pricing'", v-bind:href="'/pricing'"
• class object keys: :class="{ active: isActive }"
• dynamic bindings when nested source markup and nearby selector context provide a stable match

AI Fix can modify .vue files under resources/js.

Inertia

Inertia React and Vue apps are supported through the React/Vue source locators. For route discovery in SPA-heavy apps, enable JavaScript crawling:

Dashboard

The dashboard has two primary tabs.

Scanner

Run scans in four modes:

• single URL
• multiple URLs
• whole website crawl
• interactive states

Each issue can be expanded to inspect the failing node, copy the selector, preview the element, open the source file in your editor, or request an AI fix.

Interactive state scans can be recorded visually in the dashboard. Click Record to open a recorder window, interact with the target page, create named states as you move through the flow, and send the generated script back to Lens. You can also paste or edit the raw script directly. The generated format stays copyable and CI-friendly:

Supported actions are click, type, select, check, uncheck, and wait.

Save the same script in a file to run it from the CLI:

Interactive-state CLI scans support WCAG selection, level filters, thresholds, and baselines. They require one URL and cannot be combined with --crawl.

History

History stores scan runs and issue metadata in your database. It supports:

• paginated scan history
• trend chart for recent scans
• scan details
• deleting old scans
• comparing two scans to identify new, fixed, and remaining issues

Artisan Command

Run audits from the terminal:

The CLI uses the same scanner, crawler, interaction-script parser, source locator, and source type metadata as the dashboard. State labels are printed in the diagnostic table and preserved in baselines.

--wcag=2.0, --wcag=2.1, and --wcag=2.2 select the standard version. This is independent from --a, --aa, and --all, which select the conformance levels shown in the result. The default standard is WCAG 2.0. When changing the standard used by a baseline workflow, create a fresh reviewed baseline.

Baseline Quality Gate

Use the baseline gate when an existing application already has accessibility issues and you want CI to block only new regressions.

By default, Lens stores the baseline in:

The comparison uses stable fingerprints based on the rule, normalized URL path, selector, and source file when available, so a different local or CI host does not invalidate the baseline.

Local HTTPS Certificates

For local environments with self-signed certificates, such as DDEV or Laravel Valet, enable:

The default is false, so production-like scans stay strict unless you explicitly opt in.

Configuration

Published config file:

Environment Options

Set LENS_FOR_LARAVEL_IGNORE_HTTPS_ERRORS=true only for trusted local environments with self-signed certificates. Since v3.0 the setting consistently covers axe scans, sitemap and page requests made by the crawler, optional JavaScript-rendered crawling, and element preview screenshots. Its default remains false.

Authenticated scans

Pages behind login can be scanned by impersonating an existing user of the host application:

The dashboard shows a user ID field when the feature is enabled; crawling, state scans, and element previews accept the same user. Only the numeric id travels from the client - Lens logs in server-side through the configured guard and passes a short-lived session cookie to Chromium. Raw cookies, tokens, and passwords are never accepted, logged, or stored in history, and the previous auth state is restored after the scan. Authenticated scans require a persistent session driver (file, database, or redis); the array driver cannot share sessions with the scanner browser. When LENS_FOR_LARAVEL_AUTH_ALLOWED_IDS is set, only those ids may be used.

Interface languages

Version 3 ships complete package-owned interface catalogs for English, Polish, Spanish, French, and German. The selected language covers the scanner, history and URL-aware comparisons, AI Fix editor and Fix All queue, preview modals, interactive-state recorder, PDF reports, chart labels, and package-generated browser, route, interaction-script, baseline, and CLI error messages. The dashboard language switcher stores its choice in the session; exported PDF reports use that same language. Console errors use the Laravel application locale active for the command.

locale defines the initial language, fallback_locale is used when a translation is unavailable, and supported_locales controls the choices displayed in the dashboard. Accessibility-rule descriptions returned by axe-core and framework validation messages can still follow the language supplied by those upstream libraries rather than Lens's catalog.

Supported editors:

• vscode
• cursor
• phpstorm
• sublime
• none

Supported AI providers:

• gemini
• openai
• anthropic
• ollama
• openrouter
• xai
• deepseek
• mistral

Disable AI Fix explicitly while keeping all scanning features enabled:

Crawling

Whole-site scans discover URLs in this order:

1. sitemap.xml
2. sitemap_index.xml
3. sitemaps/sitemap.xml
4. internal <a href> links

By default, crawling uses Laravel's HTTP client and parses the initial HTML. This is fast and works well for Blade, Livewire, and server-rendered pages.

For SPA or Inertia apps where links are rendered after JavaScript hydration:

With that enabled, Lens attempts to render each crawled page in Chromium and collect links from the hydrated DOM. If browser crawling fails or finds no links, it falls back to the HTTP crawler.

Limit the crawl size with:

AI Fix

AI Fix is available only when all of the following are true:

• PHP 8.3 or newer
• Laravel 12 or newer
• the optional laravel/ai package is installed
• LENS_FOR_LARAVEL_AI_ENABLED is not set to false

On older supported applications, only AI Fix is disabled. The accessibility scanner and every non-AI feature remain available.

The AI Fix workflow:

1. Lens locates the source file and line.
2. It extracts the smallest relevant element or component instead of an arbitrary line window.
3. It sends the issue, failing DOM snippet, WCAG tags, and selected source fragment to the configured AI provider.
4. A dedicated accessibility agent returns a minimal replacement and explanation.
5. The dashboard shows a diff preview.
6. You can accept the proposal as generated or edit it directly in the modal. The built-in editor includes line numbers, indentation shortcuts, a live diff, and an option to restore the AI version.
7. Fix All A and Fix All AA create review queues for every located issue at the selected level. Lens generates up to three suggestions concurrently, opens the queue immediately, and lets you move between ready suggestions while later items continue loading. One bulk action then applies every ready suggestion with its reviewed or edited code, and per-item failures are reported without stopping the rest.
8. Each queued fix keeps its own generated, edited, rejected, failed, or applied state. A failed suggestion can be retried without restarting the rest of the queue.
9. Lens applies each reviewed replacement after running the same path and dangerous-code checks for both generated and edited proposals.
10. The issue is immediately marked AI Fix applied - pending re-scan while remaining in the violation counts until a new axe-core scan verifies the result.

Since v3.0, the agent uses a 12000-token output ceiling and a reduced Gemini thinking budget, and leaves temperature at the provider default so models without temperature support keep working. Gemini, OpenAI, Anthropic, OpenRouter, xAI, DeepSeek, and Mistral use the default model configured in laravel/ai unless LENS_FOR_LARAVEL_AI_MODEL sets an explicit model at your own responsibility. In v3.3, Ollama can use the exact local model tag from LENS_FOR_LARAVEL_AI_OLLAMA_MODEL; when both model settings are empty, the Laravel AI SDK default is used. The dashboard reports whether AI Fix uses the default AI SDK model or a manually configured model name. If the provider reaches its token limit or returns malformed structured output, Lens performs one controlled retry. Persistent failures produce a safe, understandable message; provider, resolved model, finish reason, and token usage are recorded in the application log without logging the submitted source fragment.

Privacy: AI Fix sends the failing DOM snippet, accessibility issue details, WCAG tags, and a bounded element/component source fragment to the configured provider. With Ollama's default localhost endpoint, this data stays on the machine running the Laravel application. A remote Ollama endpoint and cloud providers receive that bounded context over the network. Lens does not send the entire repository; review the selected context for secrets or sensitive information before requesting a fix.

Configure provider credentials:

To use a specific model instead of the SDK default, set an explicit model at your own responsibility (for example gpt-5.6-luna for OpenAI). An empty value keeps the SDK default behavior.

To run AI Fix locally, install Ollama, then pull a code-capable model:

Ollama serves http://127.0.0.1:11434 by default, so the URL can normally be omitted. laravel/ai 0.3.x names the optional URL override OLLAMA_BASE_URL; current releases use OLLAMA_URL. The selected model must already be present in ollama list. Larger code models can improve suggestions but require more memory and take longer to answer.

To test the full local workflow, run curl http://127.0.0.1:11434/api/tags, clear Laravel's cached configuration with php artisan optimize:clear, and add a known violation such as <img src="logo.png"> to a rendered page. Scan it in the dashboard, request AI FIX, and verify that storage/logs/laravel.log records provider ollama and the selected model without recording the source fragment. Review and apply the proposal, confirm the issue stays marked as pending, then re-scan to let axe-core verify the result.

Supported writable files:

• resources/views/**/*.blade.php
• resources/js/**/*.js
• resources/js/**/*.jsx
• resources/js/**/*.ts
• resources/js/**/*.tsx
• resources/js/**/*.vue

AI Fix does not write outside those paths.

IDE Integration

When a source location is found, click it in the dashboard to open your editor at the exact line.

Use none to disable editor links:

Scan Output

Each issue includes fields like:

sourceType can be:

• blade
• react
• vue
• null when no source location is found

Security

Lens is intended for local and controlled development environments.

Built-in protections:

• Dashboard access is restricted by enabled_environments.
• Scan URLs must use HTTP or HTTPS.
• Scan URLs must match the host configured in APP_URL.
• External domain scanning is blocked.
• AI Fix apply rejects path traversal.
• AI Fix writes only to supported Blade/React/Vue source paths.
• AI Fix blocks generated code containing server-side execution functions such as shell_exec, system, exec, passthru, proc_open, popen, and eval.
• AI Fix blocks newly introduced raw PHP open tags unless they were already present in the original code block.
• Authenticated scans accept only a numeric user id; login happens server-side, session cookies are short-lived and never logged or stored, and the previous auth state is restored after the scan.
• Fix writes use LOCK_EX.
• Scan, crawl, preview, fix, history, and report endpoints use throttling where appropriate.

Recommended production posture:

If you enable Lens on staging, protect the route with authentication middleware:

Known Limitations

axe-core automates many high-confidence accessibility checks, but neither axe-core nor Lens can determine full WCAG conformance. A clean scan is evidence from automated checks, not proof that the application is fully accessible.

Source location is heuristic. Lens can locate many common Blade, Livewire, React, Vue, and Inertia patterns, but it may miss or misidentify:

• deeply abstracted components
• custom components that render HTML internally, such as <LogoImage />
• dynamic class builders with no literal class or recognizable variant
• CSS module keys that do not resemble the final generated class
• runtime-generated attributes without a named Blade route, recognizable nested markup, or stable selector context
• elements rendered only after user interaction

For interactive states, run targeted scans after exposing the state, add dedicated URLs, or combine Lens with manual QA.

Always complement Lens with:

• keyboard navigation testing
• screen reader testing with NVDA, JAWS, or VoiceOver
• manual form validation checks
• modal, menu, dropdown, accordion, and tab interaction checks
• cognitive and usability review

Upgrade Notes for v3.0 through v3.5

v3.5 is the current development line. Its new features are an optional explicit AI model override and dashboard info about the active AI Fix model. It requires no migration.

New in v3.5:

• LENS_FOR_LARAVEL_AI_MODEL optionally pins an explicit model for any provider at your own responsibility; when it is empty, cloud providers keep the SDK default and Ollama falls back to LENS_FOR_LARAVEL_AI_OLLAMA_MODEL
• the new providers keep the same implicit SDK-default model behavior as Gemini, OpenAI, and Anthropic unless LENS_FOR_LARAVEL_AI_MODEL sets an explicit model; Ollama still accepts its explicit model tag
• the dashboard reports whether AI Fix uses the default AI SDK model or a manually configured model name
• Fix All queues gained an apply-all action that writes every ready suggestion at once, using each item's reviewed or edited code; previously each ready suggestion had to be accepted individually; per-item failures (for example stale source after an earlier apply in the same file, or rate limiting with one wait-and-retry) are reported without stopping the rest
• the accessibility agent no longer pins temperature to 0, so models without temperature support (for example gpt-5.6-luna) stop failing with a provider error; generation uses the provider default temperature

If the Lens config was published before v3.5, add:

v3.4 added authenticated scans for pages behind login and four additional AI Fix providers. It requires no migration.

New in v3.4:

• openrouter, xai, deepseek, and mistral are accepted by LENS_FOR_LARAVEL_AI_PROVIDER
• configure credentials with OPENROUTER_API_KEY, XAI_API_KEY, DEEPSEEK_API_KEY, or MISTRAL_API_KEY in the host application
• LENS_FOR_LARAVEL_AUTH_ENABLED=true enables scanning as an existing user (default false)
• LENS_FOR_LARAVEL_AUTH_GUARD selects the session guard used for login (default web)
• LENS_FOR_LARAVEL_AUTH_ALLOWED_IDS optionally restricts impersonation to a comma-separated id list
• php artisan lens:audit --as-user=1 scans single URLs, crawls, and state scripts as that user
• the dashboard, crawler, state scans, and element previews accept the same server-resolved user id
• authenticated scans require a persistent session driver (file, database, or redis)

If the Lens config was published before v3.4, add:

v3.3 added local AI Fix models through Ollama. It requires no migration.

New in v3.3:

• ollama is accepted by LENS_FOR_LARAVEL_AI_PROVIDER
• LENS_FOR_LARAVEL_AI_OLLAMA_MODEL selects an installed Ollama model tag
• LENS_FOR_LARAVEL_AI_OLLAMA_TIMEOUT allows slower local generation and defaults to 120 seconds
• local generations keep the same bounded source context, structured response, one-retry policy, review diff, apply safeguards, and pending re-scan state as cloud providers

If the Lens config was published before v3.3, add:

New in v3.2:

• local rendered URLs can map back to named Laravel routes such as route('home') in Blade and Livewire views
• failing DOM attributes are read from the target opening tag without treating nested child attributes or classes as target attributes
• bounded multiline element and descendant signatures map nested Blade, React, and Vue markup
• nearby ancestor selector context distinguishes repeated dynamic elements while preserving React/Vue precedence in mixed applications

Added in v3.1:

• reviewable AI Fix proposals with in-modal editing, indentation shortcuts, live diff updates, keyboard apply, and restore-to-AI controls
• progressive Fix All queues for WCAG A and AA, with three concurrent generations, per-item loading and error states, navigation, editing, rejection, retry, and apply controls
• fresh cache-busted browser navigation on every re-scan, with result actions rebound to the current issue list and superseded AI requests cancelled
• more precise repeated-element source mapping using rendered filenames and numeric :nth-child(...) positions

The v3.0 foundation includes:

• selectable WCAG 2.0, 2.1, and 2.2 standards in the dashboard and CLI
• WCAG 2.0 as the backward-compatible default
• persisted WCAG version metadata in scan history, comparisons, baselines, and PDF reports
• URL-aware history comparisons that distinguish identical rules and selectors on different pages
• reusable interactive-state scripts in the CLI through --states=path
• consistent ignore_https_errors handling for scans, HTTP/browser crawling, and previews
• core support for PHP 8.2+ and Laravel 10-13
• AI Fix isolated as an optional feature requiring PHP 8.3+, Laravel 12+, and laravel/ai
• stabilized AI Fix with semantic source fragments, minimal replacements, bounded Gemini thinking, one controlled structured-output retry, safe errors, and provider/model/token diagnostics
• immediate pending-verification status on issues changed by AI Fix, without claiming success before a new axe-core scan
• complete English, Polish, Spanish, French, and German catalogs for package-owned dashboard, history, comparison, modal, PDF, and error text

After upgrading from v2 to v3.0:

If you published the config before v3.0.0, add:

Install the optional AI SDK only on a supported runtime when AI Fix is needed:

Historical: Upgrade Notes for v2.0.0

Version 2 adds major frontend support and persistence features:

• React source locating and AI Fix
• Vue source locating and AI Fix
• Inertia-friendly source discovery
• sourceType metadata
• scan history tables
• scan comparison
• SPA crawler option
• scan wait option

After upgrading:

If you already published the config, manually add:

Testing This Package

License

The MIT License (MIT). See LICENSE.md for details.