Download the PHP package tigusigalpa/yandex-smartcaptcha-php without Composer

Yandex SmartCaptcha PHP

PHP for Yandex SmartCaptcha with full Laravel support.

Русская версия

Table of Contents

• Features
• Requirements
• Installation
• Getting Started with Yandex SmartCaptcha
  • Prerequisites
  • Create Yandex Cloud Account
  • Create Captcha in Console
  • Get Captcha Keys
  • Get IAM Token
• Quick Start
• API Methods
• Frontend Integration
• Laravel Validation Rule
• Error Handling
• Logging
• Testing
• Contributing
• Changelog
• Support

Features

• ✅ Complete API Coverage: All SmartCaptcha API methods
• 🔐 Token Validation: Validate user captcha tokens
• 📦 Captcha Management: Create, update, delete, and list captchas
• 🔑 Secret Key Retrieval: Get server secret keys
• 🎨 Laravel Integration: Service provider, facade, and config
• 📝 Type Safety: Full PHP 8.0+ type hints and strict types
• 🪵 PSR-3 Logging: Optional logging support
• 🧪 Well Tested: Comprehensive test coverage
• 📖 Well Documented: Detailed documentation and examples

Requirements

• PHP 8.0 or higher
• Guzzle HTTP client 7.0+
• Laravel 8.0+ (optional, for Laravel integration)

Installation

Install via Composer:

Getting Started with Yandex SmartCaptcha

Prerequisites

Before you begin, you need to set up Yandex Cloud and create a captcha:

1. Create Yandex Cloud Account

1. Go to Yandex Cloud Console
2. Sign in to Yandex Cloud or register if you haven't already
3. On the Yandex Cloud Billing page, make sure you have a billing account linked and it has the ACTIVE or TRIAL_ACTIVE status
4. If you don't have a billing account, create one

2. Create Captcha in Console

1. In the management console, select your folder
2. Select Yandex SmartCaptcha service
3. Click Create captcha
4. Enter a captcha name. Naming requirements:
   • Length: 2 to 63 characters
   • Can contain lowercase Latin letters, numbers, and hyphens
   • First character must be a letter, last character cannot be a hyphen
5. (Optional) Disable domain name verification if needed
6. Specify the list of sites where the captcha will be placed (e.g., example.com)
7. Leave the appearance as standard
8. Configure the default captcha:
   • Select the pre-check type (checkbox or slider)
   • Select the challenge type (image-text task)
   • Choose complexity: Easy, Medium, or Hard
9. (Optional) Enable or disable the use of HTTP request information for ML model training
10. Click Create

3. Get Captcha Keys

After creating the captcha:

1. In the management console, select your folder
2. Select Yandex SmartCaptcha service
3. Click on the captcha name
4. On the Overview tab, copy:
   • Client Key (for frontend widget)
   • Server Key (for backend validation)

4. Get OAuth Token (for API management)

To manage captchas via API, you need an OAuth token. The package will automatically exchange it for an IAM token and refresh it when needed.

Get OAuth Token:

Visit the following URL and authorize the application:

After authorization, you'll receive an OAuth token. Copy it and use it in your application.

Note: The package uses tigusigalpa/yandex-cloud-client-php which handles:

• Automatic OAuth to IAM token exchange
• IAM token caching (valid for 12 hours)
• Automatic token refresh when expired

Now you have:

• ✅ Client Key (for frontend)
• ✅ Server Secret Key (for validation)
• ✅ OAuth Token (for API management - will be auto-exchanged to IAM)
• ✅ Folder ID (from console)

Quick Start

Basic Usage (Pure PHP)

Laravel Usage

1. Publish Configuration

2. Configure Environment

Add to your .env:

Note: The package uses yandex-cloud-client-php for authentication. Your OAuth token will be automatically exchanged for an IAM token and refreshed when needed (IAM tokens expire after 12 hours).

3. Use Facade

API Methods

Token Validation

Validate user captcha token:

Create Captcha

Create a new captcha:

Get Captcha

Get captcha information:

List Captchas

List all captchas in folder:

Update Captcha

Update captcha settings:

Delete Captcha

Delete a captcha:

Get Secret Key

Retrieve server secret key:

Frontend Integration

Basic Widget

Add to your HTML:

Advanced Widget

Laravel Validation Rule

Create custom validation rule:

Use in controller:

Error Handling

All exceptions extend SmartCaptchaException:

Logging

Enable logging in Laravel:

Or pass PSR-3 logger in pure PHP:

Testing

Run tests:

With coverage:

Documentation

• Yandex SmartCaptcha Documentation
• API Reference
• Quick Start Guide

License

MIT License. See LICENSE for details.

Author

Igor Sazonov

• GitHub: @tigusigalpa
• Email: [email protected]

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Development Setup

1. Clone the repository:

2. Install dependencies:

3. Run tests:

Coding Standards

This project follows PSR-12 coding standards:

Pull Request Process

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Changelog

[1.0.0] - 2024-11-29

Added:

• Initial release
• SmartCaptcha client with full API support
• Token validation
• Captcha management (create, read, update, delete, list)
• Secret key retrieval
• Laravel integration (service provider, facade, config)
• PSR-3 logging support
• Comprehensive documentation (EN/RU)
• DTO classes for type safety
• Exception handling
• PHP 8.0+ support with strict types

Support

• GitHub Issues
• Yandex Cloud Support