Oliv Laravel Package

Getting Started

• Install the package with Composer and pin it explicitly ("vendor/package": "0.1.1") — this is a pre-1.0 release, so treat the version as part of your contract.
• Read the package README first, then AGENTS.md (new in 0.1.1). The latter documents project conventions and is the fastest way to understand intended usage and contribution rules, and it doubles as context if you use an AI assistant on the codebase.
• Publish any config with php artisan vendor:publish if the package exposes it, and check for an environment variable controlling the admin path/domain.
• First use case: call getAdminUrl() from a Tinker session or a throwaway route and confirm it returns the URL you expect for your app's admin entry point. If you were on 0.1.0, do this before upgrading — 0.1.1 changes the method's behavior, so the string you get back may differ.
• If your app has more than one admin surface (e.g., a staff panel and a tenant panel), verify which one the helper resolves to before wiring it into anything user-facing.

Implementation Patterns

• Wrap the helper. Don't scatter getAdminUrl() calls through views and controllers. Bind it behind a small application service (e.g., AdminUrlResolver) or a Blade component so that a future behavior change in a 0.1.x patch is a one-file edit rather than a grep-and-replace.
• Redirects after admin actions. The most natural day-to-day use is post-action redirects (return redirect(getAdminUrl())) and "back to the admin" links in confirmation and error pages. Keep these in controllers/actions, not in the model layer.
• Notification and mail links. Use the helper to build deep links in mailables and notifications so the admin host stays consistent across environments. Render the URL at send time rather than persisting it.
• Config-driven environments. Point the helper at a local admin path in local/testing and the real admin host elsewhere. Assert the resolved URL in a feature test per environment so the 0.1.1 behavior change is captured as a regression test.
• Feature tests as documentation. Add a test like $this->get(getAdminUrl())->assertRedirect(...) or an assertion on the returned string. This both locks in the corrected behavior and documents what "admin URL" means in your app.
• Contributing upstream. Follow AGENTS.md for branch naming, test commands, and style before opening a PR; it was added specifically to make external contributions predictable.

Gotchas and Tips

• getAdminUrl() changed in 0.1.1. Any cached HTML, stored absolute URLs in the database, or hard-coded expectations from 0.1.0 should be audited after upgrading. Search for persisted admin links, not just code.
• Pre-1.0 means no backward-compatibility promise. A patch release can legitimately alter return values. Pin the version in composer.json and read release notes before every bump.
• Trailing slashes and base paths. URL helpers frequently differ on whether they return /admin or /admin/. If you concatenate paths onto the result, normalize with rtrim(..., '/') and test it.
• CLI and queue context. Code running outside an HTTP request (jobs, commands, scheduled tasks) may not have a request host available. If getAdminUrl() derives from the request, force an explicit configured host for those code paths.
• APP_URL and proxies. Behind a load balancer, confirm the scheme and host are correct (trusted proxies / URL::forceScheme), otherwise admin links in emails will point to http:// or an internal hostname.
• Multi-domain setups. Subdomain-routed admin panels are a common source of surprises; assert the resolved host, not just the path.
• Debugging. If the URL looks wrong, dump the underlying route/config the helper reads rather than the helper's output — the fix is almost always in configuration or route registration.
• Extension points. Prefer the package's published config or container binding for customization. If no extension point exists for your case, keep the workaround isolated in your wrapper service so it is easy to delete once upstream adds one.
• Keep AGENTS.md in mind when forking. If you vendor or fork the package, update that file alongside your changes; it is the documented source of truth for conventions.