Download the PHP package codedart/laravel-slide-captcha without Composer

Laravel Slide CAPTCHA

CAPTCHA visual self-hosted para Laravel, baseado no desafio de arrastar uma peça até a posição correta da imagem.

O pacote gera um desafio, recorta uma peça da imagem, salva temporariamente os arquivos gerados em um disco privado, normalmente S3, e retorna URLs internas temporariamente assinadas para o navegador. A posição correta fica somente no backend e é armazenada em cache por poucos segundos.

Introdução

O codedart/laravel-slide-captcha ajuda a proteger formulários Laravel contra envios automatizados.

Use esta biblioteca quando você precisa de um CAPTCHA simples, visual e controlado pela própria aplicação, sem depender de serviços externos como Google reCAPTCHA, hCaptcha ou Cloudflare Turnstile.

Ela resolve um problema comum em formulários públicos:

• Bots enviando formulários de contato.
• Cadastros automatizados.
• Tentativas repetidas em páginas sensíveis.
• Necessidade de validar interação humana sem enviar dados para provedores externos.

O usuário vê uma imagem, arrasta a peça até o ponto correto, gira a peça quando o desafio exigir rotação e, se acertar, recebe um token temporário. Esse token deve ser enviado junto com o formulário final.

Requisitos

• PHP >= 7.4
• Laravel >= 8
• Composer
• Extensão PHP gd
• Cache configurado no Laravel
• Disco de storage privado legível pela aplicação
• Recomendado: Redis para cache
• Recomendado: S3 ou storage compatível com S3 para armazenar as imagens geradas

Dependências usadas pelo pacote:

• illuminate/support
• illuminate/routing
• illuminate/cache
• illuminate/filesystem
• illuminate/http
• illuminate/validation
• intervention/image

Para usar S3 em um projeto Laravel, garanta que o driver esteja instalado e configurado. Em muitos projetos Laravel modernos, isso é feito com:

Depois configure o disco s3 no .env da aplicação Laravel.

Instalação

Instale o pacote com Composer:

O Laravel deve registrar o service provider automaticamente.

Este pacote não exige migrations, não exige publicação de assets e não exige publicação de views para funcionar.

Os assets JavaScript e CSS são servidos por rotas internas do próprio pacote.

Em produção, o pacote serve automaticamente os assets minificados de resources/dist. Os fontes legíveis ficam em resources/assets.

As rotas criadas pelo pacote são:

Para conferir se as rotas foram registradas:

Se você estiver testando este pacote localmente, antes de publicar no Packagist, adicione um repositório path no composer.json da aplicação Laravel:

Depois instale:

Build dos assets

O pacote já inclui os arquivos minificados prontos para uso.

Se você alterar resources/assets/slide-captcha.js ou resources/assets/slide-captcha.css, gere a build novamente:

Esse comando atualiza:

O objetivo é reduzir o tamanho dos arquivos enviados ao navegador e diminuir o custo de parse no dispositivo do usuário.

Testes

Para rodar a suíte de testes do pacote:

Os testes cobrem a máscara puzzle, a rotação, a análise de movimento e a validação angular.

Configuração

A configuração principal é feita pelo .env da aplicação Laravel.

Exemplo realista:

Variáveis disponíveis

SLIDE_CAPTCHA_ENABLED

Ativa ou desativa o CAPTCHA. Use false apenas em ambientes controlados, como testes locais.

SLIDE_CAPTCHA_CACHE_STORE

Define o cache usado para armazenar desafios e tokens. Exemplo: redis. Se ficar vazio, usa o cache padrão do Laravel.

SLIDE_CAPTCHA_TTL

Tempo de validade do desafio, em segundos. Padrão: 120.

SLIDE_CAPTCHA_IMAGE_WIDTH

Largura da imagem do CAPTCHA. Padrão: 320.

SLIDE_CAPTCHA_IMAGE_HEIGHT

Altura da imagem do CAPTCHA. Padrão: 180.

SLIDE_CAPTCHA_PIECE_MIN_SIZE

Tamanho mínimo da peça recortada. Padrão: 42.

SLIDE_CAPTCHA_PIECE_MAX_SIZE

Tamanho máximo da peça recortada. Padrão: 58.

SLIDE_CAPTCHA_TOLERANCE

Margem de erro permitida, em pixels. Padrão: 8.

SLIDE_CAPTCHA_ROTATION_ENABLED

Ativa a rotação obrigatória da peça. Padrão: true.

Quando ativa, o encaixe no background aparece girado, a peça começa em 0° e o usuário precisa girá-la antes de verificar.

