Функции PHP для работы с геотаргетингом

Документ описывает, как в шаблонах темы WordPress и в собственном PHP‑коде получать данные геолокации по IP и данные активного региона (локации) с помощью плагина WT Geotargeting Pro.

1. Доступ к данным геолокации по IP (Wt::$geolocation)

После инициализации плагина объект геолокации доступен как:

Wt::$geolocation

1.1. Массив всех геоданных

• Свойство: Wt::$geolocation->data
• Описание: ассоциативный массив с результатами сервиса геолокации.

Типичные ключи: city — город; region — область/регион; district — округ; country — страна; lat — широта; lng — долгота.

Пример: отладочный вывод массива геоданных:

<?php
if ( isset( Wt::$geolocation ) ) {
    echo '<pre>';
    print_r( Wt::$geolocation->data );
    echo '</pre>';
}
?>

1.2. Получение отдельного значения (getValue())

• Метод: Wt::$geolocation->getValue( $attribute )
• Параметр: $attribute — один из ключей массива (city, region, country, lat, lng и др.)
• Возвращает: строку или null

Пример: вывод города, региона и страны по IP:

<?php
if ( isset( Wt::$geolocation ) ) {
    echo esc_html( Wt::$geolocation->getValue( 'city' ) );
    echo esc_html( Wt::$geolocation->getValue( 'region' ) );
    echo esc_html( Wt::$geolocation->getValue( 'country' ) );
}
?>

Рекомендация: использовать для подсказок (например, предустановка города в форме). Для бизнес‑логики по регионам сайта (цены, телефоны, меню) — WT::$location.

2. Активный регион (локация) сайта (WT::$location)

Активная локация определяется с учётом настроек плагина: поддомены, директории, параметр региона в URL, cookie и др. Единая точка доступа:

WT::$location

Важно: в новом коде использовать только WT::$location. WT::$obj->contacts устарел (сохранён для обратной совместимости).

Локация может инициализироваться на раннем этапе из переменной запроса location (query var в URL), что позволяет другим модулям и хукам получать данные локации раньше в процессе загрузки страницы.

2.1. Получение значения атрибута (getValue())

• Метод: WT::$location->getValue( $attribute )
• Параметр: $attribute — ключ данных региона (см. параметры регионов)
• Возвращает: строку (или число) либо null

Типичные ключи: region_id, parent_id, country_id, region, region_name, parent_name, country_name, phone, email, address, admin_email, subdomain, slug, country_iso.

Примеры:

<?php
echo esc_html( WT::$location->getValue( 'region' ) );
echo esc_html( WT::$location->getValue( 'phone' ) );
echo esc_html( WT::$location->getValue( 'address' ) );
echo esc_html( WT::$location->getValue( 'country_name' ) );
echo esc_html( WT::$location->getValue( 'parent_name' ) );
?>

2.2. Пример использования в шаблонах темы

Вывод блока контактов в header.php:

<?php if ( isset( WT::$location ) ) : ?>
    <div class="header-contacts">
        <?php $phone   = WT::$location->getValue( 'phone' ); ?>
        <?php $address = WT::$location->getValue( 'address' ); ?>
        <?php if ( $phone ) : ?>
            <a class="header-contacts__phone" href="tel:<?php echo esc_attr( str_replace( array( ' ', '(', ')', '‒', '-' ), '', $phone ) ); ?>">
                <?php echo esc_html( $phone ); ?>
            </a>
        <?php endif; ?>
        <?php if ( $address ) : ?>
            <span class="header-contacts__address"><?php echo esc_html( $address ); ?></span>
        <?php endif; ?>
    </div>
<?php endif; ?>

Условный вывод блока только для определённого региона:

<?php
if ( isset( WT::$location ) && 'Самара' === WT::$location->getValue( 'region' ) ) {
    ?><div class="banner banner--samara">
        Самарское спец‑предложение: бесплатная доставка по городу.
    </div><?php
}
?>

3. Получение списка регионов и городов

Для работы со списками: WT::$location->getRegionsArray() (массивы) или WtGtLocation::getCities() (объекты WP_Post).

3.1. Массив регионов (WT::$location->getRegionsArray())

• Метод: WT::$location->getRegionsArray( $params = array() )
• Параметры: filter['type'], filter['parent'], columns, hierarchy, item_type, orderby, order и др.

Пример: список городов для выпадающего списка:

<?php
if ( isset( WT::$location ) ) {
    $cities = WT::$location->getRegionsArray( array(
        'filter' => array( 'type' => 'city' ),
    ) );
    if ( ! empty( $cities ) ) : ?>
        <select name="city_id">
            <?php foreach ( $cities as $city_id => $city_name ) : ?>
                <option value="<?php echo esc_attr( $city_id ); ?>">
                    <?php echo esc_html( $city_name ); ?>
                </option>
            <?php endforeach; ?>
        </select>
    <?php endif;
}
?>

Подходит также для модального окна выбора — см. Выбор города и JavaScript API.

3.2. Получение городов как объектов (WtGtLocation::getCities())

• Метод: WtGtLocation::getCities( $options = array() )
• Возвращает: массив объектов WP_Post (post_type = region, region_type = city)

<?php
$cities = WtGtLocation::getCities( array(
    'args' => array(
        'posts_per_page' => -1,
        'orderby'        => 'title',
        'order'          => 'ASC',
    ),
) );
foreach ( $cities as $city ) {
    $subdomain = get_post_meta( $city->ID, 'subdomain', true );
    echo esc_html( $city->post_title );
    if ( $subdomain ) {
        echo ' (' . esc_html( $subdomain ) . ')';
    }
}
?>

4. Устаревшие вызовы и обратная совместимость

В старой документации встречаются: WT::$obj->contacts->getValue(), WT::$obj->contacts->getRegionsArray(). В новом коде использовать WT::$location.

<?php
// СТАРЫЙ (устаревший)
echo esc_html( WT::$obj->contacts->getValue( 'region' ) );

// НОВЫЙ (рекомендуется)
echo esc_html( WT::$location->getValue( 'region' ) );
?>

5. Краткий чек‑лист

• IP‑геолокация: Wt::$geolocation->getValue('city'), Wt::$geolocation->data — для подсказок.
• Регионы сайта: WT::$location->getValue('region'|'phone'|'address'|…) — для цен, контактов, фильтрации.
• Списки регионов: WT::$location->getRegionsArray() или WtGtLocation::getCities().
• Обновление кода: заменять WT::$obj->contacts на WT::$location.