Skip to content

Latest commit

 

History

History
244 lines (172 loc) · 13.2 KB

README.md

File metadata and controls

244 lines (172 loc) · 13.2 KB

samp-query-php

samp-query-php - это API на PHP, разработанный для запросов и получения информации с серверов SA-MP (San Andreas Multiplayer). Этот API позволяет проверять онлайн-статус сервера, получать пинг, базовую и подробную информацию о сервере, подключенных игроках и правилах сервера. API также включает систему автоматических повторных попыток для обеспечения надежного получения данных.

Языки

Содержание

Особенности

  • Быстрый и эффективный запрос серверов SA-MP
  • Запрос базовой и подробной информации о сервере
  • Возможность получения данных об игроках и правилах сервера
  • Система автоматических повторных попыток для гарантированного получения данных
  • Настройка тайм-аутов для подключения и ответа
  • Автоматическое закрытие сокета по завершении операции
  • Поддержка нескольких языков для информации о сервере
  • Настраиваемое ограничение для отображения игроков

Установка

Клонируйте репозиторий на ваш локальный компьютер:

git clone /~https://github.com/ocalasans/samp-query-php.git

Использование

Включите файл samp_query.php в ваш проект и создайте экземпляр класса Samp_Query, передав IP-адрес и порт сервера SA-MP, который вы хотите опросить.

Пример базового использования

require 'samp_query.php';

$server = new Samp_Query('127.0.0.1', 7777);

if ($server->Is_Online()) {
    echo "Сервер онлайн!";
    echo "Пинг: " . $server->Get_Ping() . " мс";
    
    $info = $server->Get_Information();
    print_r($info);
    
    $players = $server->Get_Players_0();
    print_r($players);
    
    $rules = $server->Get_Rules();
    print_r($rules);
} else {
    echo "Сервер оффлайн.";
}

Пример с несколькими серверами

require 'samp_query.php';

$servers = [
    ['ip' => '127.0.0.1', 'port' => 7777],
    ['ip' => '192.168.0.1', 'port' => 7778],
];

foreach ($servers as $data) {
    $server = new Samp_Query($data['ip'], $data['port']);
    
    if ($server->Is_Online()) {
        echo "Сервер " . $data['ip'] . ":" . $data['port'] . " онлайн!";
        echo "Пинг: " . $server->Get_Ping() . " мс\n";
    } else {
        echo "Сервер " . $data['ip'] . ":" . $data['port'] . " оффлайн.\n";
    }
}

Доступные методы

Проверка онлайн-статуса сервера

public function Is_Online()

Возвращает true, если сервер онлайн, в противном случае false. Проверка выполняется при попытке подключения к серверу и отправке начального пакета. Если подключение не удалось, сервер считается оффлайн.

Получение пинга сервера

public function Get_Ping()

Возвращает пинг сервера в миллисекундах, вычисленный на основе времени, которое требуется для отправки пакета и получения ответа. Если сервер оффлайн или невозможно получить пинг, возвращает null.

Получение информации о сервере

public function Get_Information()

Возвращает массив с базовой информацией о сервере, такой как:

  • passworded: Указывает, защищен ли сервер паролем
  • players: Текущее количество игроков
  • maxplayers: Максимально допустимое количество игроков
  • hostname: Имя сервера
  • gamemode: Режим игры на сервере
  • language: Язык, используемый на сервере

Этот метод использует систему автоматических повторных попыток для обеспечения правильного получения данных.

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

Базовый список

public function Get_Players_0()

Возвращает массив со списком подключенных игроков, содержащий nickname и score (очки) каждого игрока. Этот метод подходит для получения общего представления о подключенных игроках.

Подробный список

public function Get_Players_1()

Возвращает массив с подробной информацией о каждом игроке, включая playerid, nickname, score и ping. Этот метод предоставляет более глубокие данные о подключенных игроках.

Получение правил сервера

public function Get_Rules()

Возвращает массив с правилами сервера, где ключ - это название правила, а значение - значение, связанное с этим правилом. Этот метод также использует систему повторных попыток для обеспечения получения данных.

Технические детали

Система повторных попыток

API включает систему повторных попыток (retry_limit), которая позволяет пытаться получить информацию до трех раз, прежде чем сдаться. Это повышает надежность, особенно в ситуациях, когда соединение может быть нестабильным.

Настраиваемые тайм-ауты

При создании экземпляра класса Samp_Query настраиваются два типа тайм-аутов:

  • timeouts['connect']: Определяет максимальное время в секундах для установления соединения с сервером. По умолчанию 1 секунда.
  • timeouts['response']: Определяет максимальное время в секундах для ожидания ответа от сервера после отправки пакета. По умолчанию 120 секунд, что является очень высоким значением.

Эти тайм-ауты гарантируют, что API не будет бесконечно ждать ответа, повышая эффективность.

Создание пакетов

Пакеты запросов к серверу SA-MP создаются вручную, используя префикс 'SAMP', за которым следует IP-адрес сервера и порт. В зависимости от типа запрашиваемой информации (i, c, d, r), к пакету добавляется соответствующая команда.

Преобразование данных

API включает приватный метод To_Int(), который преобразует бинарные данные, полученные от сервера, в целые числа. Этот метод гарантирует правильную обработку данных, даже в случае больших значений.

private function To_Int($data)

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

Настройки и конфигурация

Расширенные настройки тайм-аутов

Можно настроить тайм-ауты при создании экземпляра класса Samp_Query. Например, чтобы установить максимальное время подключения 5 секунд и время ответа 60 секунд:

$server = new Samp_Query('127.0.0.1', 7777);
$server->setTimeouts([
    'connect' => 5,
    'response' => 60
]);

Сообщения об ошибках и обработка исключений

API разработан для перехвата ошибок и сбоев подключения, возвращая четкие сообщения об ошибках в случае сбоев. Например, если сервер недоступен, API возвращает null для методов, таких как Get_Information() и Get_Rules().

if ($server->Get_Information() === null) {
    echo "Не удалось получить информацию о сервере.";
}

Лицензия

Этот API защищен лицензией MIT, которая разрешает:

  • ✔️ Коммерческое и частное использование
  • ✔️ Модификацию исходного кода
  • ✔️ Распространение кода
  • ✔️ Сублицензирование

Условия:

  • Сохранение уведомления об авторских правах
  • Включение копии лицензии MIT

Для получения дополнительной информации о лицензии: https://opensource.org/licenses/MIT

Copyright (c) Calasans - Все права защищены