Nova Location Laravel Package

Getting Started

Version 0.4.0 is a feature-and-refactor release, so start by confirming how the package is wired into your app before building on it.

1. Install/upgrade and republish assets. Run composer require <vendor>/<package> (or composer update <vendor>/<package>), then republish the config and any front-end assets. The new map search provider configuration almost certainly lives in a publishable config file, so diff your existing published config against the new stub rather than blindly overwriting it.
2. Look first at the config file. The 0.4.0 release adds search provider configuration and at least one new provider. Find the search/provider block, note the supported driver names, and check which credentials or endpoints each provider expects.
3. Inspect the MapMarker field class. The release adds initial values to MapMarker. Check the field’s constructor/defaults and how it merges initial values with model state; this is the fastest way to understand the field’s day-to-day behavior.
4. Review the refactored policies. Since policies were refactored, confirm whether the package now auto-discovers policies, expects them in a specific namespace, or requires explicit registration in a service provider.

First use case: add a MapMarker field to a form/resource with initial coordinates, configure a search provider so users can look up locations, and protect the underlying model/operations with the package’s policy. That covers the three main changes in 0.4.0 in one vertical slice.

Implementation Patterns

MapMarker fields with initial values. Use the field’s initial-value support to seed new records with sensible defaults (e.g., a default map center, a pre-selected marker, or a fallback coordinate). For edit forms, verify whether initial values act as a default only when the model attribute is empty or whether they always take precedence. A typical pattern is:

MapMarker::make('location')
    ->initialValues([
        'lat' => config('maps.default_lat'),
        'lng' => config('maps.default_lng'),
    ]);

Keep these defaults in config rather than hard-coding them per field so tests and environments can vary them.

Search provider configuration. Configure the provider centrally and let fields inherit it. The 0.4.0 release adds provider configuration and a new provider, so the intended pattern is likely to select a driver in config and have the field resolve it at render time. If you need per-field overrides, check whether the field exposes a searchProvider()/provider() method; if not, treat the config as the single source of truth. Put API keys in .env and reference them from config so config:cache works correctly.

Policy integration. The policy refactor is the highest-risk change. Review how policies are registered (auto-discovery vs. explicit Gate::policy()), what abilities they expose, and whether the package’s default policy now denies or allows by default. For day-to-day use, write your own policy only if you need custom rules; otherwise confirm the package policy matches your authorization model. Test with Gate::forUser($user)->allows(...) in feature tests rather than relying on UI behavior.

Testing pattern. Bind a fake or null search provider in tests so you don’t hit external geocoding APIs. If the package exposes a provider contract, implement a lightweight test double. For policy tests, use Laravel’s standard policy assertions and cover both the “owner” and “other user” cases, since refactors often change implicit ownership checks.

Upgrade pattern. Because 0.4.0 refactors policies and changes config, treat it as a minor upgrade that still needs a diff review: publish config to a temp location, compare, merge, then run your map/field and authorization tests before deploying.

Gotchas and Tips

• Policy refactor is the main breaking-change risk. Even though the release is versioned 0.4.x, “refactored policies” can change method names, default behavior, or registration. Grep your app for package policy references and run authorization tests against the new version before merging.
• Stale published config. If you published config in an earlier version, the new search provider settings won’t exist until you republish or manually merge. After changing providers, run php artisan config:clear (and config:cache in production) — provider resolution often fails silently otherwise.
• Initial values vs. persisted values. “Make MapMarker field with initial values” may mean defaults for new forms only. On edit screens, confirm initial values don’t overwrite existing marker data; if they do, conditionally apply them (e.g., only on create).
• Provider credentials and rate limits. A newly added search provider may have different auth requirements or quotas than the existing one. Validate with a single lookup before wiring it into a high-traffic form, and handle provider failures gracefully so the field still renders without search.
• Check for a provider contract/extension point. If the package defines an interface for search providers, prefer implementing it over subclassing a concrete provider; that keeps you compatible with future provider changes.
• Debugging tip. If search returns nothing after upgrading, log the resolved provider class and config values at boot. Most “provider not working” issues are a stale config cache or a missing .env key, not a code bug.
• Watch the release notes’ brevity. These notes are terse; read the diff or changelog for the policy refactor specifically, since undocumented ability or namespace changes are the most likely source of post-upgrade 403s.