Данные о местоположении IP полезны, когда вашему приложению Laravel требуется разумное региональное значение по умолчанию, контекст часового пояса, обогащение аналитики или дополнительный сигнал риска. Для интеграции не требуется большой пакет или сложный SDK.

С помощью IPRout вы можете отправить адрес IPv4 или IPv6 на простую конечную точку HTTP и получить информацию о GeoIP и сети в формате JSON. В этом уроке мы получим семидневный ключ разработчика, сохраним его вне базы кода и создадим многоразовый сервис Laravel на основе API.

GeoIP — это оценка, полученная на основе IP-адреса. Это не данные GPS, удостоверение личности или точное физическое местоположение пользователя. Предоставьте пользователям возможность исправлять важные варианты выбора, зависящие от местоположения.

Что мы строим

Мы добавим конечную точку в приложение Laravel, которое принимает IP-адрес: 

 GET /geoip?ip=8.8.8.8
 

Приложение проверит введенные данные, запросит у IPRout IP-контекст и вернет ответ, содержащий такие поля, как:

  • Страна, регион и город
  • Часовой пояс
  • Широта и долгота
  • Номер автономной системы (ASN)
  • Сетевая организация

Никакого стороннего пакета PHP не требуется. Встроенный HTTP-клиент Laravel обрабатывает запрос.

Получите семидневный ключ разработчика IPRout

IPRout предоставляет ключ разработчика для оценки API без создания учетной записи. На момент написания ключевое:

  • Действителен в течение семи дней
  • Всего включает 1000 запросов.
  • Не требует входа в систему

Чтобы создать его:

  1. Откройте страницу ключа разработчика IPRout .
  2. Выберите   Создать ключ API .
  3. Скопируйте сгенерированный ключ и сохраните его в безопасном месте.

Относитесь к ключу как к паролю. Не публикуйте его в публикации DEV, не фиксируйте в Git, не раскрывайте его в JavaScript на стороне браузера и не записывайте в журналы приложений.

Допуск к использованию ключа разработчика и условия могут измениться, поэтому проверьте страницу для получения актуальной информации перед публикацией или выполнением этого руководства.

Настроить Ларавел

Добавьте ключ и базовый URL-адрес API в файл   .env   вашего проекта: 

 IPROUT_API_KEY=replace_with_your_key
IPROUT_API_BASE_URL=https://api.iprout.com
 

Затем добавьте запись IPRout в   config/services.php   :
.

 'iprout' => [
    'key' => env('IPROUT_API_KEY'),
    'base_url' => env('IPROUT_API_BASE_URL', 'https://api.iprout.com'),
],
 

Использование уровня конфигурации Laravel исключает вызовы  env()  из кода приложения и работает правильно, когда конфигурация кэшируется в рабочей среде.

Если вы уже кэшировали свою конфигурацию, обновите ее после изменения   .env   : 

 php artisan config:clear
 

Создайте многоразовую службу IPRout.

Создать  app/Services/IPRout.php  : 

 <?php

namespace App\Services;

use Illuminate\Http\Client\Response;
use Illuminate\Support\Facades\Http;
use InvalidArgumentException;
use RuntimeException;

class IPRout
{
    /**
     * Look up GeoIP and ASN information for an IPv4 or IPv6 address.
     *
     * @return array<string, mixed>
     */
    public function lookup(string $ip): array
    {
        if (filter_var($ip, FILTER_VALIDATE_IP) === false) {
            throw new InvalidArgumentException('A valid IPv4 or IPv6 address is required.');
        }

        $apiKey = config('services.iprout.key');

        if (! is_string($apiKey) || $apiKey === '') {
            throw new RuntimeException('The IPRout API key is not configured.');
        }

        $response = Http::baseUrl(config('services.iprout.base_url'))
            ->withToken($apiKey)
            ->acceptJson()
            ->timeout(5)
            ->get('/ip/'.rawurlencode($ip));

        $this->ensureRequestSucceeded($response);

        return $response->json();
    }

    private function ensureRequestSucceeded(Response $response): void
    {
        if ($response->successful()) {
            return;
        }

        $message = match ($response->status()) {
            401 => 'The IPRout API key is missing or invalid.',
            422 => 'IPRout rejected the IP address as invalid.',
            429 => 'The IPRout request limit has been reached.',
            500 => 'IPRout encountered an internal server error.',
            default => 'The IPRout lookup failed with HTTP '.$response->status().'.',
        };

        throw new RuntimeException($message);
    }
}
 

API также поддерживает заголовок  X-API-Key , но метод Laravel  withToken()  делает аутентификацию носителя особенно читабельной: 

 Authorization: Bearer YOUR_API_KEY
 

