Laravel Short Url Laravel Package

Getting Started

This release (1.9.0) is effectively a new baseline: it targets Laravel 9+ and PHP 8+ only, and ships a brand new design. Treat your first day with it as a fresh install rather than an incremental upgrade.

1. Confirm your runtime. You need PHP >= 8.0 and Laravel 9. If you are on Laravel 8 or PHP 7.4, stay on the previous 1.8.x line — 1.9.0 will not install.
2. Install into a clean Laravel 9 app first. composer require <vendor>/<package>:^1.9 in a throwaway project so you can see the new design and published assets without legacy overrides interfering.
3. Publish everything. Run the package's publish command(s) for config, views, and assets (php artisan vendor:publish --provider="..." or the documented tags). The "brand new design" almost certainly means new Blade views, CSS/JS, and possibly new config keys — you want the pristine published set before customising.
4. Render the default entry point. Hit the package's default route/component/page once. This validates the service provider registers, assets resolve, and the new design loads.
5. Where to look first: the package composer.json (exact PHP/Laravel constraints and updated dependencies), the published config/<package>.php, the service provider (what it binds/registers), and the published views/assets directory. Those four tell you how it plugs in.

First use case: get the default UI/feature rendering correctly in a scratch Laravel 9 app, then diff the published views/assets against what you had customised in 1.8.x before touching your real application.

Implementation Patterns

• Version-pinned rollout. Because 1.9.0 is a hard compatibility break, introduce it on a branch with a fresh composer.lock. Don't let it float into an existing lock file mid-sprint.
• Publish-then-override. Use the package's published views/assets as the customisation surface rather than editing vendor files. With a redesigned release, re-publish and re-apply your diffs — keep your overrides small and documented so the next redesign is cheap.
• Config-driven usage. Prefer the published config file for behaviour toggles and design options over subclassing internals. If the redesign added config keys, mirror them into your environment-specific config rather than hardcoding.
• Blade/component integration. If the package exposes components/directives, use them in your layouts deliberately (one wrapper partial per feature) so a future design change is isolated to a handful of files.
• Asset pipeline. The new design likely changes CSS/JS. Wire the package's assets through your build (Vite/Mix) or its documented publish path, and cache-bust on deploy. Don't mix old published assets with new package code.
• CI matrix alignment. Update your pipeline to PHP 8.x × Laravel 9 only. Remove 7.4/8.x jobs; they will fail on install, not on tests, which wastes time.
• Staged migration workflow: scratch-app smoke test → upgrade branch in the real app → visual/regression review of the new design → deploy behind a feature flag if the UI surface is user-facing.

Gotchas and Tips

• This is a breaking release, not a feature bump. Dropping Laravel < 9 and PHP < 8 will surface as Composer dependency-resolution errors. If composer update fails with constraint conflicts, the cause is almost always your PHP version or a transitive package still pinning Laravel 8 — read the conflict tree, don't --ignore-platform-reqs.
• "Brand new design" means your view/asset overrides are stale. Published views that referenced old markup, class names, or asset paths will silently render wrong or blank. Re-publish, diff, and port customisations. Check for renamed view namespaces and removed partials.
• Updated dependencies can shift behaviour. Transitive upgrades may change minor APIs or asset tooling. Run your test suite and a visual pass, not just a boot check.
• Clear caches aggressively when debugging. php artisan config:clear, view:clear, route:clear, and rebuild assets. A "design didn't update" report is usually cached compiled views or stale published assets.
• Check the service provider for registration changes. Redesigns often add middleware, view namespaces, or asset registration. If something 404s or a component is missing, confirm the provider still auto-discovers (or is manually registered) and that config/app.php providers are current.
• Extension points to lean on: published config, published views/assets, and any documented contracts/events. Avoid reaching into vendor internals — the 1.9.0 redesign is exactly the kind of release that rearranges them.
• Pin it. Use ^1.9 in composer.json and commit the lock file, so a future 1.10 redesign doesn't land unreviewed.
• Keep the 1.8.x escape hatch documented. If you must support Laravel 8/PHP 7.4 for another app, record the last compatible version so future-you doesn't rediscover it via a failed install.