README

🐘 Evolution API PHP SDK

SDK PHP orientado a objetos para a Evolution API v2

Instâncias, mensagens, grupos, perfil, chatbots e eventos — com DTOs tipados,
tratamento de erros consistente e cobertura de contrato de todos os endpoints.

🌟 Visão geral

O Evolution PHP SDK padroniza integrações com a Evolution API em projetos PHP. Ele abstrai a complexidade das requisições HTTP cruas e entrega uma base de código tipada, documentada e fácil de usar.

De um chatbot simples a um sistema de automação multi-tenant, o SDK mantém seu código limpo, testável e escalável.

SDK não oficial. "Evolution API" é um projeto de terceiros.

🚀 Funcionalidades

Orientado a objetos — API fluente ($client->instances()->create(...)).
Type safety — DTOs para payloads de mensagens.
Cobertura completa — Instâncias, Mensagens, Chats, Grupos, Perfil, Settings, Labels, Chamadas, Templates, Storage (S3), Proxy, Métricas, Webhook/Eventos e Chatbots.
Contratos — HttpClientInterface / EvolutionClientInterface para mock em testes.
Webhooks — WebhookHandler para parsear eventos recebidos.
Logging PSR-3 — com redação automática de credenciais e payloads.
Autenticação — API Key global e por instância, mais Basic Auth para métricas.
Padrões — PSR-12 + ruleset do projeto, verificado no CI.

📦 Instalação

composer require leandronunes07/evolution-php-sdk

Requer PHP 8.3+.

⚡ Início rápido

use LeandroNunes\Evolution\Config;
use LeandroNunes\Evolution\EvolutionClient;
use LeandroNunes\Evolution\DTO\Message\TextMessageDTO;

$client = new EvolutionClient(new Config(
    baseUrl: 'https://api.sua-evolution.com',
    globalApiKey: 'SUA_GLOBAL_API_KEY',
));

$response = $client->messages()->sendText('minha-instancia', new TextMessageDTO(
    number: '5511999999999',
    text: 'Olá do SDK PHP! 🐘',
));

print_r($response);

📖 Documentação

EXAMPLES.md — referência método a método de todos os recursos.
CHANGELOG.md — histórico de versões (Keep a Changelog / SemVer).
CONTRIBUTING.md — como rodar testes e contribuir.
SECURITY.md — como reportar vulnerabilidades.

🛠️ Recursos suportados

Instances — create, connect, restart, logout, delete, connectionState, setPresence.
Messages — text, media, audio (PTT), PTV, sticker, status, location, contact, reaction, poll, list, buttons, template.
Chats — read, archive, presence, block/unblock, find chats/messages/contacts, update/delete message.
Groups — create, update (subject/description/picture), participants, settings, invites, ephemeral, leave.
Profile — fetch profile / business profile, update name/status/picture, privacy settings.
Settings / Labels / Calls — configurações da instância, etiquetas do WhatsApp, fake call.
Integrations
- Events — Webhook, Websocket, RabbitMQ, SQS, NATS, Pusher.
- Chatbots — Typebot, OpenAI, Dify, Flowise, N8N, EvoAI, EvolutionBot, Chatwoot.
Storage — recuperação de mídia via S3.
Proxy — set / find do proxy da instância.
Metrics — texto Prometheus cru (Basic Auth).
Utilities — WebhookHandler para eventos recebidos.

🧪 Testes

composer install
composer test        # phpunit
composer cs:check    # php-cs-fixer (dry-run)

Os testes de contrato (tests/Unit/Resources/EndpointContractTest.php) validam verbo, path e payload de cada método contra postman/Version-v2.3.postman_collection.