https://github.com/tito10047/altcha-bundle
A Symfony bundle to help integrate ALTCHA with Symfony forms.
https://github.com/tito10047/altcha-bundle
altcha captcha symfony symfony-bundle
Last synced: 27 days ago
JSON representation
A Symfony bundle to help integrate ALTCHA with Symfony forms.
- Host: GitHub
- URL: https://github.com/tito10047/altcha-bundle
- Owner: tito10047
- License: mit
- Created: 2024-11-24T09:13:47.000Z (11 months ago)
- Default Branch: main
- Last Pushed: 2025-09-10T18:22:58.000Z (28 days ago)
- Last Synced: 2025-09-10T19:35:32.464Z (28 days ago)
- Topics: altcha, captcha, symfony, symfony-bundle
- Language: PHP
- Homepage:
- Size: 137 KB
- Stars: 11
- Watchers: 1
- Forks: 5
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
A simple package to help integrate ALTCHA on Symfony Form.
======================
[](https://github.com/Huluti/altcha-bundle/actions/workflows/tests.yml)
This packages integrates [ALTCHA](https://altcha.org/), a privacy-friendly Captcha alternative, with Symfony forms.
Simply add an `AltchaType` field to your form and this package will automatically check the challenge issue.
> ALTCHA uses a proof-of-work mechanism to protect your website, APIs, and online services from spam and unwanted content.
>
>Unlike other solutions, ALTCHA is free, open-source and self-hosted, does not use cookies nor fingerprinting, does not track users, and is fully compliant with GDPR.
>
> Say goodbye to tedious puzzle-solving and improve your website's UX by integrating a fully automated proof-of-work mechanism.
## Support
- Symfony 6.4+
- PHP 8.2+
## Installation
You can install the package via Composer:
```bash
composer require huluti/altcha-bundle
```
Add bundle into config/bundles.php file:
```php
Huluti\AltchaBundle\HulutiAltchaBundle::class => ['all' => true]
```
Add a config file:
### YML
`config/packages/huluti_altcha.yaml`
```yml
huluti_altcha:
enable: true
hmacKey: 'RANDOM_SECRET_KEY'
floating: true
use_stimulus: false
hide_logo: false
hide_footer: false
when@test:
huluti_altcha:
enable: false
```
### PHP
`config/packages/huluti_altcha.php`:
```php
use Symfony\Component\DependencyInjection\Loader\Configurator\ContainerConfigurator;
return static function (ContainerConfigurator $containerConfigurator): void {
$containerConfigurator->extension('huluti_altcha', [
'enable' => true,
'hmacKey' => 'RANDOM_SECRET_KEY',
'floating' => true,
'use_stimulus' => false,
'hide_logo' => false,
'hide_footer' => false
]);
if ('test' === $containerConfigurator->env()) {
// Disable captcha in test environment
$containerConfigurator->extension('huluti_altcha', [
'enable' => false,
]);
}
};
```
Import bundle routes:
### YML
```yml
huluti_altcha:
resource: '@HulutiAltchaBundle/config/routes.yml'
type: yaml
```
### PHP
```php
$routingConfigurator->import('@HulutiAltchaBundle/config/routes.yml');
```
⚠️ **Important – Security Configuration**
If your application restricts access globally using a rule like:
```yaml
access_control:
- { path: ^/, roles: ROLE_USER }
```
Then the Altcha challenge endpoint (`/huluti_altcha/challenge`) will also be protected by default.
To allow it to be publicly accessible (as intended for the challenge mechanism to work), **you must explicitly add the following rule before the global one**:
```yaml
access_control:
- { path: ^/huluti_altcha/challenge, roles: PUBLIC_ACCESS }
- { path: ^/, roles: ROLE_USER }
```
This ensures that the challenge endpoint is reachable by unauthenticated users, while keeping the rest of your app secure.
### Use with your Symfony Form
Create a form type and insert an AltchaType to add the captcha:
```php
add('name', TextType::class, ['label' => false, 'attr' => ['placeholder' => 'name']])
->add('message', TextareaType::class, ['label' => false, 'attr' => ['placeholder' => 'message']])
->add('security', AltchaType::class, [
'label' => false,
'floating' => true,
'hide_logo' => false,
'hide_footer' => false,
])
->add('submit', SubmitType::class)
;
}
public function configureOptions(OptionsResolver $resolver): void
{
$resolver->setDefaults([
'data_class' => Contact::class,
]);
}
}
```
### Use inside UX Live component or with Stimulus
Asset mapper is required to use this package in the UX Live component or Stimulus.
```composer require symfony/asset-mapper```
There is only one option need to be changed to work with Stimulus or UX Live component.
```yml
huluti_altcha:
floating: false
```
### Optional: usage with Sentinel
Configure the package by providing your sentinel instance endpoint and your API key:
```yml
huluti_altcha:
sentinel:
base_url: 'http://localhost:8080'
api_key: 'key_xxxxxxxxxxxx'
```
Activating this configuration will have the effect to use the sentinel server to generate a new challenge and for it's verification.
If the sentinel instance is not reachable by the client or by the server, we will fallback on our local configuration.
## License
The MIT License (MIT). Please see [License File](LICENSE) for more information.