SLIDE_CAPTCHA_ROTATION_STEP_DEGREES

Quantidade de graus aplicada a cada clique nos botões de rotação. Padrão: 15.

SLIDE_CAPTCHA_ROTATION_MAX_DEGREES

Maior ângulo aleatório usado pelo desafio. Padrão: 90.

SLIDE_CAPTCHA_ROTATION_TOLERANCE_DEGREES

Margem de erro permitida para a rotação. Padrão: 8.

SLIDE_CAPTCHA_ROUTE_PREFIX

Prefixo das rotas internas do pacote. Padrão: slide-captcha.

SLIDE_CAPTCHA_MIDDLEWARE

Middlewares aplicados às rotas do CAPTCHA. Padrão: web.

SLIDE_CAPTCHA_STORAGE_DISK

Disco onde as imagens geradas serão salvas. Padrão: s3.

SLIDE_CAPTCHA_GENERATED_PATH

Pasta dentro do disco configurado onde as imagens temporárias serão salvas. Padrão: slide-captcha/generated.

SLIDE_CAPTCHA_TEMPORARY_URL_TTL

Tempo de validade das URLs internas assinadas das imagens, em segundos. Padrão: 300.

SLIDE_CAPTCHA_BACKGROUNDS_PATH

Diretório local usado para substituir as imagens base padrão do pacote.

Se esta variável não for definida, o pacote usa as imagens incluídas em:

Você pode usar um caminho absoluto:

Ou um caminho relativo à raiz do projeto Laravel:

O diretório deve conter imagens .jpg, .jpeg, .png ou .webp.

SLIDE_CAPTCHA_VALIDATE_MOVEMENT

Ativa a análise básica do movimento do mouse ou toque. Padrão: true.

SLIDE_CAPTCHA_MOVEMENT_MIN_POINTS

Quantidade mínima de pontos de movimento enviados pelo navegador.

SLIDE_CAPTCHA_MOVEMENT_MIN_DURATION_MS

Duração mínima do movimento, em milissegundos.

SLIDE_CAPTCHA_MOVEMENT_MAX_DURATION_MS

Duração máxima do movimento, em milissegundos.

SLIDE_CAPTCHA_MOVEMENT_MAX_SAME_Y_RATIO

Proporção máxima permitida de movimentos com o mesmo eixo Y. Ajuda a rejeitar movimentos muito lineares.

Proteção DDoS e relatórios de ataque

O pacote inclui uma camada adaptativa para proteger os endpoints internos do CAPTCHA.

Ela atua antes da geração de imagem em:

E registra sinais suspeitos em:

A identidade padrão combina:

• IP do request.
• Hash do user-agent.
• Hash da sessão Laravel, quando existir.

Quando uma identidade excede os limites, o pacote responde com 429:

O header Retry-After também é enviado.

Configuração mínima recomendada:

Use SLIDE_CAPTCHA_DDOS_MODE=monitor se quiser apenas observar e emitir relatórios, sem bloquear tráfego.

Persistência dos relatórios

Os relatórios são gravados por sinks configuráveis.

O padrão é cache temporário:

Você também pode ativar múltiplos sinks:

Sinks disponíveis:

• none: não persiste; apenas emite eventos em tempo real para listeners/broadcast.
• cache: mantém uma janela temporária em cache/Redis.
• database: grava linha a linha em uma tabela.
• s3_batch: acumula em cache e descarrega em arquivo .jsonl no disco configurado.

Para usar banco, publique a migration:

Depois configure:

Para usar batch em S3 ou storage compatível:

Agende o flush no scheduler da aplicação:

Cada arquivo S3 usa JSON Lines: um relatório JSON por linha.

Reverb e eventos em tempo real

O pacote dispara o evento:

Quando SLIDE_CAPTCHA_DDOS_BROADCAST_ENABLED=auto, o evento só é transmitido se broadcasting.default estiver configurado como reverb.

Configuração:

Payload do relatório:

Motivos comuns de ataque ou suspeita:

• rate_limit_new
• rate_limit_verify
• failure_limit
• score_threshold
• validation_failed
• not_found
• used
• expired
• invalid_position
• invalid_rotation
• movement_too_short
• movement_too_fast
• movement_too_slow
• movement_too_linear

Métricas para dashboard próprio

Este pacote não renderiza dashboard. Para consultar métricas e montar sua própria tela, injete SlideCaptchaMetrics.

Exemplo mínimo:

O snapshot retorna:

• total_events
• blocked_events
• by_severity
• by_endpoint
• by_reason
• top_ips
• top_identities
• last_event
• events
• window

Configuração do S3

Configure o disco s3 no .env da aplicação Laravel:

