{"id":19059585,"url":"https://github.com/vaibhavpandeyvpz/ank","last_synced_at":"2026-06-20T22:31:37.792Z","repository":{"id":57076618,"uuid":"80642423","full_name":"vaibhavpandeyvpz/ank","owner":"vaibhavpandeyvpz","description":"Simple and customizable captcha generation library, runs on PHP \u003e= 5.3.","archived":false,"fork":false,"pushed_at":"2017-02-02T02:06:10.000Z","size":808,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-01-02T12:13:53.463Z","etag":null,"topics":["captcha","form","php","security","validation"],"latest_commit_sha":null,"homepage":null,"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/vaibhavpandeyvpz.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-02-01T17:01:20.000Z","updated_at":"2020-02-11T07:16:11.000Z","dependencies_parsed_at":"2022-08-24T14:55:53.803Z","dependency_job_id":null,"html_url":"https://github.com/vaibhavpandeyvpz/ank","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vaibhavpandeyvpz%2Fank","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vaibhavpandeyvpz%2Fank/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vaibhavpandeyvpz%2Fank/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vaibhavpandeyvpz%2Fank/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/vaibhavpandeyvpz","download_url":"https://codeload.github.com/vaibhavpandeyvpz/ank/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":240113943,"owners_count":19749829,"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":["captcha","form","php","security","validation"],"created_at":"2024-11-09T00:10:53.612Z","updated_at":"2026-06-20T22:31:37.785Z","avatar_url":"https://github.com/vaibhavpandeyvpz.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Ank\n\n[![Latest Version](https://img.shields.io/packagist/v/vaibhavpandeyvpz/ank.svg?style=flat-square)](https://packagist.org/packages/vaibhavpandeyvpz/ank)\n[![Downloads](https://img.shields.io/packagist/dt/vaibhavpandeyvpz/ank.svg?style=flat-square)](https://packagist.org/packages/vaibhavpandeyvpz/ank)\n[![PHP Version](https://img.shields.io/packagist/php-v/vaibhavpandeyvpz/ank.svg?style=flat-square)](https://packagist.org/packages/vaibhavpandeyvpz/ank)\n[![License](https://img.shields.io/packagist/l/vaibhavpandeyvpz/ank.svg?style=flat-square)](LICENSE)\n[![Build Status](https://img.shields.io/github/actions/workflow/status/vaibhavpandeyvpz/ank/tests.yml?branch=main\u0026style=flat-square)](https://github.com/vaibhavpandeyvpz/ank/actions)\n\nA simple, customizable, and modern CAPTCHA generation library for PHP 8.2+. Generate text-based or mathematics-based CAPTCHAs with full control over appearance, fonts, colors, and distortion.\n\n\u003e **Ank** (`अंक`) means \"Number\" in Hindi\n\n![Text CAPTCHA](assets/captcha-anim.gif?raw=true \"Text CAPTCHA\") ![Math CAPTCHA](assets/math-captcha-anim.gif?raw=true \"Math CAPTCHA\")\n\n## Features\n\n- 🎨 **Two CAPTCHA Types**: Text-based alphanumeric codes or simple math problems\n- 🎭 **Highly Customizable**: Colors, fonts, size, quality, and text distortion\n- 🔒 **Secure**: Uses cryptographically secure random number generation\n- 🎯 **One-Time Validation**: CAPTCHA answers are automatically removed after validation\n- 🖼️ **12 Beautiful Fonts**: Hand-picked Google Fonts included\n- 🚀 **Modern PHP**: Built with PHP 8.2+ features (enums, match expressions, strict types)\n- 📦 **Zero Dependencies**: Only requires PHP with GD extension\n- ✅ **Well Tested**: Comprehensive test suite with high code coverage\n\n## Installation\n\nInstall via Composer:\n\n```bash\ncomposer require vaibhavpandeyvpz/ank\n```\n\n## Requirements\n\n- PHP \u003e= 8.2\n- GD extension with FreeType support (for font rendering)\n\n## Quick Start\n\n### Basic Usage\n\n```php\n\u003c?php\n\nuse Ank\\CaptchaGenerator;\nuse Ank\\MathCaptchaGenerator;\n\n// Create a text-based CAPTCHA generator\n$captcha = new CaptchaGenerator();\n\n// Generate and display the CAPTCHA image\nheader('Content-Type: image/jpeg');\necho $captcha-\u003egetCaptcha();\n\n// Later, validate user input\nif ($captcha-\u003eisValid($_POST['captcha_code'])) {\n    // CAPTCHA is valid\n    echo \"Verification successful!\";\n} else {\n    // CAPTCHA is invalid\n    echo \"Invalid CAPTCHA code.\";\n}\n```\n\n### Mathematics CAPTCHA\n\n```php\n\u003c?php\n\nuse Ank\\MathCaptchaGenerator;\n\n// Create a math-based CAPTCHA generator\n$captcha = new MathCaptchaGenerator();\n\n// Generate and display the math problem\nheader('Content-Type: image/jpeg');\necho $captcha-\u003egetCaptcha();\n\n// Validate the answer (user provides numeric answer)\nif ($captcha-\u003eisValid($_POST['answer'])) {\n    echo \"Correct answer!\";\n}\n```\n\n## Advanced Usage\n\n### Customizing Appearance\n\nThe CAPTCHA image can be fully customized using a fluent interface:\n\n```php\n\u003c?php\n\nuse Ank\\CaptchaGenerator;\nuse Ank\\Font;\n\n$captcha = new CaptchaGenerator();\n\n$image = $captcha-\u003egetCaptcha()\n    -\u003esetBackgroundColor('#000000')      // Black background\n    -\u003esetForegroundColor('#FFFFFF')      // White text\n    -\u003esetFont(Font::BANGERS)             // Use Bangers font\n    -\u003esetSize(300, 100)                  // 300x100 pixels\n    -\u003esetQuality(100)                     // Maximum JPEG quality\n    -\u003esetDistortion(15, 8);              // More distortion (angle, offset)\n\nheader('Content-Type: image/jpeg');\necho $image;\n```\n\n### Configuring Text CAPTCHA Length\n\n```php\n\u003c?php\n\nuse Ank\\CaptchaGenerator;\n\n$captcha = new CaptchaGenerator();\n$captcha-\u003esetLength(8);  // Generate 8-character codes\n\n$image = $captcha-\u003egetCaptcha();\n```\n\n### Using Custom Storage\n\nBy default, CAPTCHA answers are stored in `$_SESSION`. You can provide a custom storage array:\n\n```php\n\u003c?php\n\nuse Ank\\CaptchaGenerator;\n\n$customStorage = [];\n$captcha = new CaptchaGenerator($customStorage);\n\n// The CAPTCHA answer will be stored in $customStorage\n$captcha-\u003egetCaptcha('my_captcha_id');\n```\n\n### Multiple CAPTCHAs\n\nYou can generate multiple CAPTCHAs with different IDs:\n\n```php\n\u003c?php\n\nuse Ank\\CaptchaGenerator;\n\n$captcha = new CaptchaGenerator();\n\n// Generate multiple CAPTCHAs\n$image1 = $captcha-\u003egetCaptcha('login_form');\n$image2 = $captcha-\u003egetCaptcha('registration_form');\n$image3 = $captcha-\u003egetCaptcha('contact_form');\n\n// Validate each independently\nif ($captcha-\u003eisValid($_POST['login_captcha'], 'login_form')) {\n    // Login form CAPTCHA is valid\n}\n```\n\n### Available Fonts\n\nThe library includes 12 fonts from Google Fonts:\n\n```php\nuse Ank\\Font;\n\n// All available fonts\nFont::ACME\nFont::BANGERS\nFont::BARRIO\nFont::BREE_SERIF\nFont::FRECKLE_FACE\nFont::GOCHI_HAND\nFont::LUCKIEST_GUY\nFont::PANGOLIN\nFont::RALEWAY\nFont::RIGHTEOUS\nFont::ROBOTO_SLAB\nFont::SANSITA\n\n// Get a random font\n$randomFont = Font::random();\n\n// Get all fonts\n$allFonts = Font::all();\n```\n\n### Color Formats\n\nColors can be specified in multiple formats:\n\n```php\n$image-\u003esetBackgroundColor('#FFFFFF');  // 6-digit hex with #\n$image-\u003esetBackgroundColor('FFFFFF');   // 6-digit hex without #\n$image-\u003esetBackgroundColor('#FFF');     // 3-digit hex with #\n$image-\u003esetBackgroundColor('FFF');        // 3-digit hex without #\n```\n\n## API Reference\n\n### CaptchaGenerator\n\nText-based CAPTCHA generator.\n\n**Methods:**\n\n- `getCaptcha(string $id = 'default'): CaptchaImageInterface` - Generate a new CAPTCHA\n- `isValid(string $input, string $id = 'default'): bool` - Validate user input\n- `setLength(int $length): static` - Set the length of generated codes\n\n### MathCaptchaGenerator\n\nMathematics-based CAPTCHA generator.\n\n**Methods:**\n\n- `getCaptcha(string $id = 'default'): CaptchaImageInterface` - Generate a new math problem\n- `isValid(string $input, string $id = 'default'): bool` - Validate the answer\n\n### CaptchaImage\n\nCAPTCHA image object with customization methods.\n\n**Methods:**\n\n- `getImage(): string` - Generate and return JPEG image data\n- `setBackgroundColor(string $hex): static` - Set background color\n- `setForegroundColor(string $hex): static` - Set text color\n- `setFont(Font $font): static` - Set font\n- `setSize(int $width, int $height): static` - Set image dimensions\n- `setQuality(int $quality): static` - Set JPEG quality (0-100)\n- `setDistortion(int $angle, int $offset): static` - Set text distortion\n- `setText(string $text): static` - Set the text to display\n\n## Error Handling\n\nThe library throws `Ank\\Exception\\ImageGenerationException` if image generation fails:\n\n```php\n\u003c?php\n\nuse Ank\\CaptchaGenerator;\nuse Ank\\Exception\\ImageGenerationException;\n\ntry {\n    $captcha = new CaptchaGenerator();\n    $image = $captcha-\u003egetCaptcha();\n    echo $image-\u003egetImage();\n} catch (ImageGenerationException $e) {\n    // Handle image generation failure\n    error_log('CAPTCHA generation failed: ' . $e-\u003egetMessage());\n    // Fallback or error page\n}\n```\n\n## Security Considerations\n\n1. **One-Time Use**: CAPTCHA answers are automatically removed after validation to prevent replay attacks\n2. **Secure Random**: Uses `random_int()` for cryptographically secure random number generation\n3. **Session Storage**: By default uses PHP sessions, but you can provide custom storage\n4. **Case Sensitive**: Text CAPTCHAs are case-sensitive by design\n\n## Examples\n\n### Complete Form Example\n\n```php\n\u003c?php\n// captcha.php - Generate CAPTCHA image\nsession_start();\n\nuse Ank\\CaptchaGenerator;\n\n$captcha = new CaptchaGenerator();\nheader('Content-Type: image/jpeg');\necho $captcha-\u003egetCaptcha('form_captcha');\n```\n\n```php\n\u003c?php\n// form-handler.php - Validate form submission\nsession_start();\n\nuse Ank\\CaptchaGenerator;\n\n$captcha = new CaptchaGenerator();\n\nif ($captcha-\u003eisValid($_POST['captcha'], 'form_captcha')) {\n    // Process form\n    echo \"Form submitted successfully!\";\n} else {\n    echo \"Invalid CAPTCHA. Please try again.\";\n}\n```\n\n### AJAX Example\n\n```php\n\u003c?php\n// api/captcha.php\nsession_start();\n\nuse Ank\\CaptchaGenerator;\n\n$captcha = new CaptchaGenerator();\n$image = $captcha-\u003egetCaptcha('ajax_captcha');\n\nheader('Content-Type: image/jpeg');\necho $image;\n```\n\n```javascript\n// client-side\nfetch(\"/api/captcha.php\")\n    .then((response) =\u003e response.blob())\n    .then((blob) =\u003e {\n        const img = document.getElementById(\"captcha-image\");\n        img.src = URL.createObjectURL(blob);\n    });\n```\n\n## Testing\n\nRun the test suite:\n\n```bash\ncomposer test\n```\n\nOr with PHPUnit directly:\n\n```bash\nvendor/bin/phpunit\n```\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\nFonts are hand-picked from [Google Fonts](https://fonts.google.com/) and are used in accordance with their licenses.\n\n## Author\n\n**Vaibhav Pandey**\n\n- GitHub: [@vaibhavpandeyvpz](https://github.com/vaibhavpandeyvpz)\n- Email: contact@vaibhavpandey.com\n\n## Changelog\n\nSee [GitHub Releases](https://github.com/vaibhavpandeyvpz/ank/releases) for the changelog.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvaibhavpandeyvpz%2Fank","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvaibhavpandeyvpz%2Fank","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvaibhavpandeyvpz%2Fank/lists"}