README

⭐ Found this useful? Install from Packagist · Give it a star on GitHub to help others find it.

Symfony bundle to define signature box coordinates on PDFs. Form type with an in-browser PDF.js viewer: users place and resize signature areas by clicking and dragging. Supports units (mm, cm, pt), validation, proxy for external PDFs, and hooks for PKI/timestamp/batch signing. Symfony 6.1+, 7.x, 8.x · PHP 8.1+.

What is this?

This bundle helps you define signature box coordinates on PDFs in your Symfony applications for:

📄 PDF signature placement — Let users visually place and resize signature areas on a PDF
📐 Units and origin — Work in mm, cm, pt, px or in; choose coordinate origin (e.g. bottom-left)
🔗 External PDFs — Optional proxy to load external PDFs without CORS issues
⚙️ Named configs — Reuse presets (fixed URL, units, limits) via config: 'name' in YAML
✅ Validation — Required box names, unique names per form, min/max entries
🎯 Events — Hook into proxy request/response and coordinate submission for custom logic

Quick Search Terms

Looking for: PDF signature coordinates, signature box placement, PDF.js Symfony, PDF form coordinates, signature position configurator, Symfony PDF viewer, signature overlay, PDF signing workflow, coordinate picker, document signing? You've found the right bundle!

Features

✅ Form type — SignatureCoordinatesType with PDF URL, units (mm, cm, pt, px, in), coordinate origin (corners) and collection of signature boxes
✅ PDF viewer — In-browser viewer (PDF.js) with overlays for each box; click to add, drag to move, drag corners to resize
✅ Optional proxy — Load external PDFs without CORS; configurable via nowo_pdf_signable.proxy_enabled
✅ Named configurations — Define presets in nowo_pdf_signable.configs and use config: 'name' when adding the form type
✅ URL modes — Free-text URL input or dropdown choice (url_mode: choice, url_choices)
✅ Box options — Name as text or dropdown (name_mode: choice); min/max entries; optional unique box names validation; page restriction (allowed_pages); sort order on submit (sort_boxes); no overlapping boxes (prevent_box_overlap, default true); optional rotation (enable_rotation); default values per name (box_defaults_by_name); snap to grid (snap_to_grid) and snap to other boxes (snap_to_boxes, default true); guides and grid (show_grid, grid_step); viewer lazy load (viewer_lazy_load); batch signing (batch_sign_enabled, “Sign all” button). Audit: optional fill from request (audit.fill_from_request), placeholders for TSA and signing service (see SIGNING_ADVANCED)
✅ Viewer — Thumbnails: page strip to jump to a page; Zoom: toolbar (zoom in, zoom out, fit width, translated); Touch: pinch to zoom, two-finger pan on tablets
✅ Validation — Required box name (NotBlank); unique_box_names global (true/false) or per-name (array) to enforce unique box names
✅ Events — PdfProxyRequestEvent, PdfProxyResponseEvent, SignatureCoordinatesSubmittedEvent, BatchSignRequestedEvent, PdfSignRequestEvent for integration (see EVENTS and SIGNING_ADVANCED)
✅ Compatibility — Symfony 6.1+, 7.x, 8.x and PHP 8.1+

Screenshots

Demo index — Each card shows a different way to configure SignatureCoordinatesType (named configs, URL options, box validation, model prefill):

Signature coordinates form — PDF viewer with draggable signature boxes; unit/origin selector and box list on the right:

Signature form (alternate view) — Same form with thumbnails strip, zoom toolbar and optional rotation; boxes can be placed flush to page edges at any angle:

Installation

composer require nowo-tech/pdf-signable-bundle

Symfony Flex registers the bundle automatically. Otherwise see Installation to register the bundle and routes.

Unreleased / dev: To use the latest main branch, add the VCS repo and require dev-main — see docs/INSTALLATION.md.

Quick Start

Add the form type to your form (or use the default route /pdf-signable):

use Nowo\PdfSignableBundle\Form\SignatureCoordinatesType;
use Nowo\PdfSignableBundle\Model\SignatureCoordinatesModel;

