Color Captcha Bundle Laravel Package

Getting Started

This is a Symfony bundle that wraps the yamilovs/color-captcha image generator (a “pick/name the color” CAPTCHA) and exposes it as a route + form type + validator. Treat it as legacy code: last release was January 2019, zero dependents, and it targets the Symfony 3.4/4.x era. Verify everything you read below against the actual package on install — class names and service IDs should be confirmed, not assumed.

Minimal path to a working captcha:

composer require yamilovs/color-captcha-bundle

Then:

1. Enable the bundle. In Symfony 3.x/4.0–4.1: new Yamilovs\ColorCaptchaBundle\ColorCaptchaBundle() in AppKernel::registerBundles(). In 4.2+: add it to config/bundles.php. Confirm the real namespace with composer show yamilovs/color-captcha-bundle — the vendor prefix may be Yamilovs\Bundle\....
2. Import the routes. The bundle ships its own routing for the image endpoint (bin/console debug:router | grep -i captcha to find the name). Import with the pre-Symfony-5 @ColorCaptchaBundle/Resources/config/routing.xml notation, or copy the route definition into your own config/routes.yaml — you will likely have to do the latter on modern Symfony.
3. Check your image backend. The underlying library needs GD (or Imagick, if supported). php -m | grep -i gd first; a missing extension is the single most common “blank captcha” cause.
4. Configure defaults under the color_captcha: key (key name to be confirmed from the bundle’s DependencyInjection/Configuration.php): width/height, color palette, background, and font if applicable.
5. Add it to a form — the intended first use case is a contact/registration form: add the bundle’s form type (something like ColorCaptchaType) to your FormType, render form_row(), and let the bundled constraint validate the submitted value against the session-stored answer.

Before writing any code, read vendor/yamilovs/color-captcha-bundle/ in this order: DependencyInjection/Configuration.php → Resources/config/services.* → Form/ → Validator/ → Controller/. That’s the whole bundle; it’s small enough to read end-to-end in fifteen minutes, which is exactly what you should do given how little documentation survives.

Implementation Patterns

Form-type integration (the happy path). The package is designed around a Symfony form type plus a validator constraint. You add the field, Symfony renders the <img> pointing at the bundle route, the user answers, and the constraint compares the submission to the value cached in the session. This is the only pattern with any real chance of working out of the box on an old Symfony install.

Manual controller integration. For login forms or non-form flows, point an <img src="{{ path('...captcha_route') }}"> at the bundle route and validate the POST manually — pull the expected answer from the session yourself, or reuse the constraint through $this->validator->validate($value, new ColorCaptcha()) if the constraint is standalone. This is useful when you can’t use Symfony Forms (e.g. a hand-rolled login).

Refresh-on-click. The image URL is stateless from the browser’s point of view, but the answer lives in the session. Add a cache-busting query string (?t= + timestamp) on a “reload” button so the browser re-fetches and the session answer regenerates. Don’t rely on Cache-Control alone.

Per-form configuration. Instantiate the form type with options (palette, dimensions) rather than relying on global config, so a compact login captcha and a larger registration captcha can coexist. This requires the generator service to accept runtime overrides — check whether the bundle’s service is shared: false or factory-built; if it isn’t, you’ll need to define your own service definition.

Test environment bypass. Add an env check in the validator (or swap the constraint for a no-op via a service override in config/services_test.yaml) so functional tests and CI don’t need to OCR an image. Because the answer is session-backed, tests can also seed the session with the expected value directly — cleaner than disabling validation.

Swapping the generator. The bundle is a thin adapter over yamilovs/color-captcha. If you keep this package long-term, decorate or replace the generator service with your own implementation of the library’s interface — that’s the cleanest extension point and it isolates you from future (or abandoned) releases.

Gotchas and Tips

• It is effectively abandoned. January 2019 means Symfony 4.2-era conventions. Expect breakage on Symfony 5+ from @Bundle/Resources/... notation (removed in 5.0), removed Symfony\Component\HttpKernel\Bundle\Bundle helpers, and PHP 8 issues (dynamic properties, each(), implicit nullable params). Budget for forking or vendoring rather than assuming composer require just works.
• Zero stars, zero dependents, score 0.03. There is no community to debug this with you. Read the source, don’t Google for answers — there aren’t any.
• Blank or broken image is almost always: GD not installed, output already sent (whitespace/BOM before <?php, or a debug toolbar injecting output), or headers overwritten. Test the image route directly in a browser before blaming the form.
• The image route must never be cached. CDNs, Symfony’s HTTP cache, and browser back/forward caches will serve a stale image whose answer no longer matches the session. Set Cache-Control: no-store, no-cache, must-revalidate and consider a nonce in the URL.
• Session coupling breaks stateless/API usage. The answer lives server-side in the session. JSON APIs, token-authenticated clients, and anything behind a load balancer without sticky sessions will fail intermittently. Don’t try to make this work in a headless context — pick a different captcha.
• Color captchas are weakly secure and poorly accessible. A determined script can sample pixel colors; screen-reader users are locked out entirely. If you ship this on a public form, pair it with rate limiting and provide an accessible alternative. For a production login, prefer a maintained solution (hCaptcha/Turnstile, or a honeypot + timing check).
• Debugging tips: bin/console debug:router | grep -i captcha, bin/console debug:container | grep -i captcha, and bin/console debug:config color_captcha (if the extension is registered) will reveal the actual service IDs and route names far faster than reading stale docs. Enable twig debug and inspect the rendered <img src>.
• Extension points, in order of usefulness: (1) override the form type/constraint in your own namespace, (2) redefine the generator service in services.yaml, (3) override the bundle’s templates by placing files under templates/bundles/ColorCaptchaBundle/. Avoid patching vendor/ directly — use composer.json repositories with a VCS fork, or cweagans/composer-patches if you need a one-line fix.
• Recommendation: given the maintenance status, treat this as a short-term or throwaway integration. If the color-captcha concept fits your UX, depend directly on yamilovs/color-captcha and write ~50 lines of Symfony glue yourself — you’ll own the code, control the Symfony version compatibility, and avoid a dead bundle in your dependency tree.