- How do I install and set up jcf/geocode in a Laravel application?
- Install it with composer require jcf/geocode, then publish the package config file with the vendor:publish command so you can point it at your Google Geocoding API key. Store the key in your .env file rather than committing it, and make sure config caching is refreshed after changes. After that, add the package trait to any Eloquent model and define which attributes hold the address and the latitude/longitude columns. A smoke test that saves one model and checks the coordinates is enough to confirm the path works.
- Which Laravel and PHP versions does jcf/geocode support?
- The package is a thin service-provider wrapper, so its compatibility is driven by the composer.json constraints and the Laravel components it type-hints against. Check those constraints and any CI matrix before assuming support for the newest Laravel release. Because the surface area is small, adapting it to a newer Laravel version is typically about a day of work if the wrapper goes stale. Pin a version in composer.json and verify the last release date rather than trusting the package listing alone.
- How does the automatic geocoding trait work on Eloquent models?
- You add the package trait to a model and declare which attributes make up the address, plus the columns that should receive latitude and longitude. On save, the package builds an address string, calls the Google Geocoding API, and writes the resolved coordinates back to the model. This makes it convenient for write-time address normalization in flows like store locator seeding or delivery-zone assignment. Keep in mind it runs inside your save lifecycle, so a slow or failing HTTP call can affect the request that triggered it.
- Does jcf/geocode cache geocoding results, and can I configure the cache TTL?
- The package supports caching of resolved coordinates, and the TTL is exposed through its configuration file. Set the TTL deliberately, because Google's terms impose limits on how long geocoding results may be stored. A short-lived cache that absorbs repeated lookups for the same address is usually the safe pattern. Confirm the caching behavior and config keys by reading the published config file rather than assuming defaults.
- Can I store geocoded coordinates permanently or display them on a non-Google map?
- Google's terms commonly restrict geocoding results to short-lived caching and to display on a Google map, so building a permanent internal address-to-coordinate table from this package needs legal review. That constraint is the main gating item, not the PHP code. If your use case requires long-term storage or rendering on Mapbox, Leaflet, or another provider, get sign-off first or plan to use a provider whose terms permit it. Treat the package's cache as an optimization, not as a data warehouse.
- What does jcf/geocode cost, and how do I avoid runaway Google API bills?
- The Composer package itself is free, but every lookup is billed by Google under its usage-based pricing with a limited free monthly tier. Set per-key quota caps and billing alerts in the Google Cloud console from day one. Also guard against retry loops and queue reprocessing that could multiply calls for the same address. Aggressive caching plus a queued, rate-limited job is the practical way to keep costs predictable.
- Is jcf/geocode suitable for batch geocoding or high-volume workloads?
- No, it is designed for single-address lookups, and each call issues a synchronous HTTP request to Google. For volume, move geocoding into queued jobs, cache results, and throttle against your quota rather than calling it in a user-facing request path. It is a poor fit for offline, event-driven, or multi-provider pipelines. If you need bulk processing, consider a dedicated batch geocoder or a self-hosted option like Nominatim or Pelias.
- How do I test Laravel code that uses jcf/geocode without hitting the live Google API?
- Wrap the package behind your own Geocoder contract and inject that interface into your services, so tests can bind a fake implementation. If the package uses Laravel's HTTP client, you can also use Http::fake to return canned Google responses. Tests that call the live API are a disqualifier for CI because they are slow, billable, and flaky. Check the package source to see whether it uses the Laravel HTTP client or raw Guzzle, since that determines how easily it can be faked.
- How does jcf/geocode handle Google errors such as OVER_QUERY_LIMIT or REQUEST_DENIED?
- The wrapper is thin, so do not assume it maps Google status codes to typed exceptions or implements retries and backoff. Read the source and confirm whether failures surface as explicit exceptions or silent nulls, and make sure the API key is never written to logs or error payloads. Add your own retry and backoff policy around it, with explicit handling for quota and permission errors. Silent failures are the biggest risk because they let bad coordinates enter your database unnoticed.
- What are the alternatives to jcf/geocode, and is it actively maintained?
- Alternatives include calling the Google Geocoding API directly with Laravel's HTTP client, the geocoder-php libraries, Mapbox, HERE, or a self-hosted Nominatim or Pelias instance. The package has modest adoption, around 48 stars and no dependents, with a single maintainer, so verify recent releases and CI before relying on it. Because the code surface is small, adopting it behind your own Geocoder interface keeps replacement to roughly an afternoon of work. Choose it for prototypes and small server-side flows, not as a long-term geospatial platform.