# makidizajnerica/laravel-geolocation architecture

> Architecture diagram of the GitHub repository makidizajnerica/laravel-geolocation, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/makidizajnerica/laravel-geolocation
- Repository: https://github.com/makidizajnerica/laravel-geolocation

## Overview

Laravel GeoLocation accepts an IP through its facade or Request macro, resolves a configured provider, performs a lookup, normalizes provider-specific fields, and returns a Collection. The manager also checks in-memory and Laravel cache results and can report driver failures. README documents four providers and custom-driver support; the shown source establishes the shared HTTP, endpoint, and formatting layers, but not every provider’s internal implementation, so those details are left out.

Main entry points: [`src/GeoLocationManager.php`](https://github.com/makidizajnerica/laravel-geolocation/blob/main/src/GeoLocationManager.php) (Lookup manager), [`src/GeoLocationDriver.php`](https://github.com/makidizajnerica/laravel-geolocation/blob/main/src/GeoLocationDriver.php) (Driver base), [`config/geolocation.php`](https://github.com/makidizajnerica/laravel-geolocation/blob/main/config/geolocation.php) (Driver configuration), [`src/Support/HandlingHttpResponse.php`](https://github.com/makidizajnerica/laravel-geolocation/blob/main/src/Support/HandlingHttpResponse.php) (HTTP response handling)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Laravel entry points"]
  node_request_macro["Request macro"]
  node_facade["GeoLocation facade<br/>[GeoLocation.php]"]
  node_provider["Service provider"]
end

subgraph group_lookup["Lookup orchestration"]
  node_config["Driver configuration<br/>[geolocation.php]"]
  node_manager["Lookup manager"]
  node_memory_cache["Request memory cache"]
  node_laravel_cache[("Laravel cache")]
end

subgraph group_drivers["Provider drivers"]
  node_base_driver["Driver base"]
  node_driver_contract["Driver contract"]
  node_ipwhois["IPWhoIs driver<br/>[IPWhoIs.php]"]
  node_geoplugin["GeoPlugin driver<br/>[GeoPlugin.php]"]
  node_abstractapi["AbstractApi driver<br/>[AbstractApi.php]"]
  node_ipdata["IPData driver<br/>[IPData.php]"]
end

subgraph group_support["Driver support"]
  node_endpoint["Endpoint formatter"]
  node_http["HTTP response handling"]
  node_response_format["Response formatter"]
  node_array_helper["Array helper<br/>[Arr.php]"]
  node_driver_error["Driver exception"]
end

node_application(("Laravel application"))
node_ipwhois_service{{"IPWhoIs service"}}
node_geoplugin_service{{"GeoPlugin service"}}
node_abstractapi_service{{"AbstractApi service"}}
node_ipdata_service{{"IPData service"}}

node_application -->|"calls lookup"| node_facade
node_application -->|"uses macro"| node_request_macro
node_request_macro -->|"calls lookup"| node_facade
node_provider -->|"registers"| node_manager
node_provider -->|"registers"| node_request_macro
node_facade -->|"resolves binding"| node_manager
node_manager -->|"reads settings"| node_config
node_manager -->|"checks and stores"| node_memory_cache
node_manager -->|"reads and writes"| node_laravel_cache
node_manager -->|"invokes driver"| node_driver_contract
node_config -->|"configures"| node_ipwhois
node_config -->|"configures"| node_geoplugin
node_config -->|"configures"| node_abstractapi
node_config -->|"configures"| node_ipdata
node_ipwhois -->|"extends"| node_base_driver
node_ipdata -->|"extends"| node_base_driver
node_base_driver -->|"implements"| node_driver_contract
node_base_driver -->|"uses"| node_endpoint
node_base_driver -->|"uses"| node_http
node_base_driver -->|"uses"| node_response_format
node_ipwhois -->|"calls lookup"| node_http
node_ipdata -->|"calls lookup"| node_http
node_http -->|"requests URL"| node_endpoint
node_http -->|"throws on failure"| node_driver_error
node_manager -->|"catches and reports"| node_driver_error
node_endpoint -->|"merges parameters"| node_array_helper
node_response_format -->|"reads fields"| node_array_helper
node_ipwhois -.->|"queries"| node_ipwhois_service
node_geoplugin -.->|"queries"| node_geoplugin_service
node_abstractapi -.->|"queries"| node_abstractapi_service
node_ipdata -.->|"queries"| node_ipdata_service

click node_request_macro "https://github.com/makidizajnerica/laravel-geolocation/blob/main/src/GeoLocationServiceProvider.php"
click node_facade "https://github.com/makidizajnerica/laravel-geolocation/blob/main/src/Facades/GeoLocation.php"
click node_provider "https://github.com/makidizajnerica/laravel-geolocation/blob/main/src/GeoLocationServiceProvider.php"
click node_config "https://github.com/makidizajnerica/laravel-geolocation/blob/main/config/geolocation.php"
click node_manager "https://github.com/makidizajnerica/laravel-geolocation/blob/main/src/GeoLocationManager.php"
click node_memory_cache "https://github.com/makidizajnerica/laravel-geolocation/blob/main/src/GeoLocationManager.php"
click node_laravel_cache "https://github.com/makidizajnerica/laravel-geolocation/blob/main/src/GeoLocationManager.php"
click node_base_driver "https://github.com/makidizajnerica/laravel-geolocation/blob/main/src/GeoLocationDriver.php"
click node_driver_contract "https://github.com/makidizajnerica/laravel-geolocation/blob/main/src/Contracts/GeoLocationDriver.php"
click node_ipwhois "https://github.com/makidizajnerica/laravel-geolocation/blob/main/src/Drivers/IPWhoIs.php"
click node_geoplugin "https://github.com/makidizajnerica/laravel-geolocation/blob/main/src/Drivers/GeoPlugin.php"
click node_abstractapi "https://github.com/makidizajnerica/laravel-geolocation/blob/main/src/Drivers/AbstractApi.php"
click node_ipdata "https://github.com/makidizajnerica/laravel-geolocation/blob/main/src/Drivers/IPData.php"
click node_endpoint "https://github.com/makidizajnerica/laravel-geolocation/blob/main/src/Support/ApiEndpointFormatter.php"
click node_http "https://github.com/makidizajnerica/laravel-geolocation/blob/main/src/Support/HandlingHttpResponse.php"
click node_response_format "https://github.com/makidizajnerica/laravel-geolocation/blob/main/src/Support/ResponseDataFormatter.php"
click node_array_helper "https://github.com/makidizajnerica/laravel-geolocation/blob/main/src/Support/Arr.php"
click node_driver_error "https://github.com/makidizajnerica/laravel-geolocation/blob/main/src/Exceptions/GeoLocationDriverException.php"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_request_macro,node_facade,node_provider toneBlue
class node_config,node_manager,node_memory_cache,node_laravel_cache toneAmber
class node_base_driver,node_driver_contract,node_ipwhois,node_geoplugin,node_abstractapi,node_ipdata,node_abstractapi_service toneMint
class node_endpoint,node_http,node_response_format,node_array_helper,node_driver_error toneRose
class node_application,node_ipwhois_service,node_geoplugin_service,node_ipdata_service toneIndigo
```

## Components

### Laravel entry points

- [Request macro](https://github.com/makidizajnerica/laravel-geolocation/blob/main/src/GeoLocationServiceProvider.php): `src/GeoLocationServiceProvider.php`
- [GeoLocation facade](https://github.com/makidizajnerica/laravel-geolocation/blob/main/src/Facades/GeoLocation.php): `src/Facades/GeoLocation.php`
- [Service provider](https://github.com/makidizajnerica/laravel-geolocation/blob/main/src/GeoLocationServiceProvider.php): `src/GeoLocationServiceProvider.php`

### Lookup orchestration

- [Driver configuration](https://github.com/makidizajnerica/laravel-geolocation/blob/main/config/geolocation.php): `config/geolocation.php`
- [Lookup manager](https://github.com/makidizajnerica/laravel-geolocation/blob/main/src/GeoLocationManager.php): `src/GeoLocationManager.php`
- [Request memory cache](https://github.com/makidizajnerica/laravel-geolocation/blob/main/src/GeoLocationManager.php): `src/GeoLocationManager.php`
- [Laravel cache](https://github.com/makidizajnerica/laravel-geolocation/blob/main/src/GeoLocationManager.php): `src/GeoLocationManager.php`

### Provider drivers

- [Driver base](https://github.com/makidizajnerica/laravel-geolocation/blob/main/src/GeoLocationDriver.php): `src/GeoLocationDriver.php`
- [Driver contract](https://github.com/makidizajnerica/laravel-geolocation/blob/main/src/Contracts/GeoLocationDriver.php): `src/Contracts/GeoLocationDriver.php`
- [IPWhoIs driver](https://github.com/makidizajnerica/laravel-geolocation/blob/main/src/Drivers/IPWhoIs.php): `src/Drivers/IPWhoIs.php`
- [GeoPlugin driver](https://github.com/makidizajnerica/laravel-geolocation/blob/main/src/Drivers/GeoPlugin.php): `src/Drivers/GeoPlugin.php`
- [AbstractApi driver](https://github.com/makidizajnerica/laravel-geolocation/blob/main/src/Drivers/AbstractApi.php): `src/Drivers/AbstractApi.php`
- [IPData driver](https://github.com/makidizajnerica/laravel-geolocation/blob/main/src/Drivers/IPData.php): `src/Drivers/IPData.php`

### Driver support

- [Endpoint formatter](https://github.com/makidizajnerica/laravel-geolocation/blob/main/src/Support/ApiEndpointFormatter.php): `src/Support/ApiEndpointFormatter.php`
- [HTTP response handling](https://github.com/makidizajnerica/laravel-geolocation/blob/main/src/Support/HandlingHttpResponse.php): `src/Support/HandlingHttpResponse.php`
- [Response formatter](https://github.com/makidizajnerica/laravel-geolocation/blob/main/src/Support/ResponseDataFormatter.php): `src/Support/ResponseDataFormatter.php`
- [Array helper](https://github.com/makidizajnerica/laravel-geolocation/blob/main/src/Support/Arr.php): `src/Support/Arr.php`
- [Driver exception](https://github.com/makidizajnerica/laravel-geolocation/blob/main/src/Exceptions/GeoLocationDriverException.php): `src/Exceptions/GeoLocationDriverException.php`

### Other components

- **Laravel application**
- **IPWhoIs service**
- **GeoPlugin service**
- **AbstractApi service**
- **IPData service**

## Connections

- Laravel application → GeoLocation facade: calls lookup (evidence: `README.md`)
- Laravel application → Request macro: uses macro (evidence: `README.md`)
- Request macro → GeoLocation facade: calls lookup (evidence: `src/GeoLocationServiceProvider.php`)
- Service provider → Lookup manager: registers (evidence: `src/GeoLocationServiceProvider.php`)
- Service provider → Request macro: registers (evidence: `src/GeoLocationServiceProvider.php`)
- GeoLocation facade → Lookup manager: resolves binding (evidence: `src/GeoLocationServiceProvider.php`)
- Lookup manager → Driver configuration: reads settings (evidence: `src/GeoLocationManager.php`)
- Lookup manager → Request memory cache: checks and stores (evidence: `src/GeoLocationManager.php`)
- Lookup manager → Laravel cache: reads and writes (evidence: `src/GeoLocationManager.php`)
- Lookup manager → Driver contract: invokes driver (evidence: `src/GeoLocationManager.php`)
- Driver configuration → IPWhoIs driver: configures (evidence: `config/geolocation.php`)
- Driver configuration → GeoPlugin driver: configures (evidence: `config/geolocation.php`)
- Driver configuration → AbstractApi driver: configures (evidence: `config/geolocation.php`)
- Driver configuration → IPData driver: configures (evidence: `config/geolocation.php`)
- IPWhoIs driver → Driver base: extends (evidence: `src/Drivers/IPWhoIs.php`)
- IPData driver → Driver base: extends (evidence: `src/Drivers/IPData.php`)
- Driver base → Driver contract: implements (evidence: `src/GeoLocationDriver.php`)
- Driver base → Endpoint formatter: uses (evidence: `src/GeoLocationDriver.php`)
- Driver base → HTTP response handling: uses (evidence: `src/GeoLocationDriver.php`)
- Driver base → Response formatter: uses (evidence: `src/GeoLocationDriver.php`)
- IPWhoIs driver → HTTP response handling: calls lookup (evidence: `src/Drivers/IPWhoIs.php`)
- IPData driver → HTTP response handling: calls lookup (evidence: `src/Drivers/IPData.php`)
- HTTP response handling → Endpoint formatter: requests URL (evidence: `src/Support/HandlingHttpResponse.php`)
- HTTP response handling → Driver exception: throws on failure (evidence: `src/Support/HandlingHttpResponse.php`)
- Lookup manager → Driver exception: catches and reports (evidence: `src/GeoLocationManager.php`)
- Endpoint formatter → Array helper: merges parameters (evidence: `src/Support/ApiEndpointFormatter.php`)
- Response formatter → Array helper: reads fields (evidence: `src/Support/ResponseDataFormatter.php`)
- IPWhoIs driver → IPWhoIs service: queries
- GeoPlugin driver → GeoPlugin service: queries
- AbstractApi driver → AbstractApi service: queries
- IPData driver → IPData service: queries
