Weave Code
Yousign Bundle Laravel Package
com-company/yousign-bundle
Bundle Symfony pour intégrer Yousign (API v3, compat v2) : configuration via variables d’environnement, envoi de demandes de signature et gestion des webhooks (routes, listeners/handlers, payloads) avec binding d’événements.
Intégration du service de signature Yousign pour Symfony
Frequently asked questions about Yousign Bundle
- What does com-company/yousign-bundle do?
- It is a Symfony component that integrates the Yousign electronic signature API, covering API v3 with v2 compatibility. It handles configuration through environment variables, sending signature requests, and receiving Yousign webhooks. Webhook payloads are mapped to a WebhookPayload object and dispatched to handlers you register through event bindings.
- Is this package compatible with Laravel?
- Not natively. It is a Symfony bundle that relies on Symfony's service container, YAML configuration, and routing, so it does not ship a Laravel service provider or config file. You can still consume it in Laravel by rebinding its client class in a service provider and wrapping calls behind your own facade or service. Expect to write glue code rather than installing and using it directly.
- How do I install com-company/yousign-bundle?
- Install it with Composer using composer require com-company/yousign-bundle. In Symfony you then register the bundle in your kernel and add the Yousign route resource to config/routes. In Laravel the package will land in vendor but will not self-register, so you must manually wire the client and webhook route.
- Which environment variables are required for Yousign v2 and v3?
- For v3 you need YOUSIGN_V3_URI and YOUSIGN_V3_TOKEN, plus YOUSIGN_V3_ACCESS_KEY if you handle webhooks. For the legacy v2 API you set YOUSIGN_V2_URI, YOUSIGN_V2_APP_URI, YOUSIGN_V2_TOKEN, and YOUSIGN_V2_ACCESS_KEY when webhooks are involved. The sandbox v3 URI is https://api-sandbox.yousign.app/v3/ and production is https://api.yousign.app/v3/.
- How do I receive Yousign webhooks with this bundle?
- Create a yousign.yaml file in config/routes that references @YousignBundle/Resources/config/routes.yaml and sets a prefix. The webhook endpoint becomes {prefix}/webhook/{version}, where version is v2 or v3. You can change the prefix to fit your application's routing conventions.
- How does the event handler binding system work?
- You create classes implementing EventHandlerInterface, which declares handle(WebhookPayload $payload) and onError(YousignException $e). In config/packages/yousign.yaml you list bindings mapping a Yousign event name, such as yousign.webhook.signature.completed, to your service. A handler declared under the default key catches every event that has no explicit binding.
- What is inside WebhookPayload and what about uncommon events?
- WebhookPayload is designed to carry the data of signature_request events, which are the most common. For more specific events, such as identity document verification, the full webhook body is kept untouched in the $rawData property. You can therefore read raw fields directly when the typed properties do not cover your event type.
- Does the bundle support the date_signature_position payload field?
- The date_signature_position field is a payload-level addition, so it requires no architectural change and is sent alongside the rest of the signature request body. There are no Laravel-specific examples for it, so a small wrapper class around the client is the practical way to document and standardise usage. Validate the coordinates structure before sending rather than relying on the remote API to reject bad input.
- How should I handle errors and queue webhook processing in Laravel?
- The bundle surfaces failures as YousignException, and your handler's onError method receives it. In Laravel, catch it and route it through your exception handler or logging channel so failed signatures and malformed payloads are traceable. If you need asynchronous processing, dispatch a queued job from your handler instead of doing the work inline, since the bundle itself does not provide Laravel queue integration.
- What are the risks of wrapping this Symfony bundle in a Laravel app?
- The main risks are container mismatch, since the bundle may depend on Symfony's ContainerInterface which Laravel's service provider must rebind, and hidden dependencies that only appear on minor upgrades. Pin the version you test against and re-run your integration tests after updates. Also monitor for new webhook event types, because future releases could add events that your Laravel event handler does not yet recognise.
Weaver
How can I help you explore Laravel packages today?