PHPackages                             hostkurd/flocms-captcha - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Security](/categories/security)
4. /
5. hostkurd/flocms-captcha

ActiveLibrary[Security](/categories/security)

hostkurd/flocms-captcha
=======================

Image captcha package for FloCMS guest form verification.

v1.0.0(3mo ago)0121MITPHPPHP >=8.1

Since Mar 19Pushed 3mo agoCompare

[ Source](https://github.com/hostkurd/flocms-captcha)[ Packagist](https://packagist.org/packages/hostkurd/flocms-captcha)[ RSS](/packages/hostkurd-flocms-captcha/feed)WikiDiscussions main Synced 3w ago

READMEChangelog (1)DependenciesVersions (2)Used By (1)

FloCMS Captcha
==============

[](#flocms-captcha)

A lightweight, framework-friendly image captcha package for **FloCMS**.
Designed for secure guest form verification with minimal dependencies.

---

✨ Features
----------

[](#-features)

- Simple image-based captcha (GD powered)
- Fully customizable (size, fonts, characters, noise, etc.)
- Session-based verification
- Framework-agnostic (works outside FloCMS too)
- PSR-4 autoloaded
- Extensible renderer system (future support for other drivers)

---

📦 Installation
--------------

[](#-installation)

Install via Composer:

```
composer require hostkurd/flocms-captcha
```

### Requirements

[](#requirements)

- PHP >= 8.1
- GD extension enabled (`ext-gd`)

---

🚀 Quick Start
-------------

[](#-quick-start)

### 1. Create captcha instance

[](#1-create-captcha-instance)

```
use FloCMS\Captcha\CaptchaManager;

$captcha = new CaptchaManager();
```

---

### 2. Output captcha image

[](#2-output-captcha-image)

Create a simple endpoint:

```
// public/captcha.php

require dirname(__DIR__) . '/vendor/autoload.php';

use FloCMS\Captcha\CaptchaManager;

$captcha = new CaptchaManager();
$captcha->output();
```

---

### 3. Display in form

[](#3-display-in-form)

```

```

---

### 4. Verify input

[](#4-verify-input)

```
use FloCMS\Captcha\CaptchaManager;

$captcha = new CaptchaManager();

if (!$captcha->verify($_POST['captcha'] ?? null)) {
    die('Invalid captcha');
}
```

---

### 5. Clear after success

[](#5-clear-after-success)

```
$captcha->clear();
```

---

⚙️ Configuration
----------------

[](#️-configuration)

You can override default settings by passing a config array:

```
$captcha = new CaptchaManager([
    'length' => 5,
    'width' => 200,
    'height' => 60,
]);
```

---

### Default Configuration

[](#default-configuration)

```
return [
    'length' => 6,
    'width' => 180,
    'height' => 50,
    'font_size' => 24,
    'angle_min' => -15,
    'angle_max' => 15,
    'noise_lines' => 8,
    'session_key' => 'flocms_captcha',
    'characters' => 'ABCDEFGHJKLMNPQRSTUVWXYZ23456789',
    'case_sensitive' => false,
    'fonts' => [
        __DIR__ . '/../public/fonts/Acme.ttf',
        __DIR__ . '/../public/fonts/PlayfairDisplay.ttf',
        __DIR__ . '/../public/fonts/Ubuntu.ttf',
    ],
];
```

---

🧠 How It Works
--------------

[](#-how-it-works)

1. A random captcha string is generated
2. The string is stored in session
3. An image is rendered using GD
4. User submits input
5. Input is compared securely using `hash_equals`

---

🔐 Security Notes
----------------

[](#-security-notes)

- Uses `random_int()` for cryptographically secure randomness
- Uses `hash_equals()` to prevent timing attacks
- Case-insensitive comparison by default (configurable)
- Always use **CSRF protection alongside captcha**

---

🧩 Architecture
--------------

[](#-architecture)

```
FloCMS\Captcha\
├── Captcha.php          // Logic (generate, store, verify)
├── CaptchaManager.php   // Facade / main API
├── Renderer\
│   ├── RendererInterface.php
│   └── GdRenderer.php   // Image rendering (GD)

```

---

🔄 Session Handling
------------------

[](#-session-handling)

By default, the package uses native PHP sessions:

```
$_SESSION['flocms_captcha']
```

Session is automatically started if not already active.

---

📁 Fonts
-------

[](#-fonts)

Fonts are included inside the package:

```
public/fonts/

```

You can replace or extend them:

```
$captcha = new CaptchaManager([
    'fonts' => [
        '/path/to/custom/font1.ttf',
        '/path/to/custom/font2.ttf',
    ]
]);
```

---

🔌 Extending (Custom Renderer)
-----------------------------

[](#-extending-custom-renderer)

You can create your own renderer by implementing:

```
FloCMS\Captcha\Renderer\RendererInterface
```

Example:

```
use FloCMS\Captcha\Renderer\RendererInterface;

class CustomRenderer implements RendererInterface
{
    public function render(string $text): void
    {
        // your rendering logic
    }
}
```

Then inject it:

```
$captcha = new CaptchaManager([], new CustomRenderer());
```

---

🧪 Example
---------

[](#-example)

Run the included example:

```
php -S localhost:8000 -t examples
```

Then open:

```
http://localhost:8000/basic.php

```

---

🏗️ Integration with FloCMS
--------------------------

[](#️-integration-with-flocms)

Recommended usage:

- Keep captcha as a **separate package**
- Use alongside:
    - `flocms-core` (Session, CSRF, Validation)
- Expose via route or `public/captcha.php`

---

❌ What NOT to Do
----------------

[](#-what-not-to-do)

Avoid placing captcha inside:

```
public/themes/default/

```

Captcha is **application logic**, not a theme asset.

---

🛣️ Roadmap
----------

[](#️-roadmap)

- Session adapter (FloCMS Session integration)
- Multiple captcha drivers (SVG, math captcha, etc.)
- API-based captcha (future support)
- Rate limiting / anti-bruteforce
- Audio captcha support

---

🤝 Contributing
--------------

[](#-contributing)

Contributions are welcome.

- Fork the repository
- Create a feature branch
- Submit a pull request

---

📄 License
---------

[](#-license)

MIT License

---

👤 Author
--------

[](#-author)

**HostKurd**

---

💡 Final Note
------------

[](#-final-note)

This package is intentionally lightweight and modular.
Use it as a drop-in captcha solution or extend it to fit your framework needs.

###  Health Score

36

—

LowBetter than 79% of packages

Maintenance82

Actively maintained with recent releases

Popularity6

Limited adoption so far

Community8

Small or concentrated contributor base

Maturity42

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Unknown

Total

1

Last Release

96d ago

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/14282027?v=4)[Khalat](/maintainers/Khalat)[@khalat](https://github.com/khalat)

---

Top Contributors

[![sarmad-qadir](https://avatars.githubusercontent.com/u/223909750?v=4)](https://github.com/sarmad-qadir "sarmad-qadir (2 commits)")

---

Tags

securitycaptchaformverificationflocms

### Embed Badge

![Health badge](/badges/hostkurd-flocms-captcha/health.svg)

```
[![Health](https://phpackages.com/badges/hostkurd-flocms-captcha/health.svg)](https://phpackages.com/packages/hostkurd-flocms-captcha)
```

###  Alternatives

[gregwar/captcha-bundle

Captcha bundle

3524.8M33](/packages/gregwar-captcha-bundle)[s1syphos/php-simple-captcha

Simple captcha generator

2639.5k9](/packages/s1syphos-php-simple-captcha)[ayesh/stateless-csrf

Secret-key based state-less CSRF token generator and validator for PHP 8. State-less means you do not have to store the CSRF token in session or database.

3224.0k](/packages/ayesh-stateless-csrf)[lorddashme/php-simple-captcha

A simple captcha package that fit to any type of web application built on php.

103.0k](/packages/lorddashme-php-simple-captcha)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)