Geo Ip Bundle Laravel Package

Getting Started

• Install the package with Composer and let Laravel package discovery register the service provider. Publish any package config if the package exposes it, then set the required environment values (API key, endpoint, or driver) before making your first lookup.
• The first practical use case is resolving a visitor or account IP into a GeoResponse and reading the two new fields: countryName for display and countryIsoCode for application logic such as locale selection, tax/shipping rules, or access policies.
• Look first at the package config file, the service provider binding, and the GeoResponse class. The GeoResponse object is the main integration point; v1.0.16 adds countryName and countryIsoCode without indicating breaking changes.
• Start with a single lookup in a controller or middleware, log the returned GeoResponse, and confirm how the new fields are serialized before wiring them into persistence or views.

Implementation Patterns

• Resolve once per request, reuse the response. Perform the lookup in middleware or a form request and attach the resulting GeoResponse to the request or container. Avoid repeated lookups for the same IP in controllers, views, and listeners.
• Use the ISO code for decisions, the country name for presentation. Store and compare countryIsoCode in business logic; use countryName only when rendering human-readable output. This keeps behavior stable if the display name changes or is localized differently.
• Locale selection middleware. Map countryIsoCode to a supported Laravel locale and call App::setLocale() early in the request lifecycle. Fall back to the application default when the response is missing, the IP is private, or the country is unsupported.
• Cache lookups by IP. Cache the serialized GeoResponse or just the fields you need (countryIsoCode, countryName, and any other used fields) with a TTL that respects the provider’s terms and your accuracy requirements. This is especially important for high-traffic pages.
• Persist canonical codes, not display names. When storing a user’s or order’s country, persist the ISO code. Resolve countryName at render time or through your own translation layer so display naming remains consistent across the app.
• Blade and API resources. Expose countryName in views and API resources for display, and expose countryIsoCode as a stable machine-readable field. Normalize the output shape in your own resource rather than relying directly on the package’s array/JSON format.
• Testing with fakes. Bind a fake or stub GeoResponse in the container for feature tests so tests do not depend on external geo services. Assert both the new fields and your fallback behavior when they are absent or null.

Gotchas and Tips

• Private and reserved IPs. Local development (127.0.0.1, ::1), Docker networks, and private ranges often produce no country data. Always null-check the GeoResponse and both new fields before using them.
• ISO code normalization. Treat countryIsoCode as an ISO 3166-1 alpha-2 code and normalize case where needed. If you compare it to stored values, decide on uppercase and apply that consistently; avoid case-sensitive comparisons against user input.
• Country name localization. countryName may be English-only or provider-localized depending on configuration. Do not assume it matches Laravel’s translation files; use it as a fallback and prefer your own translation keys when you need multilingual display.
• Serialization shape. The new fields may appear as countryName / countryIsoCode on the object but as country_name / country_iso_code in arrays or JSON, depending on the package’s serialization. Inspect toArray()/JSON output before depending on exact keys in API contracts or strict tests.
• Config and opcache. After changing environment values or package config, run php artisan config:clear. In production, remember that cached config can mask new environment variables.
• Rate limits and quotas. Geo providers often throttle or bill per lookup. Cache aggressively, avoid lookups inside loops, and consider a fallback path when the provider is unavailable.
• Upgrade safety. v1.0.16 appears additive: new GeoResponse fields, no stated removals or signature changes. It should be a low-risk upgrade, but pin the version if you have strict tests around response shape or serialized payloads.