Laravel Unique Urls Laravel Package

Product Decisions This Supports

• URL/slug architecture and SEO strategy — the package owns the "one canonical, unique URL per model" concern, so decisions about permalink structure, slug generation and route-to-model resolution don't get re-implemented per feature team.
• Modular monolith vs. single app/ layout — v2.2.0 makes urls:generate and urls:doctor module-aware out of the box (nwidart/laravel-modules layouts plus the legacy Models/Entities conventions, or an explicit model_paths map). Adopting a module structure is no longer a silent regression for URL coverage.
• Build vs. buy for URL management — the package bundles generation, uniqueness guarantees, handler/strategy conventions and a diagnostic command. Buying (adopting) is justified unless you need CMS-grade routing, redirect history at scale, or are off Laravel.
• Release/QA gating as a roadmap item — urls:doctor --strict turns empty or partial scans into a non-zero exit code, making "every model has a reachable, unique URL" a CI-enforceable invariant rather than a manual QA checklist item.
• Migrations and refactors — models moving between App\Models and Modules\* now keep working via bare-name fallback in --model; ambiguous short names fail loudly with candidates listed instead of resolving arbitrarily. This de-risks the "extract a module" roadmap item.
• Observability of technical debt — the doctor now names individual paths that resolve to zero models, surfacing wrong directories or PSR-4/namespace mismatches that previously read as health. A PM can use the reported counts ("checked 12 models in 2 paths") as a concrete coverage metric in release notes and status reports.

When to Consider This Package

Consider adoption when:

• You are on Laravel and models need human-readable, guaranteed-unique URL segments tied to application routes.
• Your codebase is already modular, or heading there — this release removes the previous blind spot; without it, module-hosted models silently escaped both generation and diagnostics.
• You want URL correctness to be a CI gate (--strict) rather than a post-deploy discovery.
• Your URL handling already follows, or can follow, the package's conventions: a urlHandler() controller resolved through Laravel's ControllerResolver (Livewire __invoke() style, or a declared method with show()/index() fallbacks) and a urlStrategy() for slug derivation.
• You need predictable failure semantics — an unresolvable controller dependency or uninstantiable model is now recorded as an error instead of aborting the run and costing coverage of every subsequent model.

Look elsewhere when:

• You need a full routing/CMS layer with redirect chains, localisation of slugs, sitemaps, or editorial URL management — this is a model-level URL uniqueness tool, not a content routing platform.
• You are not on Laravel, or you resolve controllers outside Laravel's container (the new handler validation is explicitly tied to ControllerResolver).
• You rely on urlStrategy() throwing to signal problems — failures there are deliberately silent, so anything you need alerted on must be surfaced through another layer.
• You require the doctor to validate slug generation itself; it validates discovery, handler resolution and model instantiation, and intentionally ignores strategy failures caused by empty instances.

How to Pitch It (Stakeholders)

For executives: This release hardens the layer that decides what URL every record in the product gets. The material business value is twofold: SEO and link integrity (unique, resolvable URLs per model) and reduced release risk — URL coverage is now checkable in CI, and a clean run reports exactly how many models across how many paths were verified instead of a bare "Everything is ok." The upgrade is non-breaking: no configuration change is required, and the new scan is a superset of the old app/-only behaviour.

For engineering: v2.2.0 fixes three real defects rather than adding surface area. (1) ModelDiscoveryService resolves scan directories alongside their PSR-4 root and namespace prefix, defaulting to app/ plus configured module paths, with a new model_paths key that accepts a bare directory, a Namespace => /directory pair, or a full path/base_path/namespace descriptor — non-existent directories are skipped. (2) urls:doctor now distinguishes "clean" from "nothing checked": it names any path yielding zero models, warns when the whole scan is empty, and --strict converts either condition into a CI failure. (3) --model is now uniform across both commands — fully qualified names work, bare names resolve against App\Models then fall back to discovered models, ambiguity is reported with candidates, and missing classes are errors rather than container exceptions. Handler validation now mirrors request-time resolution via ControllerResolver (including __invoke(), show()/index() fallbacks and Livewire component names), and trait detection uses class_uses_recursive() so inherited usage is covered.

Expectation to set before upgrading: projects that have already moved models into modules should anticipate urls:doctor reporting more findings than before. That is the previous blind spot becoming visible, not a regression — budget a short remediation pass, then enable --strict in CI to keep it closed.