{"id":20522621,"url":"https://github.com/ocalasans/samp-query-php","last_synced_at":"2025-03-06T00:42:09.913Z","repository":{"id":254391838,"uuid":"845780580","full_name":"ocalasans/samp-query-php","owner":"ocalasans","description":"PHP API to make requests and extract data from SA-MP (San Andreas Multiplayer) servers.","archived":false,"fork":false,"pushed_at":"2024-11-02T04:47:42.000Z","size":214,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-01-16T10:47:46.270Z","etag":null,"topics":["api","networking","php","query","sa-mp","sa-mp-development","samp","server","server-query","server-status"],"latest_commit_sha":null,"homepage":"","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ocalasans.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-08-21T23:10:27.000Z","updated_at":"2025-01-15T15:06:40.000Z","dependencies_parsed_at":"2025-01-16T10:41:46.829Z","dependency_job_id":"bcbe4d57-a3d7-40f5-88e3-3fa3d56f74d4","html_url":"https://github.com/ocalasans/samp-query-php","commit_stats":null,"previous_names":["ocalasans/samp-query-php"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ocalasans%2Fsamp-query-php","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ocalasans%2Fsamp-query-php/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ocalasans%2Fsamp-query-php/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ocalasans%2Fsamp-query-php/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ocalasans","download_url":"https://codeload.github.com/ocalasans/samp-query-php/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":242128317,"owners_count":20076177,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api","networking","php","query","sa-mp","sa-mp-development","samp","server","server-query","server-status"],"created_at":"2024-11-15T22:36:13.299Z","updated_at":"2025-03-06T00:42:09.903Z","avatar_url":"https://github.com/ocalasans.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"# samp-query-php\r\n\r\n**samp-query-php** é uma **API** em **PHP** desenvolvida para consultar e obter informações de servidores **SA-MP (San Andreas Multiplayer)**. Esta **API** permite que você verifique se um servidor está online, obtenha o ping, informações básicas e detalhadas sobre o servidor, jogadores conectados e regras do servidor. A **API** também inclui um sistema de tentativas automáticas para garantir que os dados sejam obtidos de forma confiável.\r\n\r\n### Idiomas\r\n\r\n- Deutsch: [README](translations/Deutsch/README.md)\r\n- English: [README](translations/English/README.md)\r\n- Español: [README](translations/Espanol/README.md)\r\n- Français: [README](translations/Francais/README.md)\r\n- Italiano: [README](translations/Italiano/README.md)\r\n- Polski: [README](translations/Polski/README.md)\r\n- Русский: [README](translations/Русский/README.md)\r\n- Svenska: [README](translations/Svenska/README.md)\r\n- Türkçe: [README](translations/Turkce/README.md)\r\n\r\n## Índice\r\n\r\n- [samp-query-php](#samp-query-php)\r\n    - [Idiomas](#idiomas)\r\n  - [Índice](#índice)\r\n  - [Características](#características)\r\n  - [Instalação](#instalação)\r\n  - [Uso](#uso)\r\n    - [Exemplo de uso básico](#exemplo-de-uso-básico)\r\n    - [Exemplo com múltiplos servidores](#exemplo-com-múltiplos-servidores)\r\n  - [Métodos Disponíveis](#métodos-disponíveis)\r\n    - [Verificar se o servidor está online](#verificar-se-o-servidor-está-online)\r\n    - [Obter ping do servidor](#obter-ping-do-servidor)\r\n    - [Obter informações do servidor](#obter-informações-do-servidor)\r\n    - [Obter lista de jogadores](#obter-lista-de-jogadores)\r\n      - [Lista Básica](#lista-básica)\r\n      - [Lista Detalhada](#lista-detalhada)\r\n    - [Obter regras do servidor](#obter-regras-do-servidor)\r\n  - [Detalhes Técnicos](#detalhes-técnicos)\r\n    - [Sistema de tentativas](#sistema-de-tentativas)\r\n    - [Timeouts configuráveis](#timeouts-configuráveis)\r\n    - [Construção de pacotes](#construção-de-pacotes)\r\n    - [Conversão de dados](#conversão-de-dados)\r\n  - [Customizações e Configurações](#customizações-e-configurações)\r\n    - [Configurações avançadas de timeout](#configurações-avançadas-de-timeout)\r\n    - [Mensagens de erro e tratamento de exceções](#mensagens-de-erro-e-tratamento-de-exceções)\r\n  - [Licença](#licença)\r\n    - [Condições:](#condições)\r\n\r\n## Características\r\n\r\n- Consulta rápida e eficiente de servidores **SA-MP**.\r\n- Requisição de informações básicas e detalhadas do servidor.\r\n- Possibilidade de obtenção de dados sobre jogadores e regras do servidor.\r\n- Sistema de tentativas automático para garantir a obtenção dos dados.\r\n- Configuração de timeouts para conexão e resposta.\r\n- Fechamento automático do socket ao término da operação.\r\n- Suporte a múltiplos idiomas para informações do servidor.\r\n- Limitação personalizada para a exibição de jogadores.\r\n\r\n## Instalação\r\n\r\nClone o repositório para sua máquina local:\r\n\r\n```bash\r\ngit clone https://github.com/ocalasans/samp-query-php.git\r\n```\r\n\r\n## Uso\r\n\r\nInclua o arquivo `samp_query.php` no seu projeto e instancie a classe `Samp_Query` passando o endereço IP e a porta do servidor **SA-MP** que deseja consultar.\r\n\r\n### Exemplo de uso básico\r\n\r\n```php\r\nrequire 'samp_query.php';\r\n\r\n$server = new Samp_Query('127.0.0.1', 7777);\r\n\r\nif ($server-\u003eIs_Online()) {\r\n    echo \"Servidor está online!\";\r\n    echo \"Ping: \" . $server-\u003eGet_Ping() . \" ms\";\r\n    \r\n    $info = $server-\u003eGet_Information();\r\n    print_r($info);\r\n    \r\n    $players = $server-\u003eGet_Players_0();\r\n    print_r($players);\r\n    \r\n    $rules = $server-\u003eGet_Rules();\r\n    print_r($rules);\r\n} else {\r\n    echo \"Servidor está offline.\";\r\n}\r\n```\r\n\r\n### Exemplo com múltiplos servidores\r\n\r\n```php\r\nrequire 'samp_query.php';\r\n\r\n$servidores = [\r\n    ['ip' =\u003e '127.0.0.1', 'porta' =\u003e 7777],\r\n    ['ip' =\u003e '192.168.0.1', 'porta' =\u003e 7778],\r\n];\r\n\r\nforeach ($servers as $data) {\r\n    $server = new Samp_Query($data['ip'], $data['porta']);\r\n    \r\n    if ($server-\u003eIs_Online()) {\r\n        echo \"Servidor \" . $data['ip'] . \":\" . $data['porta'] . \" está online!\";\r\n        echo \"Ping: \" . $server-\u003eGet_Ping() . \" ms\\n\";\r\n    } else {\r\n        echo \"Servidor \" . $data['ip'] . \":\" . $data['porta'] . \" está offline.\\n\";\r\n    }\r\n}\r\n```\r\n\r\n## Métodos Disponíveis\r\n\r\n### Verificar se o servidor está online\r\n\r\n```php\r\npublic function Is_Online()\r\n```\r\n\r\nRetorna `true` se o servidor estiver online, caso contrário, `false`. A verificação é realizada ao tentar conectar-se ao servidor e enviar um pacote inicial. Se a conexão falhar, o servidor é considerado offline.\r\n\r\n### Obter ping do servidor\r\n\r\n```php\r\npublic function Get_Ping()\r\n```\r\n\r\nRetorna o ping do servidor em milissegundos, calculado com base no tempo que leva para o pacote ser enviado e a resposta ser recebida. Se o servidor estiver offline ou não puder obter o ping, retorna `null`.\r\n\r\n### Obter informações do servidor\r\n\r\n```php\r\npublic function Get_Information()\r\n```\r\n\r\nRetorna um array com informações básicas do servidor, como:\r\n\r\n- `passworded`: Indica se o servidor é protegido por senha.\r\n- `players`: Número atual de jogadores.\r\n- `maxplayers`: Número máximo de jogadores permitido.\r\n- `hostname`: Nome do servidor.\r\n- `gamemode`: Modo de jogo do servidor.\r\n- `language`: Idioma utilizado no servidor.\r\n\r\nEste método faz uso do sistema de tentativas automáticas para garantir que os dados sejam obtidos corretamente.\r\n\r\n### Obter lista de jogadores\r\n\r\n#### Lista Básica\r\n\r\n```php\r\npublic function Get_Players_0()\r\n```\r\n\r\nRetorna um array com a lista de jogadores conectados, contendo `nickname` e `score` (pontuação) de cada jogador. Esse método é adequado para obter uma visão geral dos jogadores conectados.\r\n\r\n#### Lista Detalhada\r\n\r\n```php\r\npublic function Get_Players_1()\r\n```\r\n\r\nRetorna um array com informações detalhadas sobre cada jogador, incluindo `playerid`, `nickname`, `score` e `ping`. Esse método fornece dados mais profundos sobre os jogadores conectados.\r\n\r\n### Obter regras do servidor\r\n\r\n```php\r\npublic function Get_Rules()\r\n```\r\n\r\nRetorna um array com as regras do servidor, onde a chave é o nome da regra e o valor é o valor associado a essa regra. Esse método também utiliza o sistema de tentativas para assegurar a obtenção dos dados.\r\n\r\n## Detalhes Técnicos\r\n\r\n### Sistema de tentativas\r\n\r\nA API incorpora um sistema de tentativas (`retry_limit`) que permite tentar a obtenção de informações até três vezes antes de desistir. Isso aumenta a confiabilidade, especialmente em situações onde a conexão pode ser instável.\r\n\r\n### Timeouts configuráveis\r\n\r\nAo instanciar a classe `Samp_Query`, dois tipos de timeouts são configurados:\r\n\r\n- `timeouts['connect']`: Define o tempo máximo em segundos para estabelecer uma conexão com o servidor. O padrão é 1 segundo.\r\n- `timeouts['response']`: Define o tempo máximo em segundos para esperar uma resposta do servidor após o envio de um pacote. O padrão é 120 segundos que já é um tempo extremamente alto.\r\n\r\nEsses timeouts garantem que a API não fique indefinidamente aguardando uma resposta, melhorando a eficiência.\r\n\r\n### Construção de pacotes\r\n\r\nOs pacotes de consulta ao servidor **SA-MP** são construídos manualmente, utilizando o prefixo `'SAMP'` seguido pelo endereço IP do servidor e pela porta. Dependendo do tipo de informação solicitada (`i`, `c`, `d`, `r`), o comando correspondente é adicionado ao pacote.\r\n\r\n### Conversão de dados\r\n\r\nA API inclui um método privado `To_Int()` que converte dados binários recebidos do servidor para inteiros. Esse método garante que os dados sejam manipulados corretamente, mesmo em casos de grandes valores.\r\n\r\n```php\r\nprivate function To_Int($data)\r\n```\r\n\r\nO método utiliza operações bit a bit para reconstruir o valor inteiro a partir dos dados binários, convertendo as quatro partes separadas de um número inteiro para o formato original.\r\n\r\n## Customizações e Configurações\r\n\r\n### Configurações avançadas de timeout\r\n\r\nÉ possível personalizar os timeouts no momento da instância da classe `Samp_Query`. Por exemplo, para definir o tempo máximo de conexão para 5 segundos e o tempo de resposta para 60 segundos:\r\n\r\n```php\r\n$server = new Samp_Query('127.0.0.1', 7777);\r\n$server-\u003esetTimeouts([\r\n    'connect' =\u003e 5,\r\n    'response' =\u003e 60\r\n]);\r\n```\r\n\r\n### Mensagens de erro e tratamento de exceções\r\n\r\nA API é projetada para capturar erros e falhas de conexão, retornando mensagens de erro claras em caso de falhas. Por exemplo, se um servidor não puder ser alcançado, a API retorna `null` para métodos como `Get_Information()` e `Get_Rules()`.\r\n\r\n```php\r\nif ($server-\u003eGet_Information() === null) {\r\n    echo \"Não foi possível obter informações do servidor.\";\r\n}\r\n```\r\n\r\n## Licença\r\n\r\nEsta API está protegido sob a Licença MIT, que permite:\r\n- ✔️ Uso comercial e privado\r\n- ✔️ Modificação do código fonte\r\n- ✔️ Distribuição do código\r\n- ✔️ Sublicenciamento\r\n\r\n### Condições:\r\n\r\n- Manter o aviso de direitos autorais\r\n- Incluir cópia da licença MIT\r\n\r\nPara mais detalhes sobre a licença: https://opensource.org/licenses/MIT\r\n\r\n**Copyright (c) Calasans - Todos os direitos reservados**\r\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Focalasans%2Fsamp-query-php","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Focalasans%2Fsamp-query-php","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Focalasans%2Fsamp-query-php/lists"}