Smart 404
Package docs status
Section titled “Package docs status”This page is generated from package source documentation in the Capell packages repository and the checked-in manifest. Source documentation is not distribution status. Before running a Composer command, verify that the exact package and compatible 1.x release are available through public Packagist or the authenticated marketplace account.
| Field | Value |
|---|---|
| Composer package | capell-app/smart-404 |
| Package slug | smart-404 |
| Product group | Capell Search & SEO |
| Tier | premium |
| Bundle | search-seo |
| Runtime contexts | admin, frontend, console |
| Capell version | ^1.0 |
| Catalogue role | extension |
| Release channel | Labs |
| Source repository | capell-app/packages |
| Source path | packages/smart-404 |
| Docs source | packages/smart-404/docs |
| Manifest | capell.json |
What This Plugin Adds
Section titled “What This Plugin Adds”Smart 404 is a premium Search and SEO extension that adds deterministic suggestions to frontend and static 404 documents while keeping the original HTTP 404 response.
- Status: Beta
Evidence: capell.json, src/Actions/ResolveSmart404SuggestionsAction.php, resources/views/widget.blade.php.
Why It Matters
Section titled “Why It Matters”For developers: The resolver ranks similar public URLs, then the deepest indexed ancestor and its direct children.
For teams: The feature does not redirect, track visitors, call an AI service, or expose authoring data.
Evidence: src/Support/RenderHooks/RegisterSmart404Hook.php, routes/web.php.
Screens And Workflow
Section titled “Screens And Workflow”Authentic desktop, mobile, and settings captures are deferred until a clean host application is available. See docs/screenshots.json.
Technical Shape
Section titled “Technical Shape”- Provider:
Capell\Smart404\Providers\Smart404ServiceProvider. - Settings: enabled and maximum suggestions, with config defaults for threshold, endpoint, timeout, and rate limit.
- Public route:
GET /smart-404/suggestions?path=...with current-origin, site, language, and indexability filtering. - External CSS and JavaScript assets use DOM creation and
textContent; timeout or malformed JSON hides the shell.
Data Model
Section titled “Data Model”The resolver returns immutable Smart404SuggestionData objects with translated titles and relative URLs. It consumes the shared Foundation registry and creates no Smart 404 content tables.
Install Impact
Section titled “Install Impact”- Required packages: Admin, Core, Discovery Foundation, and Frontend.
- Settings migration:
database/settings/2026_08_08_000001_create_smart_404_settings.php. - Frontend impact: an AfterContent hook on error responses only.
- Static errors: installation regenerates enabled site error documents when a static error store is configured.
Common Pitfalls
Section titled “Common Pitfalls”- The endpoint returns 404 when disabled, 422 for malformed paths, 429 when throttled, and 200 with an empty array when no suggestions qualify.
- Candidate URLs must be relative to the current origin and must not be noindex or from another site or language.
- Never change the 404 response to a redirect or query the database from the public Blade view.
Troubleshooting
Section titled “Troubleshooting”Check the Smart 404 health result for the AfterContent hook and the three public routes. If static hydration is empty, inspect the endpoint response and browser timeout rather than adding inline scripts.
Quick Start
Section titled “Quick Start”- Require and install
capell-app/smart-404. - Enable Smart 404 in the settings surface and choose a maximum of one to ten suggestions.
- Request a missing path and verify the response remains 404 while the suggestion list is present.