{"id":20531964,"url":"https://github.com/geocoder-php/geocoderlaravel","last_synced_at":"2026-05-31T01:03:25.992Z","repository":{"id":10649354,"uuid":"12878469","full_name":"geocoder-php/GeocoderLaravel","owner":"geocoder-php","description":"Geocoder service provider for Laravel","archived":false,"fork":false,"pushed_at":"2025-03-06T01:20:06.000Z","size":29597,"stargazers_count":723,"open_issues_count":15,"forks_count":106,"subscribers_count":24,"default_branch":"master","last_synced_at":"2025-05-06T22:38:37.989Z","etag":null,"topics":["geocoding","laravel-package"],"latest_commit_sha":null,"homepage":"http://geocoder-php.org/GeocoderLaravel/","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/geocoder-php.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2013-09-16T20:49:38.000Z","updated_at":"2025-03-31T17:37:45.000Z","dependencies_parsed_at":"2024-06-18T11:01:58.225Z","dependency_job_id":"ed57c778-5667-4cfb-a49f-6c71ac323a67","html_url":"https://github.com/geocoder-php/GeocoderLaravel","commit_stats":{"total_commits":260,"total_committers":37,"mean_commits":7.027027027027027,"dds":0.3423076923076923,"last_synced_commit":"f354165d10768b04da0e46b76dd99fd44dba89d2"},"previous_names":[],"tags_count":56,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/geocoder-php%2FGeocoderLaravel","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/geocoder-php%2FGeocoderLaravel/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/geocoder-php%2FGeocoderLaravel/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/geocoder-php%2FGeocoderLaravel/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/geocoder-php","download_url":"https://codeload.github.com/geocoder-php/GeocoderLaravel/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254036811,"owners_count":22003653,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["geocoding","laravel-package"],"created_at":"2024-11-16T00:11:28.567Z","updated_at":"2026-05-31T01:03:25.986Z","avatar_url":"https://github.com/geocoder-php.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![Travis](https://img.shields.io/travis/geocoder-php/GeocoderLaravel.svg)](https://travis-ci.org/geocoder-php/GeocoderLaravel)\n[![Scrutinizer](https://img.shields.io/scrutinizer/g/geocoder-php/GeocoderLaravel.svg)](https://scrutinizer-ci.com/g/geocoder-php/GeocoderLaravel/)\n[![Coveralls](https://img.shields.io/coveralls/geocoder-php/GeocoderLaravel.svg)](https://coveralls.io/github/geocoder-php/GeocoderLaravel)\n[![GitHub release](https://img.shields.io/github/release/geocoder-php/GeocoderLaravel.svg)](https://github.com/geocoder-php/GeocoderLaravel/releases)\n[![Packagist](https://img.shields.io/packagist/dt/toin0u/geocoder-laravel.svg)](https://packagist.org/packages/toin0u/geocoder-laravel)\n\n\n# Geocoder for Laravel\n\n\u003e If you still use **Laravel 4**, please check out the `0.4.x` branch\n [here](https://github.com/geocoder-php/GeocoderLaravel/tree/0.4.x).\n\n**Version 13.0.0 is a backwards-compatibility-breaking update. Please review\n the _Upgrading_ section, especially the new default HTTP adapter, before\n installing.**\n\n\u003e **Versioning change:** starting with `13.0.0`, this package's major version\n\u003e tracks the highest supported Laravel major version, instead of the upstream\n\u003e Geocoder PHP version. So `13.x` supports Laravel 11/12/13, the next major\n\u003e will be `14.x` when Laravel 14 ships, and so on. The previous tag was\n\u003e `5.0.0`; the jump to `13.0.0` reflects the new versioning scheme, not 9\n\u003e intermediate releases.\n\nThis package allows you to use [**Geocoder**](http://geocoder-php.org/Geocoder/)\n in [**Laravel**](http://laravel.com/).\n\n## Requirements\n- PHP \u003e= 8.2\n- Laravel \u003e= 11.0\n\n## Installation\n1. Install the package via composer:\n  ```sh\n  composer require toin0u/geocoder-laravel\n  ```\n\n2. **If you are running Laravel 5.5 (the package will be auto-discovered), skip\n  this step.** Find the `providers` array key in `config/app.php` and register\n  the **Geocoder Service Provider**:\n  ```php\n  // 'providers' =\u003e [\n      Geocoder\\Laravel\\Providers\\GeocoderService::class,\n  // ];\n  ```\n3. **Optional** I recommend adding the following lines to your `composer.json` file to prevent stale caches when upgrading or updating the package, both in your live and dev environments:\n```json\n        \"post-update-cmd\": [\n            \"@php artisan cache:clear\",\n        ],\n        \"post-install-cmd\": [\n            \"@php artisan cache:clear\",\n        ]\n```\n\n## Configuration\nPay special attention to the language and region values if you are using them.\n For example, the GoogleMaps provider uses TLDs for region values, and the\n following for language values: https://developers.google.com/maps/faq#languagesupport.\n\nFurther, a special note on the GoogleMaps provider: if you are using an API key,\n you must also use set HTTPS to true. (Best is to leave it true always, unless\n there is a special requirement not to.)\n\nSee the [Geocoder documentation](http://geocoder-php.org/Geocoder/) for a list\n of available adapters and providers.\n\n### Dedicated Cache Store *Recommended*\nTo implement the dedicated cache store, add another redis store entry in\n`config/database.php`, something like the following:\n```php\n    \"redis\" =\u003e [\n        // ...\n\n        \"geocode-cache\" =\u003e [ // choose an appropriate name\n            'host' =\u003e env('REDIS_HOST', '192.168.10.10'),\n            'password' =\u003e env('REDIS_PASSWORD', null),\n            'port' =\u003e env('REDIS_PORT', 6379),\n            'database' =\u003e 1, // be sure this number differs from your other redis databases\n        ],\n    ]\n```\n\nYou will also need to add an entry in `config/cache.php` to point to this redis\ndatabase:\n```php\n    \"stores\" =\u003e [\n        // ...\n\n        \"geocode\" =\u003e [\n            'driver' =\u003e 'redis',\n            'connection' =\u003e 'geocode-cache',\n        ],\n    ],\n```\n\nFinally, configure Geocoder for Laravel to use this store. Edit\n`config/geocoder.php`:\n```php\n    \"cache\" =\u003e [\n        \"store\" =\u003e \"geocode\",\n\n        // ...\n    ],\n```\n\n#### Disabling Caching on a Query-Basis\nYou can disable caching on a query-by-query basis as needed, like so:\n```php\n    $results = app(\"geocoder\")\n        -\u003edoNotCache()\n        -\u003egeocode('Los Angeles, CA')\n        -\u003eget();\n```\n\n#### ⚠️ Laravel 13 `cache.serializable_classes` — Important\n\n\u003e Laravel 13 introduced [`cache.serializable_classes`](https://laravel.com/docs/13.x/upgrade#cache-serializable_classes-configuration) as a security hardening measure, defaulting to `false` to block deserialization of arbitrary PHP objects from the cache. This package stores `Collection`s of `Address` objects in the cache, which would silently break caching under the new default.\n\nTo keep caching working out of the box without forcing you to maintain an\nallow-list as new providers are installed, **this package scans the installed\nGeocoder vendor directories at boot and merges every model class it finds into\nyour application's `cache.serializable_classes` allow-list**. Whatever\nproviders you have installed under `vendor/geocoder-php/*` are covered\nautomatically — there's no curated list to go stale.\n\n**🔐 Security implication:** the package narrowly relaxes Laravel 13's hardening\nfor the geocoder model classes installed in your `vendor/` directory. Other\nPHP objects you store in the cache remain blocked unless you explicitly allow\nthem. The blast radius is bounded to classes you've already deliberately\ninstalled via composer.\n\n**Opting out.** Set `auto_register_serializable_classes` to `false` in your\n`config/geocoder.php`:\n\n```php\n    'cache' =\u003e [\n        // ...\n\n        'auto_register_serializable_classes' =\u003e false,\n    ],\n```\n\nWhen opted out, the package will not touch `cache.serializable_classes` at all.\nYou then have two reasonable paths:\n\n1. **Manage the allow-list yourself.** Add the geocoder model classes to\n   `config/cache.php`'s `serializable_classes` directly. Caching keeps working\n   under your explicit control. Pick this if you want to audit exactly which\n   PHP objects your application allows to deserialize from cache.\n\n2. **Disable caching for geocoder queries.** Call\n   `app('geocoder')-\u003edoNotCache()` on each query, or set `cache.duration` to\n   `0` in `config/geocoder.php`. Pick this if you don't want to maintain the\n   allow-list and can absorb the per-request API cost.\n\nDoing neither under Laravel 13 could cause `__PHP_Incomplete_Class` corruption\non cached results.\n\n### Providers\nIf you are upgrading and have previously published the geocoder config file, you\n need to add the `cache-duration` variable, otherwise cache will be disabled\n (it will default to a `0` cache duration). The default cache duration provided\n by the config file is `999999999` seconds, essentially forever.\n\nBy default, the configuration specifies a Chain provider, containing the\n GoogleMaps provider for addresses as well as reverse lookups with lat/long,\n and the GeoIP provider for IP addresses. The first to return a result\n will be returned, and subsequent providers will not be executed. The default\n config file is kept lean with only those two providers.\n\nHowever, you are free to add or remove providers as needed, both inside the\n Chain provider, as well as along-side it. The following is the default\n configuration provided by the package:\n```php\nuse Geocoder\\Laravel\\Http\\LaravelHttpClient;\nuse Geocoder\\Provider\\Chain\\Chain;\nuse Geocoder\\Provider\\GeoPlugin\\GeoPlugin;\nuse Geocoder\\Provider\\GoogleMaps\\GoogleMaps;\n\nreturn [\n\n    /*\n    |--------------------------------------------------------------------------\n    | Cache Duration\n    |--------------------------------------------------------------------------\n    |\n    | Specify the cache duration in seconds. The default approximates a forever\n    | cache, but there are certain issues with Laravel's forever caching\n    | methods that prevent us from using them in this project.\n    |\n    | Default: 9999999 (integer)\n    |\n    */\n    'cache-duration' =\u003e 9999999,\n\n    /*\n    |--------------------------------------------------------------------------\n    | Providers\n    |--------------------------------------------------------------------------\n    |\n    | Here you may specify any number of providers that should be used to\n    | perform geocaching operations. The `chain` provider is special,\n    | in that it can contain multiple providers that will be run in\n    | the sequence listed, should the previous provider fail. By\n    | default the first provider listed will be used, but you\n    | can explicitly call subsequently listed providers by\n    | alias: `app('geocoder')-\u003eusing('google_maps')`.\n    |\n    | Please consult the official Geocoder documentation for more info.\n    | https://github.com/geocoder-php/Geocoder#providers\n    |\n    */\n    'providers' =\u003e [\n        Chain::class =\u003e [\n            GoogleMaps::class =\u003e [\n                env('GOOGLE_MAPS_LOCALE', 'us'),\n                env('GOOGLE_MAPS_API_KEY'),\n            ],\n            GeoPlugin::class  =\u003e [],\n        ],\n    ],\n\n    /*\n    |--------------------------------------------------------------------------\n    | Adapter\n    |--------------------------------------------------------------------------\n    |\n    | The HTTP adapter to use when communicating with geocoding services. By\n    | default this package ships a PSR-18 client that delegates to Laravel's\n    | `Http` facade — this gives you `Http::fake()` in tests, native retry\n    | and timeout configuration, and any HTTP middleware you've registered.\n    |\n    | Provide any class that implements `Psr\\Http\\Client\\ClientInterface` to\n    | swap in a different adapter (e.g., `Http\\Client\\Curl\\Client` from\n    | `php-http/curl-client`, which you would need to install separately).\n    |\n    | To pass constructor arguments (timeouts, proxies, client options, etc.)\n    | use the array form `[Class =\u003e [args]]`. Arguments are forwarded to the\n    | adapter's constructor — it's on you to match its signature. Named args\n    | are supported: `[Class =\u003e ['timeout' =\u003e 10]]`.\n    |\n    | Default: LaravelHttpClient::class\n    |\n    | Examples:\n    |   'adapter' =\u003e LaravelHttpClient::class,\n    |   'adapter' =\u003e [LaravelHttpClient::class =\u003e ['timeout' =\u003e 10, 'retry' =\u003e [3, 100]]],\n    |   'adapter' =\u003e [Http\\Client\\Curl\\Client::class =\u003e [null, null, [CURLOPT_PROXY =\u003e '...']]],\n    |\n    */\n    'adapter'  =\u003e LaravelHttpClient::class,\n\n    /*\n    |--------------------------------------------------------------------------\n    | Reader\n    |--------------------------------------------------------------------------\n    |\n    | You can specify a reader for specific providers, like GeoIp2, which\n    | connect to a local file-database. The reader should be set to an\n    | instance of the required reader class or an array containing the reader\n    | class and arguments.\n    |\n    | Please consult the official Geocoder documentation for more info.\n    | https://github.com/geocoder-php/geoip2-provider\n    |\n    | Default: null\n    |\n    */\n    'reader' =\u003e null,\n\n];\n```\n\n### Adapters\nBy default we ship `Geocoder\\Laravel\\Http\\LaravelHttpClient`, a thin PSR-18\n client that delegates every request to Laravel's `Http` facade. This means:\n\n- `Http::fake()` and `Http::assertSent()` work in your tests with no extra setup\n- One less third-party HTTP client to manage\n\n#### Configuring Adapter Options\nYou can pass constructor arguments to the adapter via the array form\n `[Class =\u003e [args]]` in `config/geocoder.php`. Arguments are forwarded directly\n to the adapter's constructor — it's on you to match its signature. Named\n arguments are supported.\n\nThe default `LaravelHttpClient` accepts `timeout`, `connectTimeout`, `retry`,\n and `options` (Guzzle transport options). These are forwarded to the\n underlying Laravel `PendingRequest`:\n```php\n'adapter' =\u003e [LaravelHttpClient::class =\u003e [\n    'timeout' =\u003e 10,\n    'connectTimeout' =\u003e 3,\n    'retry' =\u003e [3, 100],             // [times, sleepMilliseconds]\n    'options' =\u003e ['verify' =\u003e false], // Guzzle transport options\n]],\n```\n\n#### Using a Different Transport\nSet `'adapter'` to any class that implements `Psr\\Http\\Client\\ClientInterface`.\n To go back to the previous CURL adapter, install `php-http/curl-client` and\n pass your CURL options the same way:\n```php\n'adapter' =\u003e [Http\\Client\\Curl\\Client::class =\u003e [\n    null,\n    null,\n    [CURLOPT_PROXY =\u003e env('CURL_PROXY'), CURLOPT_PROXYUSERPWD =\u003e env('CURL_PROXYUSERPWD')],\n]],\n```\n\n### Customization\nIf you would like to make changes to the default configuration, publish and\n edit the configuration file:\n```sh\nphp artisan vendor:publish --provider=\"Geocoder\\Laravel\\Providers\\GeocoderService\" --tag=\"config\"\n```\n\n## Usage\nThe service provider initializes the `geocoder` service, accessible via the\n facade `Geocoder::...` or the application helper `app('geocoder')-\u003e...`.\n\n### Geocoding Addresses\n#### Get Collection of Addresses\n```php\napp('geocoder')-\u003egeocode('Los Angeles, CA')-\u003eget();\n```\n\n#### Get IP Address Information\n```php\napp('geocoder')-\u003egeocode('8.8.8.8')-\u003eget();\n```\n\n#### Reverse-Geocoding\n```php\napp('geocoder')-\u003ereverse(43.882587,-103.454067)-\u003eget();\n```\n\n#### Localizing Results\nUse the `locale()` method to request localized formatting from providers that\n support it (GoogleMaps, Nominatim, etc.). Results are cached separately per\n locale, so switching locales doesn't pollute each other's cache entries:\n```php\napp('geocoder')-\u003elocale('it')-\u003egeocode('Bologna')-\u003eget();\napp('geocoder')-\u003elocale('fr')-\u003ereverse(45.5, -73.5)-\u003eget();\n```\n\nIf you need to build a query with additional options, you can also set the\n locale directly on a query and pass it through `geocodeQuery()` or\n `reverseQuery()`:\n```php\nuse Geocoder\\Query\\GeocodeQuery;\n\n$query = GeocodeQuery::create('Bologna')-\u003ewithLocale('it');\napp('geocoder')-\u003egeocodeQuery($query)-\u003eget();\n```\n\n#### Dumping Results\n```php\napp('geocoder')-\u003egeocode('Los Angeles, CA')-\u003edump('kml');\n```\n\n#### Dependency Injection\n```php\nuse Geocoder\\Laravel\\ProviderAndDumperAggregator as Geocoder;\n\nclass GeocoderController extends Controller\n{\n    public function getGeocode(Geocoder $geocoder)\n    {\n       $geocoder-\u003egeocode('Los Angeles, CA')-\u003eget()\n    }\n}\n```\n\n## Upgrading\nAnytime you upgrade this package, please remember to clear your cache, to prevent incompatible cached responses when breaking changes are introduced (this should hopefully only be necessary in major versions):\n```sh\nphp artisan cache:clear\n```\n\n### 5.x to 13.x\nUpdate your `composer.json`:\n```json\n    \"toin0u/geocoder-laravel\": \"^13.0\",\n```\n\n\u003e Yes, the jump from `5.x` to `13.x` is intentional — see the versioning note\n\u003e at the top of this README. There are no `5.x` through `12.x` releases.\n\n**Breaking: default HTTP adapter changed.** The default `'adapter'` in\n `config/geocoder.php` is now `Geocoder\\Laravel\\Http\\LaravelHttpClient`\n instead of `Http\\Client\\Curl\\Client`. The new adapter is a PSR-18 client\n that delegates to Laravel's `Http` facade, so `Http::fake()`, retries,\n timeouts, and middleware all work transparently.\n\nIf you have **published the geocoder config previously**, your config file\n still pins the old curl adapter and will fail at runtime once\n `php-http/curl-client` is no longer installed. Pick one:\n\n- **Recommended:** delete (or rename) your published `config/geocoder.php`\n  and re-publish it, then re-apply your customizations.\n- Or edit the existing file: change `use Http\\Client\\Curl\\Client;` to\n  `use Geocoder\\Laravel\\Http\\LaravelHttpClient;` and change\n  `'adapter' =\u003e Client::class` to `'adapter' =\u003e LaravelHttpClient::class`.\n- Or, if you want to keep the curl adapter, install it explicitly:\n  `composer require php-http/curl-client`. The published config keeps working\n  unchanged.\n\n**Other notable changes in 13.x:**\n- Minimum PHP raised to 8.2; minimum Laravel raised to 11.x.\n- `php-http/curl-client` removed from required dependencies (install it\n  yourself if you still need it).\n- `MaxMindBinary` provider support removed (the underlying PHP package was\n  abandoned). Use `geocoder-php/geoip2-provider` for MaxMind data instead.\n\n### 4.x to 5.x\nUpdate your `composer.json`:\n```json\n    \"toin0u/geocoder-laravel\": \"^5.0\",\n```\n\n### 1.x to 4.x\nUpdate your composer.json file:\n```json\n    \"toin0u/geocoder-laravel\": \"^4.0\",\n```\n\nThe one change to keep in mind here is that the results returned from\n `Geocoder for Laravel` are now using the Laravel-native Collections class\n instead of returning an instance of `AddressCollection`. This should provide\n greater versatility in manipulation of the results, and be inline with\n expectations for working with Laravel. The existing `AddressCollection`\n methods should map straight over to Laravel's `Collection` methods. But be sure\n to double-check your results, if you have been using `count()`,\n `first()`, `isEmpty()`, `slice()`, `has()`, `get()`, or `all()` on your results.\n\nAlso, `getProviders()` now returns a Laravel Collection instead of an array.\n\n**Alert:** if you have been using the `getIterator()` method, it is no longer\n needed. Simply iterate over your results as you would any other Laravel\n collection.\n\n**Deprecated:**\n  - the `all()` method on the geocoder is being deprecated in favor of using\n    `get()`, which will return a Laravel Collection. You can then run `all()`\n    on that. This method will be removed in version 5.0.0.\n  - the `getProvider()` method on the geocoder is being deprecated in favor of using\n    `getProviders()`, which will return a Laravel Collection. You can then run `first()`\n    on that to get the same result. This method will be removed in version 5.0.0.\n\n**Added:** this version introduces a new way to create more complex queries:\n  - geocodeQuery()\n  - reverseQuery()\n\n Please see the [Geocoder documentation](https://github.com/geocoder-php/Geocoder)\n for more details.\n\n### 0.x to 1.x\nIf you are upgrading from a pre-1.x version of this package, please keep the\n following things in mind:\n\n1. Update your composer.json file as follows:\n\n    ```json\n    \"toin0u/geocoder-laravel\": \"^1.0\",\n    ```\n\n2. Remove your `config/geocoder.php` configuration file. (If you need to customize it, follow the configuration instructions below.)\n3. Remove any Geocoder alias in the aliases section of your `config/app.php`. (This package auto-registers the aliases.)\n4. Update the service provider entry in your `config/app.php` to read:\n\n    ```php\n    Geocoder\\Laravel\\Providers\\GeocoderService::class,\n    ```\n\n5. If you are using the facade in your code, you have two options:\n    1. Replace the facades `Geocoder::` (and remove the corresponding `use` statements) with `app('geocoder')-\u003e`.\n    2. Update the `use` statements to the following:\n\n        ```php\n        use Geocoder\\Laravel\\Facades\\Geocoder;\n        ```\n\n6. Update your query statements to use `-\u003eget()` (to retrieve a collection of\n GeoCoder objects) or `-\u003eall()` (to retrieve an array of arrays), then iterate\n to process each result.\n\n## Troubleshooting\n- Clear cache: `php artisan cache:clear`.\n- If you are still experiencing difficulties, please please open an issue on GitHub:\n https://github.com/geocoder-php/GeocoderLaravel/issues.\n\n## Changelog\nhttps://github.com/geocoder-php/GeocoderLaravel/blob/master/CHANGELOG.md\n\n## Contributor Code of Conduct\nPlease note that this project is released with a\n [Contributor Code of Conduct](https://github.com/geocoder-php/Geocoder#contributor-code-of-conduct).\n By participating in this project you agree to abide by its terms.\n\n## License\nGeocoderLaravel is released under the MIT License. See the bundled\n [LICENSE](https://github.com/geocoder-php/GeocoderLaravel/blob/master/LICENSE)\n file for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgeocoder-php%2Fgeocoderlaravel","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgeocoder-php%2Fgeocoderlaravel","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgeocoder-php%2Fgeocoderlaravel/lists"}