$model = new SignatureCoordinatesModel();
$form = $this->createForm(SignatureCoordinatesType::class, $model);
// Or use a named config: ['config' => 'fixed_url']

Render the form with the bundle form theme so the PDF viewer and boxes render correctly:

{% form_theme form '@NowoPdfSignable/form/theme.html.twig' %}
{{ form_widget(form.signatureCoordinates) }}

On submit you get a SignatureCoordinatesModel with pdfUrl, unit, origin and signatureBoxes (each with name, page, x, y, width, height, and angle when enable_rotation is true).

Configure nowo_pdf_signable (proxy, example URL, optional named configs) as needed. See Usage for full options and examples.

Requirements

PHP >= 8.1
Symfony >= 6.1 || >= 7.0 || >= 8.0
Extensions: form, http-client, twig, translation, validator, yaml

Configuration

The bundle works with default settings. Create or edit config/packages/nowo_pdf_signable.yaml:

nowo_pdf_signable:
    proxy_enabled: true                    # Enable proxy for external PDFs (avoids CORS)
    example_pdf_url: ''                    # Optional default URL for form preload
    configs: {}                            # Optional named configs (see CONFIGURATION.md)

See CONFIGURATION.md for detailed options and named configs.

Demos

Dockerized demos (Symfony 7 and 8, Bootstrap, Vite, TypeScript) with multiple usage examples. The screenshots above show the demo home (configuration cards), the signature coordinates form (PDF viewer + boxes), and an alternate view with thumbnails, zoom and rotation.

cd demo
make run-symfony7   # → http://localhost:8000
make run-symfony8   # → http://localhost:8001

Nineteen demos: no config, default config, fixed_url, overridden config, URL as dropdown, limited boxes, same signer (multiple locations), unique per name (array), page restriction, sorted boxes, no-overlap, allow-overlap, rotation, defaults-by-name, snap-to-grid, guides-and-grid, viewer lazy-load, latest features (combined), predefined boxes; plus signing (draw, upload, legal disclaimer, predefined boxes — sign only, signing options). See demo/README.md and demo/Makefile.

Xdebug

Demos include Xdebug. Your IDE should listen on port 9003. To start only on demand, set XDEBUG_START_WITH_REQUEST=trigger in the demo docker-compose.yml and use your IDE trigger.

Frontend (Vite + TypeScript)

The PDF viewer is built with Vite and TypeScript. The bundle ships a built file at src/Resources/public/js/pdf-signable.js. After installing the bundle:

php bin/console assets:install

To rebuild from source (bundle root):

pnpm install
pnpm run build

Tests and QA

From the bundle root (optionally via Docker):

make up
make install
make test          # PHPUnit
make test-coverage # PHPUnit + HTML (coverage/) and Clover (coverage.xml). Requires PCOV in the container.
make cs-check      # PHP-CS-Fixer
make qa            # cs-check + test
make validate-translations  # Validate translation YAML files (inside Docker)

Or locally: composer test, composer test-coverage, composer cs-check, composer qa. The bundle Docker image includes PCOV for coverage.

Documentation

Installation — Step-by-step installation and route registration
Configuration — Proxy, example URL, named configs
Usage — Form options, named configs, customization
Events — Proxy, submission, batch sign and PDF sign request events
Advanced signing — PKI/PAdES, timestamp, audit trail, batch (structure; you add keys and services)
Styles — PDF viewer CSS, handle sizes, single-inclusion
Testing — Test structure and code coverage
Changelog — Version history
Upgrading — Upgrade instructions
Roadmap — Possible improvements and future ideas
Accessibility — Keyboard, screen readers, contrast
Release process — How to create a release and tag
Contributing — How to contribute
Security — Reporting vulnerabilities

License

The MIT License (MIT). Please see LICENSE for more information.

Contributing

We welcome contributions! Please see CONTRIBUTING.md for details on how to contribute to this project. For security issues see SECURITY.md.

Author

Created by Héctor Franco Aceituno at Nowo.tech

nowo-tech / pdf-signable-bundle

Maintainers

Details