Yousign Bundle Laravel Package

Getting Started

1. Install with Composer (composer require picoss/yousign-bundle). This is a Symfony 2.x-era bundle, so expect an old dependency tree (likely an older Guzzle and no PHP 7.4+/8.x type hints).
2. Register the bundle manually. In legacy Symfony (app/AppKernel.php) add new Picoss\YouSignBundle\PicossYouSignBundle() to the $bundles array; in Symfony 4+ add it to config/bundles.php (Flex won't auto-register it).
3. Configure credentials in config.yml / config/packages/picoss_yousign.yaml. The extension typically exposes an API key plus a sandbox/production switch, e.g.:

   picoss_yousign:
       api_key: "%yousign_api_key%"
       mode: sandbox   # or production
   

   Keep api_key in parameters.yml / env vars, never in committed YAML.
4. Find the wired service before writing code: run bin/console debug:container yousign --show-private (or php app/console container:debug) to see the actual service ID, class, and constructor arguments. The bundle's Resources/config/services.yml is the authoritative source — read it first.
5. First use case: authenticate and create a signature request. Inject the bundle's client service into a controller, create a request, attach a PDF, add a signer, then activate. Treat the client as a thin HTTP wrapper — it will return arrays/objects straight from the YouSign API, not validated DTOs.

Implementation Patterns

• Wrap, don't sprinkle. Never call the bundle client directly from controllers. Create your own SignatureService that depends on the bundle client, normalizes YouSign response arrays into your domain objects, and centralizes retry/logging. This isolates you from the bundle's low maintenance and non-strict return types.
• Domain-flow wiring. The natural integration is event-driven: an order/document is approved → fire a domain event → a listener calls your SignatureService::requestSignature($document, $signers) → persist the returned signature_request ID on your entity → a webhook controller (or polling command) reconciles status changes back to your entity.
• Config-per-environment. Use sandbox in dev/test and production in prod via environment-specific YAML. Because the only real difference is the base URL, this keeps local testing cheap.
• Webhook handling. YouSign callbacks hit your app over HTTP. Register a route outside the bundle, verify the payload against a stored signature request ID you persisted earlier (don't trust the body blindly), and update status asynchronously. Keep the handler idempotent — callbacks can be replayed.
• Testability via alias. Register your SignatureService with an alias and override it in config/services_test.yaml with a fake that records calls. This avoids hitting the real API in test suites; the bundle itself ships no mocking layer.
• Batch operations. For multi-document flows, iterate and create one signature request per document, then store all returned IDs keyed by document. The bundle returns whatever the API sends — often an array with a id field — so handle both success and errors keys explicitly.

Gotchas and Tips

• Symfony version drift is the biggest pitfall. This is a Symfony 2 bundle. In Symfony 4+/5+/6+, autowiring the bundle's services may fail because the definitions aren't typed or are private by default. Define your own service and inject the bundle client explicitly by ID.
• Service IDs are not guaranteed. Don't guess picoss_yousign.client. Grep the bundle's Resources/config/services.yml, or run debug:container to confirm. Aliasing the ID in your own services.yaml protects you against renames.
• Return types are loose. Expect arrays (not objects) with inconsistent keys between sandbox and production. Add your own response validation and throw a domain-specific exception when id or status is missing.
• HTTP client is likely EOL. The underlying Guzzle version will be old; pin it, or re-implement the small bit you need on top of Symfony HttpClient and stop using the bundle client entirely. This is often the cleanest way to keep using the package's config while avoiding a dead HTTP layer.
• Error handling isn't standardized. Yousign's API returns errors in the body with non-2xx status codes. Wrap calls in try/catch, check the status/errors key, and log the full body (redact api_key) — silent failures look like empty arrays.
• No events/extension points. The bundle is minimal — no Symfony events, no DTO mapping. Any cross-cutting needs (retry, logging, rate limiting) belong in your own decorator around the client.
• Low stars / low maintenance. Pin exact versions in composer.json, review the source for the handful of methods you actually use, and keep your SignatureService thin enough that moving off the bundle (e.g., to the official YouSign SDK or direct HTTP calls) is a one-day change rather than a rewrite.
• Mode misconfiguration. Sandbox keys against the production base URL fail with auth errors that look like invalid credentials. When debugging, log the resolved base URL alongside every request to confirm the mode is what you think it is.