As imagens geradas são privadas. O navegador acessa rotas internas assinadas do pacote; essas rotas leem a imagem no disco configurado, carregam com Intervention e retornam o PNG pela própria aplicação.

O usuário ou role da AWS precisa ter permissão para:

• s3:PutObject
• s3:GetObject
• s3:DeleteObject
• s3:ListBucket, se exigido pela configuração do bucket

Publicar configuração

Não é obrigatório publicar a configuração.

Se quiser customizar o arquivo config/captcha.php, rode:

Também é possível usar a tag antiga slide-captcha-config.

Depois limpe o cache de configuração:

Também é possível publicar a view se quiser alterar o HTML do widget:

Uso básico

Inclua o CAPTCHA no formulário Blade:

O pacote adiciona os campos ocultos automaticamente:

No controller, valide o token:

A regra SlideCaptchaVerified busca o token no cache e apaga o token após o uso. Isso impede reutilização.

Frontend com React e React Native

Além da view Blade incluída neste pacote, você pode usar componentes prontos para aplicações frontend modernas:

• React Web: @codedart/slide-captcha-react
• React Native e Expo: @codedart/slide-captcha-react-native

Esses pacotes não substituem este backend Laravel. Eles apenas consomem os endpoints já criados por esta biblioteca:

O fluxo continua o mesmo:

1. O frontend carrega um desafio.
2. O usuário arrasta e gira a peça, quando houver rotação.
3. O frontend envia a tentativa para /slide-captcha/verify.
4. O backend retorna um token temporário.
5. O formulário final envia slide_captcha_token.
6. O Laravel valida esse token com SlideCaptchaVerified.

React com Laravel Vite e react-hook-form

Use este caminho quando o formulário é renderizado por React dentro de uma aplicação Laravel.

Instale as dependências:

Configure o Vite para compilar React.

Arquivo: vite.config.js

Rotas do login

Arquivo: routes/web.php

Controller do login

Arquivo: app/Http/Controllers/Auth/LoginController.php

Quando você usa o pacote React, o campo essencial é slide_captcha_token. O campo slide_captcha_verified é usado pela view Blade padrão, mas não é obrigatório neste fluxo.

View Blade

Arquivo: resources/views/auth/login.blade.php

Componente React

Arquivo: resources/js/login.tsx

Se o React estiver no mesmo domínio do Laravel, baseUrl pode ser omitido. Se estiver em outro host, configure a URL no .env do Vite:

E informe no componente:

React Native e Expo

Use este caminho quando o CAPTCHA será usado em um aplicativo mobile.

Instale o pacote:

O app mobile precisa chamar uma URL absoluta. Em desenvolvimento, use o IP da sua máquina na rede:

Não use localhost no celular físico, porque localhost aponta para o próprio aparelho.

Para um fluxo mobile simples, você pode expor os endpoints do CAPTCHA por api:

Com essa configuração, use baseUrl apontando para /api:

Se sua aplicação mobile usa Laravel Sanctum com cookies e CSRF, você também pode manter o middleware web, desde que envie cookies e CSRF corretamente. Para a maioria dos apps nativos, usar endpoints de API é mais simples.

Exemplo de tela de login

Arquivo: App.tsx

Rota de login para API

Arquivo: routes/api.php

Arquivo: app/Http/Controllers/Api/LoginController.php

Em produção, use HTTPS para proteger credenciais, cookies e tokens.

Exemplo prático em um projeto real

Este exemplo cria uma página de contato protegida pelo CAPTCHA.

1. Rotas

Arquivo: routes/web.php

2. Controller

Arquivo: app/Http/Controllers/ContactController.php

3. View

Arquivo: resources/views/contact/create.blade.php

O que acontece neste fluxo

1. O usuário abre /contato.
2. A view renderiza o CAPTCHA.
3. O JavaScript chama GET /slide-captcha/new.
4. O pacote gera o desafio e salva as imagens temporárias no S3.
5. O navegador recebe URLs internas assinadas para ver as imagens.
6. O usuário arrasta a peça e, quando a rotação estiver ativa, gira a peça até encaixar.
7. O JavaScript chama POST /slide-captcha/verify.
8. Se estiver correto, o pacote retorna um token.
9. O formulário envia slide_captcha_token.
10. O controller valida o token com SlideCaptchaVerified.

Tratamento de erros

Erro: CAPTCHA não carrega

Verifique se as rotas existem:

Procure por:

Se não aparecerem, limpe caches:

Erro: CSRF token mismatch

O JavaScript envia o CSRF usando a meta tag:

Garanta que essa tag existe no <head> da página.

