PHPackages                             forutan/fcaptcha - 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. forutan/fcaptcha

ActiveLibrary[Security](/categories/security)

forutan/fcaptcha
================

Forutan FCaptcha is a secure, modular, image-based CAPTCHA for Laravel with cryptographic protection and multi-context support (login, checkout, etc.). Effectively prevents automated spam in production forms.

1.0.0(6mo ago)01proprietaryPHPPHP ^8.1

Since Oct 25Pushed 6mo agoCompare

[ Source](https://github.com/yaservaziri/ForutanFCaptcha)[ Packagist](https://packagist.org/packages/forutan/fcaptcha)[ Fund](https://yaservaziri.github.io/ForutanFCaptcha/donate.html)[ RSS](/packages/forutan-fcaptcha/feed)WikiDiscussions main Synced 1mo ago

READMEChangelogDependencies (5)Versions (2)Used By (0)

📦 Install via [Packagist](https://packagist.org/packages/forutan/fcaptcha)
🐙 View source on [GitHub](https://github.com/yaservaziri/ForutanFCaptcha)

🛡️ FCaptcha — Laravel Image-Based CAPTCHA
=========================================

[](#️-fcaptcha--laravel-image-based-captcha)

A secure, modular, image-based CAPTCHA for Laravel with cryptographic protection and multi-context support (login, checkout, etc.). Effectively prevents automated spam in production forms.

Table of Contents 📚
-------------------

[](#table-of-contents-)

- [Features](#features)
- [Requirements](#requirements)
- [Installation](#installation)
- [Prepare CAPTCHA Images](#prepare-captcha-images)
- [Middleware Usage](#middleware-usage)
- [Configuration](#configuration)
- [Probability of Random Success](#probability-of-random-success)
- [Contributing](#contributing)
- [Support](#support)
- [Commercial License](#commercial-license)

---

Features
--------

[](#features)

- ✅ Context-aware verification per usage scenario
- 🔐 Tokenized sessions & encrypted image access (no public URLs)
- 🔄 Random image selection + obfuscation each time (e.g. visual noise, distortions)
- 🧠 One-time URLs with secure session binding
- 🛡️ Brute-force protection (retry limits & block durations)
- 🌐 Middleware-ready for any route
- ⚙️ Customizable image count, context behavior, UI
- 🧩 Clean, modern, extendable codebase

---

[![FCaptcha Preview](assets/fcaptcha.jpg)](assets/fcaptcha.jpg)

---

Requirements
------------

[](#requirements)

To use the `fcaptcha:prepare-images` command, [ImageMagick](https://imagemagick.org/) must be installed and available in your system's PATH:

- **Linux/macOS**: You should have the `convert` command available
- **Windows**: Install ImageMagick and ensure `magick` is accessible in your command prompt

You can verify the installation using:

```
# On Linux/macOS
which convert

# On Windows
where magick

```

---

Installation
------------

[](#installation)

Install via Composer:

```
composer require forutan/fcaptcha

```

Publish the config file (this will copy the default settings to `config/fcaptcha.php`):

```
php artisan vendor:publish --tag=fcaptcha-config

```

---

Prepare CAPTCHA Images
----------------------

[](#prepare-captcha-images)

FCaptcha requires categorized images to generate visual CAPTCHAs. You can prepare your image set using **one of these four methods (in order of priority):**

### 📁 Required Folder Structure (All Methods)

[](#-required-folder-structure-all-methods)

No matter which method you choose — whether a custom path, config value, built-in demo set, or published assets — the images folder must follow this categorized layout:

```
/your_folder
├── cat
│   ├── img1.jpg
│   ├── img2.png
├── dog
│   ├── dog1.jpeg
│   ├── dog2.png
├── flower
│   ├── tulip.jpg
│   ├── rose.png
└── ...

```

- Folder names become categories
- File names can be anything
- Supported formats: `.jpg`, `.jpeg`, `.png`

### ➊ Method 1: Custom folder path (CLI flag)

[](#-method-1-custom-folder-path-cli-flag)

Pass the images folder path directly via `--from`:

```
php artisan fcaptcha:prepare-images --from=/full/path/to/your_folder

```

### ➋ Method 2: Path via Config

[](#-method-2-path-via-config)

Set your path in `config/fcaptcha.php` like this:

```
'image_seed_path' => '/full/path/to/your_folder', // or base_path('your/folder') or ...

```

Then run:

```
php artisan fcaptcha:prepare-images

```

### ➌ Method 3: Use Built-in Demo Images

[](#-method-3-use-built-in-demo-images)

If you don't specify `--from` and leave `image_seed_path` as `null` (in `config/fcaptcha.php` ), FCaptcha will automatically use the built-in demo images from:

```
/vendor/forutan/fcaptcha/database/fcaptcha_seeder

```

In this case, just run:

```
php artisan fcaptcha:prepare-images

```

### ➍ Method 4: Customize Built-in Images

[](#-method-4-customize-built-in-images)

To use and modify the internal demo set:

- Publish them:

```
php artisan vendor:publish --tag=fcaptcha-seeds

```

- Edit the copied files at:

```
storage/app/private/fcaptcha_seeder

```

- Run the preparation:

```
php artisan fcaptcha:prepare-images --from=storage/app/private/fcaptcha_seeder

```

> ⚠️ **Important:** After modifying your image set or resetting the database, **you must re-run** the image preparation command to sync the new data.

---

🎉 FCaptcha is now ready to power your Laravel forms with strong, customizable CAPTCHA protection.
Enjoy secure, bot-resistant interactions — right out of the box 💻🛡️

Middleware Usage
----------------

[](#middleware-usage)

Apply `fcaptcha.verified:{context}` middleware to any route.

### Example: single route

[](#example-single-route)

```
Route::post('/comment', function () {
    // Handle comment
})->middleware('fcaptcha.verified:comment');

```

### Example: group of routes

[](#example-group-of-routes)

```
Route::middleware('fcaptcha.verified:checkout')->group(function () {
    Route::get('/cart', 'CartController@index');
    Route::post('/checkout', 'OrderController@store');
});

```

Each `context` is verified separately.

---

Configuration
-------------

[](#configuration)

FCaptcha comes with customizable UI and behavior. You can tweak both via Blade views and config values.

### 🖌️ Customize the CAPTCHA UI

[](#️-customize-the-captcha-ui)

Publish the default Blade view:

```
php artisan vendor:publish --tag=fcaptcha-views

```

Edit the files under:

```
resources/views/vendor/fcaptcha/

```

You can modify layout, texts, styles, or add your own branding.

### 🛠️ Change Behavior & Limits

[](#️-change-behavior--limits)

Configuration file is located at `config/fcaptcha.php`. It controls core behavior of FCaptcha — including image sizes, retry limits, category logic, and redirect behavior.

Key options:

```
    // Where to load CAPTCHA images from (see docs above).
    'image_seed_path' => null,

    // CAPTCHA image resize dimensions (pixels) and quality.
    'default_width' => 200,
    'default_height' => 200,
    'default_quality' => 80,

    // Font used in images.
    'font_path' => base_path('vendor/forutan/fcaptcha/resources/fonts/lightweight.ttf'),

    // Where to redirect after solving CAPTCHA per context.
    'redirect_on_pass' => [
      'default' => '/',
    ],

    // Number of images shown in grid.
    'image_count' => [
      'default' => 12,
    ],

    // How many correct images required to pass.
    'min_correct' => ['default' => 3],
    'max_correct' => ['default' => 6],

    // Token/session expiration.
    'expire_minutes' => ['default' => 2],

    // Anti-brute-force: retry limits and block times.
    'max_attempts' => ['default' => 3],
    'block_duration_minutes' => ['default' => 60],

    // Route prefix and middleware.
    'route_prefix' => 'fcaptcha',
    'middleware' => ['web'],

    // per-route rate limiting.
    'throttle' => [
        'show' => '100,1',
        'verify' => '100,1',
        'image' => '100,1',
    ],

```

---

Probability of Random Success
-----------------------------

[](#probability-of-random-success)

The probability of randomly solving the CAPTCHA (by pure guessing) is shown below:

> 🎯 **Formula:**
> `P = 1 / C(n, k)`
> where `n = total images` and `k = required correct selections`

Correct Images (k)Combinations (C(12, k))Probability3220~0.45%4495~0.20%5792~0.13%6924~0.11%**Average success chance:** < 0.4% — providing strong protection against bots.

---

Contributing
------------

[](#contributing)

Have ideas for improvements? Found a bug?
Pull requests and issues are warmly welcome — let's make FCaptcha even better together!

---

Support
-------

[](#support)

If you find FCaptcha helpful:

👉 [Donate here](https://yaservaziri.github.io/ForutanFCaptcha/donate.html)

---

Commercial License
------------------

[](#commercial-license)

This project is licensed under a custom non-commercial license. Usage is permitted only for personal and academic purposes. Commercial use of any kind is strictly prohibited. For commercial inquiries, please contact:

👉 [Request license](mailto:forutan.vaziri@gmail.com?subject=Commercial%20License%20Inquiry%20-%20FCaptcha)

###  Health Score

31

—

LowBetter than 68% of packages

Maintenance66

Regular maintenance activity

Popularity2

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity44

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

196d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/155b5058d28cc343eaac583442b2e93186cfacea9f512900b31163cc88d0aad1?d=identicon)[yaservaziri](/maintainers/yaservaziri)

---

Top Contributors

[![yaservaziri](https://avatars.githubusercontent.com/u/107651723?v=4)](https://github.com/yaservaziri "yaservaziri (1 commits)")

### Embed Badge

![Health badge](/badges/forutan-fcaptcha/health.svg)

```
[![Health](https://phpackages.com/badges/forutan-fcaptcha/health.svg)](https://phpackages.com/packages/forutan-fcaptcha)
```

###  Alternatives

[laravel/cashier

Laravel Cashier provides an expressive, fluent interface to Stripe's subscription billing services.

2.5k25.9M106](/packages/laravel-cashier)[laravel/pulse

Laravel Pulse is a real-time application performance monitoring tool and dashboard for your Laravel application.

1.7k12.1M99](/packages/laravel-pulse)[roots/acorn

Framework for Roots WordPress projects built with Laravel components.

9682.1M97](/packages/roots-acorn)[fumeapp/modeltyper

Generate TypeScript interfaces from Laravel Models

196277.9k](/packages/fumeapp-modeltyper)[api-platform/laravel

API Platform support for Laravel

59126.4k6](/packages/api-platform-laravel)[laragear/poke

Keep your forms alive, avoid TokenMismatchException by gently poking your Laravel app

2211.5k](/packages/laragear-poke)

PHPackages © 2026

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