PHPackages                             dominik-eller/geoip - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Utility & Helpers](/categories/utility)
4. /
5. dominik-eller/geoip

ActiveLibrary[Utility & Helpers](/categories/utility)

dominik-eller/geoip
===================

Google Ads GeoTargets CSV updater and lookup as a reusable PHP 8.4 Composer package.

v1.1.0(4mo ago)012MITPHPPHP ^8.4CI failing

Since Nov 12Pushed 2mo agoCompare

[ Source](https://github.com/dominik-eller/geoip)[ Packagist](https://packagist.org/packages/dominik-eller/geoip)[ RSS](/packages/dominik-eller-geoip/feed)WikiDiscussions master Synced 1mo ago

READMEChangelog (2)Dependencies (1)Versions (4)Used By (0)

Deller/GeoIP — Google Ads GeoTargets as a Composer package
==========================================================

[](#dellergeoip--google-ads-geotargets-as-a-composer-package)

Small PHP 8.4 library and CLI to download the official Google Ads GeoTargets list and look up entries by `criteria_id` (aka `loc_physical_ms`).

- Source page:
- Stores a local `geotargets.csv`
- Lookup by `criteria_id` and return a JSON-compatible array
- Includes CLI tools for update and lookup

Installation
------------

[](#installation)

```
composer require dominik-eller/geoip

```

Requirements:

- PHP 8.4+
- ext-zip and ext-json

Quick start (library)
---------------------

[](#quick-start-library)

```
use Deller\GeoIP\GeoTargetsUpdater;
use Deller\GeoIP\GeoTargetsLookup;

// 1) Download/refresh CSV (once or via cron)
$targetDir = __DIR__ . '/var/geodata';
$updater = new GeoTargetsUpdater($targetDir);
$csvPath = $updater->update(); // returns /absolute/path/to/geotargets.csv

// 2) Lookup by criteria_id (aka loc_physical_ms)
$lookup = new GeoTargetsLookup($csvPath);
$result = $lookup->findById(2267);

header('Content-Type: application/json; charset=utf-8');
echo json_encode($result ?: ['error' => 'not_found'], JSON_PRETTY_PRINT | JSON_UNESCAPED_UNICODE);
```

Returned structure on success:

```
{
  "criteria_id": "2267",
  "name": "Germany",
  "canonical_name": "Germany",
  "country_code": "DE",
  "target_type": "Country",
  "status": "Active"
}
```

If not found:

```
{"error": "not_found", "criteria_id": ""}
```

CLI tools
---------

[](#cli-tools)

Two executables are provided via Composer bin:

- `geotargets-update` — downloads the latest CSV
- `geotargets-lookup` — looks up an ID and prints JSON

Examples:

```
# Download to ./data by default
vendor/bin/geotargets-update

# Set custom directory
GEOTARGETS_DIR=/var/data/geo vendor/bin/geotargets-update

# Lookup by ID
vendor/bin/geotargets-lookup 2267

# Or via env var
LOC=2267 vendor/bin/geotargets-lookup

# Custom CSV path
GEOTARGETS_CSV=/var/data/geo/geotargets.csv vendor/bin/geotargets-lookup 2267

```

WordPress Plugin
----------------

[](#wordpress-plugin)

Dieses Paket enthält ein WordPress-Plugin für eine einfache Integration.

### Build (ZIP erstellen)

[](#build-zip-erstellen)

Da das Plugin die Kern-Bibliothek nutzt, aber ohne Composer lauffähig sein soll, muss es "gebaut" werden. Dabei werden die notwendigen Dateien in ein installierbares ZIP-Archiv gepackt.

```
composer build-wp-plugin
```

Das Ergebnis liegt unter `build/deller-geoip-plugin.zip`.

### Installation

[](#installation-1)

1. Erstelle das ZIP-Archiv wie oben beschrieben.
2. Lade das ZIP-Archiv im WordPress-Adminbereich unter **Plugins -> Installieren -> Plugin hochladen** hoch.
3. Alternativ: Kopiere den Inhalt des `wp-plugin` Verzeichnisses manuell in `wp-content/plugins/geoip` und stelle sicher, dass die Dateien aus `src/` ebenfalls im `src/` Ordner des Plugins liegen.
4. Aktiviere das Plugin im WordPress-Adminbereich.

### Features

[](#features)

- **WP-CLI Command**: `wp geoip update` to refresh the GeoTargets data.
    - Optional: `wp geoip update --country=DE` to only download targets for a specific country (reduces file size significantly).
- **WP-CLI Command**: `wp geoip lookup ` to check a specific ID.
- **Helper Function**: Use `deller_geoip_lookup($id)` in your own plugins or themes.
- **Data Storage**: The CSV data is stored in your WordPress uploads directory under `wp-content/uploads/geoip-data/`.
- **Automatic Updates**: The plugin schedules a monthly WP-Cron event (`deller_geoip_update_event`) to keep the data fresh.
    - Tip: You can hook into `deller_geoip_update_event` and pass a country code if you want the automated update to be filtered.

### Manual Cron Trigger

[](#manual-cron-trigger)

If you want to trigger the update via a real system cron job, you have several options:

#### 1. Via Standalone PHP script (Recommended for Plesk/Standard Hosting)

[](#1-via-standalone-php-script-recommended-for-pleskstandard-hosting)

The plugin provides a dedicated script that can be called directly:

```
# Update all targets
php wp-content/plugins/geoip/cron-update.php

# Update only Germany (DE)
php wp-content/plugins/geoip/cron-update.php DE
```

This is the easiest way if you don't have WP-CLI installed.

#### 2. Via WP-CLI

[](#2-via-wp-cli)

```
wp geoip update
```

#### 3. Via Action Hook

[](#3-via-action-hook)

Or hook into the action within your own code:

```
do_action('deller_geoip_update_event');
```

### Example usage in code

[](#example-usage-in-code)

```
$data = deller_geoip_lookup(1004542);
if ($data) {
    echo "Location: " . $data['canonical_name'];
}
```

Web endpoint example
--------------------

[](#web-endpoint-example)

Create `public/geotarget.php` in your app:

```