Erro: imagem do CAPTCHA não abre

O pacote precisa ler as imagens geradas no disco configurado.

Use um disco S3:

E confirme se o S3 está configurado corretamente no Laravel e se a aplicação tem permissão de leitura no caminho configurado em SLIDE_CAPTCHA_GENERATED_PATH.

Erro: nenhuma imagem base encontrada

Mensagem comum:

Causas prováveis:

• SLIDE_CAPTCHA_BACKGROUNDS_PATH aponta para uma pasta inexistente.
• A pasta existe, mas não tem imagens.
• As imagens não são .jpg, .jpeg, .png ou .webp.

Solução:

Depois coloque imagens nessa pasta.

Erro: validação do CAPTCHA inválida ou expirada

Mensagem:

Causas prováveis:

• O usuário demorou demais para enviar.
• O token já foi usado.
• O cache foi limpo.
• O cache configurado na geração é diferente do cache usado na validação.

Solução:

• Use Redis em produção.
• Aumente SLIDE_CAPTCHA_TTL se necessário.
• Não reutilize o mesmo token em mais de um submit.

Respostas do endpoint de verificação

O endpoint POST /slide-captcha/verify pode retornar:

Motivos comuns:

• validation_failed: dados enviados inválidos.
• not_found: desafio expirado ou inexistente.
• used: desafio já usado.
• expired: desafio expirado.
• invalid_position: usuário errou a posição.
• invalid_rotation: usuário errou a rotação da peça.
• movement_too_short: poucos pontos de movimento.
• movement_too_fast: movimento rápido demais.
• movement_too_slow: movimento lento demais.
• movement_too_linear: movimento muito linear.
• ddos_protection: identidade bloqueada temporariamente pela proteção adaptativa.

Boas práticas

• Use SLIDE_CAPTCHA_STORAGE_DISK=s3 em produção.
• Mantenha as imagens geradas privadas.
• Use URLs internas assinadas com TTL curto.
• Use Redis para cache.
• Não valide apenas slide_captcha_verified; valide sempre slide_captcha_token com SlideCaptchaVerified.
• Coloque a validação no controller ou em um Form Request.
• Mantenha as imagens base sem texto, logos ou rostos identificáveis.
• Use imagens com detalhes distribuídos para facilitar o encaixe da peça.
• Não use imagens muito lisas ou muito escuras.
• Em produção, monitore erros de S3 e cache.
• Evite desativar SLIDE_CAPTCHA_VALIDATE_MOVEMENT em produção.

Responsabilidades recomendadas:

• routes/web.php: define as rotas do formulário da sua aplicação.
• Controller: valida o formulário e aplica SlideCaptchaVerified.
• Blade: renderiza o formulário e inclui @include('slide-captcha::captcha').
• .env: configura cache, S3 e comportamento do CAPTCHA.
• Diretório de backgrounds: guarda as imagens base customizadas, se você não quiser usar as imagens padrão do pacote.

Problemas comuns

O botão enviar não valida mesmo após acertar o CAPTCHA

Causa provável: o campo slide_captcha_token não chegou no request.

Solução: confira se o CAPTCHA está dentro da tag <form>.

O JavaScript não carrega

Causa provável: rota de asset não registrada ou cache antigo de rotas.

Solução:

A imagem aparece quebrada

Causa provável: a URL interna assinada expirou, o S3 está sem permissão de leitura ou o disco está mal configurado.

Solução: confira as credenciais AWS e aumente temporariamente:

O CAPTCHA sempre retorna erro de movimento

Causa provável: ambiente de teste automatizado ou navegador bloqueando eventos.

Solução para desenvolvimento:

Não é recomendado deixar isso desativado em produção.

O pacote usa as imagens padrão em vez das minhas

Causa provável: SLIDE_CAPTCHA_BACKGROUNDS_PATH não foi definido ou está errado.

Solução:

Depois rode:

A configuração do .env não muda o comportamento

Causa provável: configuração cacheada.

Solução:

Exemplo final completo

Este exemplo funciona em um projeto Laravel limpo, desde que o pacote esteja instalado e o disco S3 esteja configurado.

.env

Em projetos Laravel mais antigos, a variável do cache padrão pode se chamar CACHE_DRIVER em vez de CACHE_STORE. Use o nome adotado pela sua aplicação.

routes/web.php

app/Http/Controllers/RegisterInterestController.php

resources/views/interest/create.blade.php

Teste rápido

Rode a aplicação:

Acesse:

Resolva o CAPTCHA e envie o formulário.

Se algo falhar, rode:

E confira as configurações de cache e S3 no .env.