Sharp Ohdear Broken Links Laravel Package

Getting Started

• composer require code16/sharp-ohdear-broken-links — this is a Sharp extension, so you must already have code16/sharp installed and a working Sharp admin (a SharpServiceProvider, at least one entity/menu entry, and an authenticated guard).
• Publish and inspect the config before writing any code: php artisan vendor:publish --provider="Code16\SharpOhdearBrokenLinks\SharpOhdearBrokenLinksServiceProvider" (check the provider for the exact tag), then read config/sharp-ohdear-broken-links.php top to bottom. The two things you cannot guess are the Oh Dear API token and the Oh Dear site/monitor ID — the package needs both to fetch anything.
• Put credentials in .env (OHDEAR_API_TOKEN, site ID) rather than the config file, and add them to your deployment secrets. The token is a per-team Oh Dear API token, not a per-site one.
• Register the package's Sharp menu entry in config/sharp.php (or in your SharpServiceProvider::buildMenu()), typically alongside your existing entities. The natural first use case: open Broken links in the Sharp sidebar, see the current 404 list pulled from Oh Dear, and click through to the Sharp form of the entity that owns the broken URL so an editor can fix or redirect it.
• If your Sharp entities are not yet wired to the package's link-resolution config, expect an empty or link-less list on first load — resolve that mapping first (see below) before assuming the integration is broken.

Implementation Patterns

• Resolution mapping is the core of the integration. The package fetches URLs; Sharp knows about entities. You configure how a broken URL maps back to a Sharp entity/model so the "fix this" action has somewhere to go. Start with the entities that own public-facing slugs (pages, articles, products) and add more incrementally — a mapping that silently resolves to the wrong entity is worse than no mapping.
• Treat the list as read-only triage. Don't build editing into the broken-links screen; use it to deep-link into the Sharp form you already have. This keeps permissions, validation, and Sharp's own save pipeline intact.
• Cache aggressively. Oh Dear's API is a network round-trip per page load and you will hit rate limits on a busy admin. Wrap the fetch in Cache::remember() with a TTL (an hour is reasonable), and expose a manual refresh only to admins.
• Scheduled warm-up. Add a small artisan command or scheduled job that refreshes the cache during off-hours so the first editor of the day doesn't pay the latency.
• Environment gating. Only register the Sharp menu entry when the token and site ID are present, and disable it outside production/staging. Local and CI environments have no Oh Dear data and will produce noisy 401s or empty screens.
• Sharp conventions still apply. The broken-links screen is subject to Sharp's authorization layer — if your SharpServiceProvider uses policies or a custom SharpAuthorization, verify editors actually see the menu item they need.
• Redirect hygiene belongs elsewhere. This package surfaces problems; the fix (301s, .htaccess/nginx rules, or a slug-history table in your app) lives in your codebase. Consider pairing it with a slug_history table so an editor renaming a page doesn't create a new broken link tomorrow.

Gotchas and Tips

• v2.6 is a safe minor upgrade. It adds PHP 8.5 support and "basic testing"; there are no breaking changes, no deprecations, and no API or config changes called out. Bump the constraint and run your suite.
• "Basic testing" is not a safety net. The phrase in the release notes suggests a first pass of coverage, not comprehensive coverage of the Oh Dear client or the resolution mapping. Keep your own smoke check (does the menu render, does the list populate) in your upgrade routine — especially if you jump PHP minor versions.
• PHP 8.5 support means the package is now installable there, not that Sharp is. Before bumping your app to PHP 8.5, confirm code16/sharp itself and your other Sharp extensions declare 8.5 compatibility. A single extension claiming support is not sufficient.
• Empty list is usually one of three things: no token, wrong site ID, or Oh Dear's broken-links check not enabled/never run for that site. Log the raw HTTP status from the Oh Dear client first — a 401 and a 200-with-empty-array look identical in the UI but have completely different fixes.
• Rate limits and latency. Oh Dear rate-limits the API. If the Sharp screen times out, it's almost always an uncached call on page load, not a Sharp problem.
• Watch for stale links. Oh Dear keeps reporting a link until its next crawl, so a link you just fixed may linger for hours. Don't chase "it's still broken" reports until a re-crawl has run.
• Extension points: publish the package views if you need to change the table columns, and keep your resolution/mapping logic in your own service class rather than editing vendor files — the mapping is the part most likely to need per-project customisation and the part most likely to break on a package minor.
• Pin sensibly. "code16/sharp-ohdear-broken-links": "^2.6" is fine; if you're still on PHP 8.2/8.3 and want the smallest diff, 2.5 → 2.6 is a no-risk move, so there's no reason to stay behind.