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: 14 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 (over 1 year ago)
- Default Branch: main
- Last Pushed: 2026-05-19T08:39:15.000Z (24 days ago)
- Last Synced: 2026-05-19T11:19:59.722Z (24 days ago)
- Topics: altcha, captcha, symfony, symfony-bundle
- Language: PHP
- Homepage:
- Size: 11 MB
- Stars: 18
- Watchers: 1
- Forks: 8
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
- Security: SECURITY.md
Awesome Lists containing this project
README
A simple package to help integrate ALTCHA on Symfony Form.
======================
[](https://github.com/Tito10047/altcha-bundle/actions/workflows/ci.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 | 7.4 | 8.0+
- PHP 8.2+
- Webpack | Asset Mapper | Twig
## Installation
You can install the package via Composer:
```bash
composer require tito10047/altcha-bundle
```
Add bundle into config/bundles.php file:
```php
Tito10047\AltchaBundle\AltchaBundle::class => ['all' => true]
```
Add a config file:
### YML
`config/packages/altcha.yaml`
```yml
altcha:
enable: true
hmacSignature: '%env(APP_SECRET)%' # Replaces deprecated hmacKey
hmacAlgorithm: 'SHA-256'
hmacKeySignature: ~ # Optional signature key
cost: 5000
counter_min: 5000
counter_max: 10000
timeout: 30.0
floating: true
overlay: false
use_stimulus: false
include_script: true
hide_logo: false
hide_footer: false
when@test:
altcha:
enable: false
```
Import bundle routes:
### YML
```yml
altcha:
resource: '@AltchaBundle/config/routes.yml'
type: yaml
```
⚠️ **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 (`/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: ^/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,
// Optional: override global config
// 'cost' => 5000,
// 'timeout' => 30.0,
// 'counter_min' => 5000,
// 'counter_max' => 10000,
])
->add('submit', SubmitType::class)
;
}
public function configureOptions(OptionsResolver $resolver): void
{
$resolver->setDefaults([
'data_class' => Contact::class,
]);
}
}
```
### Use with Webpack Encore
```js
//webpack.config.js
module.exports = Encore.getWebpackConfig();
module.exports.resolve.alias["altcha/dist/i18n/all.js"]='altcha/i18n';
```
```yaml
#config/packages/altcha.yaml
altcha:
use_stimulus: true
include_script: false
```
### Optional: usage with UX Live components
There is only one option need to be changed to work with or UX Live component.
```yml
altcha:
use_stimulus: true
floating: false
include_script: false
```
### Optional: usage with Sentinel
Configure the package by providing your sentinel instance endpoint and your API key:
```yml
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.