Пятисекундный тайм-аут не позволяет медленному внешнему запросу занимать рабочую область приложения на неопределенный срок. Выберите тайм-аут производства и резервный вариант на основе собственного бюджета запроса.

Добавить контроллер

Создайте контроллер: 

 php artisan make:controller GeoIPController
 

Замените его содержимое на:
.

 <?php

namespace App\Http\Controllers;

use App\Services\IPRout;
use Illuminate\Http\JsonResponse;
use Illuminate\Http\Request;

class GeoIPController extends Controller
{
    public function __invoke(Request $request, IPRout $iprout): JsonResponse
    {
        $validated = $request->validate([
            'ip' => ['required', 'ip'],
        ]);

        return response()->json(
            $iprout->lookup($validated['ip'])
        );
    }
}
 

Контейнер службы Laravel может автоматически создавать класс  IPRout , поэтому для этой службы не требуется привязка вручную.

Зарегистрировать маршрут

Добавьте маршрут в  routes/web.php   : 

 use App\Http\Controllers\GeoIPController;
use Illuminate\Support\Facades\Route;

Route::get('/geoip', GeoIPController::class);
 

Запустите локальный сервер разработки: 

 php artisan serve
 

Затем выполните поиск с другого терминала: 

 curl "http://127.0.0.1:8000/geoip?ip=8.8.8.8"
 

Успешный ответ имеет следующую форму: 

 {
  "ip": "8.8.8.8",
  "country_code": "US",
  "country": "United States",
  "region": "California",
  "city": "Mountain View",
  "timezone": "America/Los_Angeles",
  "latitude": 37.4056,
  "longitude": -122.0775,
  "asn": 15169,
  "organization": "Google LLC"
}
 

Распределение IP-адресов и наборы данных GeoIP изменяются, поэтому не пишите тесты, требующие общедоступного IP-адреса для возврата одного постоянного города или координаты.

Вместо этого посмотрите IP-адрес вызывающего абонента

IPRout также предоставляет   GET /ip   , который возвращает информацию об IP-адресе, отправляющем запрос API. Это отличается от поиска адреса конечного пользователя по вашему запросу Laravel.

Во многих развертываниях IPRout увидит исходящий IP-адрес вашего сервера приложений, когда вы вызываете   GET /ip   . Если вам нужна информация о посетителе, получите IP-адрес посетителя через Laravel и передайте его  GET /ip/{ip}  .

Будьте осторожны, когда ваше приложение работает за обратным прокси-сервером или балансировщиком нагрузки. Доверяйте пересылаемым IP-заголовкам только в том случае, если Laravel настроен с прокси-серверами, которыми вы управляете. В противном случае клиент может предоставить ложное значение заголовка.

Обрабатывать сбои, не нарушая приложение

Внешний поиск не должен стать единственной точкой отказа. Решите, что будет делать ваше приложение, когда поиск недоступен:

  • Используйте нейтральное значение по умолчанию для дополнительной персонализации.
  • Запишите событие аналитики без полей расширения.
  • Попросите пользователя выбрать свой регион или часовой пояс.
  • Требуйте еще одного сигнала о риске вместо принятия автоматического решения по безопасности.

Задокументированные состояния ошибок IPRout:

Статус Значение
 401  Ключ API отсутствует или недействителен.
 422  Неверный IP-адрес
 429  Скорость ограничена
 500  Внутренняя ошибка сервера

Не повторяйте ответы  401  или  422 , не исправив запрос. Ограниченная повторная попытка с отсрочкой может подойти в случае временной ошибки сервера, но повторные попытки должны оставаться в пределах вашей задержки и ограничений на количество запросов.

Контрольный список производства

Перед развертыванием интеграции:

  • Храните  IPROUT_API_KEY  в секретном хранилище вашей хостинговой платформы.
  • Проверьте каждый предоставленный IP-адрес.
  • Настройте короткий тайм-аут и резервный вариант для конкретного приложения.
  • Избегайте регистрации ключей API или ненужных необработанных IP-адресов.
  • Проверьте, как долго ваше приложение хранит данные, полученные из IP.
  • Кэшируйте повторные запросы только в том случае, если такое поведение соответствует вашим требованиям к актуальности данных и конфиденциальности.
  • Отслеживайте  401  ,  422  ,  429  и ответы об ошибках сервера.
  • Разрешите пользователям исправлять важные настройки по умолчанию для региона или часового пояса.

Начните свой первый поиск GeoIP в Laravel

Теперь у вас есть небольшая интеграция с Laravel с безопасной конфигурацией, проверкой ввода, явной обработкой ошибок и отсутствием дополнительных зависимостей от пакетов.

Создайте семидневный ключ разработчика IPRout , затем воспользуйтесь документацией по API IPRout , когда будете готовы изучить полный контракт запроса.