Laravel Sign Pad

https://github.com/creagia/laravel-sign-pad
Admin
A Laravel package that allows users to sign documents and optionally generate certified PDFs...
Tokens:38,507
Snippets:279
Trust Score:8.4
License:MIT
Update:1 week ago
Show doc for...
Tokens:
Raw
### InstallCommand constructor sets signature and description

Source: https://github.com/creagia/laravel-sign-pad/blob/main/_autodocs/api-reference/service-provider.md

Assigns the command signature 'sign-pad:install' and description 'Install Laravel Sign Pad' in the constructor. Takes no arguments or options.

```php
public function __construct()
{
    $this->signature = 'sign-pad:install';
    $this->description = 'Install Laravel Sign Pad';

    parent::__construct();
}
```

--------------------------------

### Publish config and migration files with sign-pad:install

Source: https://github.com/creagia/laravel-sign-pad/blob/main/README.md

Run the artisan command to publish configuration and migration files, then migrate the database.

```bash
php artisan sign-pad:install
```

--------------------------------

### Install laravel-sign-pad via Composer

Source: https://github.com/creagia/laravel-sign-pad/blob/main/README.md

Install the package using Composer. Requires PHP 8.2-8.5 and Laravel 11-13.

```bash
composer require creagia/laravel-sign-pad
```

--------------------------------

### getSignedDocumentPath() example

Source: https://github.com/creagia/laravel-sign-pad/blob/main/_autodocs/api-reference/signature.md

Example usage of getSignedDocumentPath() showing the returned relative path.

```php
echo $myModel->signature->getSignedDocumentPath();
// "signed_documents/document-04d28fe4-3f4f-48f1-a8ce-7d6c3a26be4e.pdf"
```

--------------------------------

### Add RequiresSignature trait and implement CanBeSigned

Source: https://github.com/creagia/laravel-sign-pad/blob/main/README.md

Prepare a model for signing by adding the RequiresSignature trait and implementing the CanBeSigned contract. This is the minimal setup required to use the package.

```php
<?php

namespace App\Models;

use Creagia\LaravelSignPad\Concerns\RequiresSignature;
use Creagia\LaravelSignPad\Contracts\CanBeSigned;

class MyModel extends Model implements CanBeSigned
{
    use RequiresSignature;

}

?>
```

--------------------------------

### InstallCommand handle method publishes config and migrations

Source: https://github.com/creagia/laravel-sign-pad/blob/main/_autodocs/api-reference/service-provider.md

Silently publishes the 'sign-pad-config' and 'sign-pad-migrations' tags, then interactively asks whether to run migrations and whether to open the GitHub repository in the default browser. Platform-specific commands are chosen by PHP_OS_FAMILY: 'open' on Darwin, 'start' on Windows, 'xdg-open' on Linux.

```php
public function handle(): void
{
    $this->info('Publishing config file...');

    $this->callSilently('vendor:publish', [
        '--tag' => 'sign-pad-config',
    ]);

    $this->info('Publishing migration...');

    $this->callSilently('vendor:publish', [
        '--tag' => 'sign-pad-migrations',
    ]);

    if ($this->confirm('Would you like to run the migrations now?')) {
        $this->comment('Running migrations...');

        $this->call('migrate');
    }

    if ($this->confirm('Would you like to star our repo on GitHub?')) {
        $repoUrl = 'https://github.com/creagia/laravel-sign-pad';

        if (PHP_OS_FAMILY == 'Darwin') {
            exec("open {$repoUrl}");
        }
        if (PHP_OS_FAMILY == 'Windows') {
            exec("start {$repoUrl}");
        }
        if (PHP_OS_FAMILY == 'Linux') {
            exec("xdg-open {$repoUrl}");
        }
    }

    $this->info('sign-pad has been installed!');
}
```

--------------------------------

### Customize sign pad component with Tailwind

Source: https://github.com/creagia/laravel-sign-pad/blob/main/README.md

Blade component example showing how to pass customization properties: border-color, pad-classes, button-classes, clear-name, submit-name, and disabled-without-signature.

```html
<x-creagia-signature-pad
    border-color="#eaeaea"
    pad-classes="rounded-xl border-2"
    button-classes="bg-gray-100 px-4 py-2 rounded-xl mt-4"
    clear-name="Clear"
    submit-name="Submit"
    :disabled-without-signature="true"
/>
```

--------------------------------

### configurePackage method in LaravelSignPadServiceProvider

Source: https://github.com/creagia/laravel-sign-pad/blob/main/_autodocs/api-reference/service-provider.md

Defines the package configuration for laravel-sign-pad, registering config, views, routes, assets, a Blade component, a migration, and the install command. The method is part of the LaravelSignPadServiceProvider class which extends Spatie\LaravelPackageTools\PackageServiceProvider.

```php
public function configurePackage(Package $package): void
{
    $package
        ->name('laravel-sign-pad')
        ->hasConfigFile()
        ->hasViews('laravel-sign-pad')
        ->hasRoute('web')
        ->hasAssets()
        ->hasViewComponent('creagia', SignaturePad::class)
        ->hasMigration('create_signatures_table')
        ->hasCommand(InstallCommand::class);
}
```

--------------------------------

### Publish JavaScript assets with sign-pad-assets tag

Source: https://github.com/creagia/laravel-sign-pad/blob/main/README.md

Publish the package's JavaScript assets to the public/vendor/sign-pad/ folder.

```bash
php artisan vendor:publish --tag=sign-pad-assets
```

--------------------------------

### POST /creagia/sign-pad Example Request

Source: https://github.com/creagia/laravel-sign-pad/blob/main/_autodocs/endpoints.md

Example HTTP request to the signature endpoint. The form must include the CSRF token (`_token`) and the base64 PNG data URL (`sign`). The `model`, `id`, and `token` parameters are appended as query string parameters by `RequiresSignature::getSignatureRoute()`.

```http
POST /creagia/sign-pad?model=App%5CModels%5CMyModel&id=1&token=1a2b3c4d... HTTP/1.1
Host: example.com
Content-Type: application/x-www-form-urlencoded

_token=abc123...&sign=data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8z8BQDwAEhQGAhKmMIQAAAABJRU5ErkJggg==
```

--------------------------------

### Create SSL certificate with OpenSSL

Source: https://github.com/creagia/laravel-sign-pad/blob/main/README.md

Run this command in the storage/app directory to generate a self-signed SSL certificate for PDF certification. The certificate is saved as certificate.crt in the current directory.

```bash
cd storage/app
openssl req -x509 -nodes -days 365000 -newkey rsa:1024 -keyout certificate.crt -out certificate.crt
```

--------------------------------

### getSignatureImagePath() example

Source: https://github.com/creagia/laravel-sign-pad/blob/main/_autodocs/api-reference/signature.md

Example usage of getSignatureImagePath() showing the returned relative path.

```php
echo $myModel->signature->getSignatureImagePath();
// "signatures/04d28fe4-3f4f-48f1-a8ce-7d6c3a26be4e.png"
```

--------------------------------

### getSignedDocumentAbsolutePath() example with null handling

Source: https://github.com/creagia/laravel-sign-pad/blob/main/_autodocs/api-reference/signature.md

Example usage of getSignedDocumentAbsolutePath() with error handling for the nullable result. Checks for null and returns early if no PDF document was generated.

```php
$path = $myModel->signature->getSignedDocumentAbsolutePath();

if ($path === null) {
    // Model was signed, but no PDF document was generated
    // (the model does not implement ShouldGenerateSignatureDocument).
    return;
}

echo $path;
```

--------------------------------

### getSignatureImageAbsolutePath() example

Source: https://github.com/creagia/laravel-sign-pad/blob/main/_autodocs/api-reference/signature.md

Example usage of getSignatureImageAbsolutePath() showing the returned absolute path.

```php
echo $myModel->signature->getSignatureImageAbsolutePath();
// "/var/www/html/storage/app/private/signatures/04d28fe4-...-.png"
```

--------------------------------

### Retrieve signature image and document paths

Source: https://github.com/creagia/laravel-sign-pad/blob/main/README.md

PHP code to output the signature image path and the generated PDF document path using the model's signature relation.

```php
echo $myModel->signature->getSignatureImagePath();
echo $myModel->signature->getSignedDocumentPath();
```

--------------------------------

### Example Success Response (302 Redirect)

Source: https://github.com/creagia/laravel-sign-pad/blob/main/_autodocs/endpoints.md

Successful signing returns a 302 redirect to the configured `redirect_route_name` with the `uuid` of the created signature as a query parameter. The `Location` header carries the UUID.

```http
HTTP/1.1 302 Found
Location: http://example.com/signature/thanks?uuid=04d28fe4-3f4f-48f1-a8ce-7d6c3a26be4e
```

--------------------------------

### Consuming the uuid on the redirect route

Source: https://github.com/creagia/laravel-sign-pad/blob/main/_autodocs/endpoints.md

Example of defining the redirect route in `routes/web.php` and configuring `redirect_route_name` in `config/sign-pad.php`. The route receives the `uuid` query parameter from the redirect.

```php
// routes/web.php
Route::get('/signature/thanks', function (Illuminate\Http\Request $request) {
    $uuid = $request->query('uuid');

    return "Your signature reference is: {$uuid}";
})->name('signature.thanks');

// config/sign-pad.php
'redirect_route_name' => 'signature.thanks',
```

--------------------------------

### Create sign pad form with signature route

Source: https://github.com/creagia/laravel-sign-pad/blob/main/README.md

Blade template that renders the sign pad canvas and submits to the model's signature route. Includes the required JavaScript asset. The form is only shown when the model has not been signed yet.

```html
@if (!$myModel->hasBeenSigned())
    <form action="{{ $myModel->getSignatureRoute() }}" method="POST">
        @csrf
        <div style="text-align: center">
            <x-creagia-signature-pad />
        </div>
    </form>
    <script src="{{ asset('vendor/sign-pad/sign-pad.min.js') }}"></script>
@endif
```

--------------------------------

### Blade template for the document

Source: https://github.com/creagia/laravel-sign-pad/blob/main/_autodocs/api-reference/document-templates.md

Example Blade view that uses the $model variable to display contract details.

```blade
{{-- resources/views/pdf/my-pdf-blade-template.blade.php --}}
<h1>Contract for {{ $model->name }}</h1>
<p>Drawn up on {{ $model->created_at->format('d/m/Y') }}.</p>
```

--------------------------------

### Deleting a signature - usage example

Source: https://github.com/creagia/laravel-sign-pad/blob/main/_autodocs/api-reference/requires-signature.md

Shows how to delete a signature and handle the case where no signature record exists. The $deleted variable is true when a signature was deleted, false otherwise.

```php
$deleted = $myModel->deleteSignature();

if (! $deleted) {
    // Model had no signature record.
}
```

--------------------------------

### Implement ShouldGenerateSignatureDocument with getSignatureDocumentTemplate

Source: https://github.com/creagia/laravel-sign-pad/blob/main/README.md

Extend the model to generate PDF documents with the signature. Implement the ShouldGenerateSignatureDocument contract and define the document template using getSignatureDocumentTemplate. The template can be a Blade or PDF template, and signature positions are specified per page. A $model object is automatically injected into the Blade template.

```php
<?php

namespace App\Models;

use Creagia\LaravelSignPad\Concerns\RequiresSignature;
use Creagia\LaravelSignPad\Contracts\CanBeSigned;
use Creagia\LaravelSignPad\Contracts\ShouldGenerateSignatureDocument;
use Creagia\LaravelSignPad\Templates\BladeDocumentTemplate;
use Creagia\LaravelSignPad\Templates\PdfDocumentTemplate;
use Creagia\LaravelSignPad\SignatureDocumentTemplate;
use Creagia\LaravelSignPad\SignaturePosition;

class MyModel extends Model implements CanBeSigned, ShouldGenerateSignatureDocument
{
    use RequiresSignature;
    
    public function getSignatureDocumentTemplate(): SignatureDocumentTemplate
    {
        return new SignatureDocumentTemplate(
            outputPdfPrefix: 'document', // optional
            // template: new BladeDocumentTemplate('pdf/my-pdf-blade-template'), // Uncomment for Blade template
            // template: new PdfDocumentTemplate(storage_path('pdf/template.pdf')), // Uncomment for PDF template
            signaturePositions: [
                 new SignaturePosition(
                     signaturePage: 1,
                     signatureX: 20,
                     signatureY: 25,
                 ),
                 new SignaturePosition(
                     signaturePage: 2,
                     signatureX: 25,
                     signatureY: 50,
                 ),
            ]               
        );
    }
}

?>
```

--------------------------------

### Usage in model implementing ShouldGenerateSignatureDocument

Source: https://github.com/creagia/laravel-sign-pad/blob/main/_autodocs/api-reference/signature-document-template.md

Example of returning a SignatureDocumentTemplate from getSignatureDocumentTemplate() on a model. Uses BladeDocumentTemplate with a Blade view and a single SignaturePosition. Constructor arguments are validated later at document-generation time; invalid config values throw InvalidConfiguration.

```php
use App\Models\MyModel;
use Creagia\LaravelSignPad\Contracts\CanBeSigned;
use Creagia\LaravelSignPad\Contracts\ShouldGenerateSignatureDocument;
use Creagia\LaravelSignPad\Concerns\RequiresSignature;
use Creagia\LaravelSignPad\SignatureDocumentTemplate;
use Creagia\LaravelSignPad\SignaturePosition;
use Creagia\LaravelSignPad\Templates\BladeDocumentTemplate;
use Illuminate\Database\Eloquent\Model;

class MyModel extends Model implements CanBeSigned, ShouldGenerateSignatureDocument
{
    use RequiresSignature;

    public function getSignatureDocumentTemplate(): SignatureDocumentTemplate
    {
        return new SignatureDocumentTemplate(
            outputPdfPrefix: 'document',
            template: new BladeDocumentTemplate('pdf/my-pdf-blade-template'),
            signaturePositions: [
                new SignaturePosition(signaturePage: 1, signatureX: 20, signatureY: 25),
            ],
        );
    }
}
```

--------------------------------

### Delete model signature

Source: https://github.com/creagia/laravel-sign-pad/blob/main/README.md

PHP code to delete the model's signature using the deleteSignature() method.

```php
echo $myModel->deleteSignature();
```

--------------------------------

### Handle InvalidConfiguration when invoking AppendSignatureDocumentAction

Source: https://github.com/creagia/laravel-sign-pad/blob/main/_autodocs/api-reference/actions.md

Wrap the AppendSignatureDocumentAction invocation in a try/catch block to handle InvalidConfiguration exceptions. The catch block reports the exception, with an example message about an invalid sign pad width.

```php
use Creagia\LaravelSignPad\Actions\AppendSignatureDocumentAction;
use Creagia\LaravelSignPad\Exceptions\InvalidConfiguration;

try {
    app(AppendSignatureDocumentAction::class)($pdf, $decodedImage, $template);
} catch (InvalidConfiguration $e) {
    // e.g. 'Invalid sign pad width. Check your config key sign-pad.width'
    report($e);
}
```

--------------------------------

### SignaturePad constructor with defaults

Source: https://github.com/creagia/laravel-sign-pad/blob/main/_autodocs/api-reference/signature-pad-component.md

Creates a new component instance. Width and height default to configuration values from `config('sign-pad.width')` and `config('sign-pad.height')` when not provided. The constructor is truncated in the source with `// ...` indicating omitted body.

```php
/**
 * Create a new component instance.
 *
 * @return void
 */
public function __construct(
    ?float $width = null,
    ?float $height = null,
    string $padClasses = '',
    string $buttonClasses = '',
    string $borderColor = '#777777',
    string $submitName = 'Submit',
    string $clearName = 'Clear',
    bool $disabledWithoutSignature = false
) {
    $this->width = $width ?? config('sign-pad.width');
    $this->height = $height ?? config('sign-pad.height');
    // ...
}
```

--------------------------------

### __invoke(Request $request, GenerateSignatureDocumentAction $generateSignatureDocumentAction): RedirectResponse

Source: https://github.com/creagia/laravel-sign-pad/blob/main/_autodocs/api-reference/laravel-sign-pad-controller.md

Handles the POST request to sign a model instance. It validates the request, decodes the signature image, creates a signature record, stores the image, optionally generates a PDF, and redirects to the configured route.

```APIDOC
## [POST] /creagia/sign-pad

### Description
Handles the POST request to sign a model instance. It validates the request, decodes the signature image, creates a signature record, stores the image, optionally generates a PDF, and redirects to the configured route.

### Method
POST

### Endpoint
`/creagia/sign-pad` (as returned by `$model->getSignatureRoute()`)

### Parameters
#### Query Parameters
- **model** (string) - Required - FQCN of the model class to sign, e.g. `App\Models\MyModel`
- **id** (integer) - Required - Primary key of the model instance
- **token** (string) - Required - `md5(config('app.key').$modelClass)` generated by `RequiresSignature::getSignatureRoute()`

#### Request Body
- **sign** (string) - Required - Base64 PNG data URL, e.g. `data:image/png;base64,...` produced by `SignaturePad.toDataURL()`

### Request Example
```http
POST /creagia/sign-pad?model=App%5CModels%5CMyModel&id=1&token=... HTTP/1.1
Content-Type: application/x-www-form-urlencoded

sign=data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJ...
```

### Response
#### Success Response (302)
Redirects to the configured route with `['uuid' => $uuid]`.

#### Response Example
```http
HTTP/1.1 302 Found
Location: /redirect-route?uuid=...
```

### Error Responses
- **422** - Validation failure (missing required fields)
- **404** - Model not found (`findOrFail`)
- **403** - Invalid token
- **500** - Invalid signature or model already signed (exception thrown)
```

--------------------------------

### Direct Instantiation: SignaturePad

Source: https://github.com/creagia/laravel-sign-pad/blob/main/_autodocs/api-reference/signature-pad-component.md

Direct instantiation of the SignaturePad component class, useful for server-side composition.

```APIDOC
## Direct Instantiation: SignaturePad

### Description
Direct instantiation of the SignaturePad component class, useful for server-side composition.

### Constructor Parameters
- `width` (int) - Optional - Width of the canvas.
- `height` (int) - Optional - Height of the canvas.
- `padClasses` (string) - Optional - CSS classes for the canvas.
- `buttonClasses` (string) - Optional - CSS classes for the buttons.
- `borderColor` (string) - Optional - Border color of the canvas.
- `submitName` (string) - Optional - Text for the submit button.
- `clearName` (string) - Optional - Text for the clear button.
- `disabledWithoutSignature` (boolean) - Optional - Whether the submit button is disabled until a signature is drawn.

### Example
```php
$component = new SignaturePad(
    width: 500,
    height: 250,
    padClasses: 'rounded-xl',
    buttonClasses: 'btn',
    borderColor: '#eaeaea',
    submitName: 'Envia',
    clearName: 'Borra',
    disabledWithoutSignature: true,
);
```
```

--------------------------------

### Direct instantiation of SignaturePad component

Source: https://github.com/creagia/laravel-sign-pad/blob/main/_autodocs/api-reference/signature-pad-component.md

Direct instantiation as used in component tests, useful when composing server-side. Passes width, height, padClasses, buttonClasses, borderColor, submitName, clearName, and disabledWithoutSignature.

```php
$component = new SignaturePad(
    width: 500,
    height: 250,
    padClasses: 'rounded-xl',
    buttonClasses: 'btn',
    borderColor: '#eaeaea',
    submitName: 'Envia',
    clearName: 'Borra',
    disabledWithoutSignature: true,
);
```

--------------------------------

### Initialize SignaturePad for .e-signpad elements

Source: https://github.com/creagia/laravel-sign-pad/blob/main/_autodocs/api-reference/javascript-asset.md

Wires up every element matching .e-signpad. Uses a module-level submitted flag to prevent double submission across all pads. Reads data-disabled-without-signature to control submit-button gating.

```javascript
const eSignpads = document.querySelectorAll('.e-signpad');

let submitted = false;

eSignpads.forEach(function(eSignpad) {
    let signaturePad = new SignaturePad(eSignpad.querySelector('canvas')),
        submit = eSignpad.querySelector('.sign-pad-button-submit'),
        clear = eSignpad.querySelector('.sign-pad-button-clear'),
        disabledWithoutSignature = parseInt(eSignpad.getAttribute('data-disabled-without-signature'));
    ...
});
```

--------------------------------

### SignaturePad Component Constructor

Source: https://github.com/creagia/laravel-sign-pad/blob/main/_autodocs/api-reference/signature-pad-component.md

Creates a new SignaturePad component instance. Accepts optional parameters to customize the canvas dimensions, styling, button labels, and behavior.

```APIDOC
## SignaturePad Component Constructor

### Description
Creates a new SignaturePad component instance. Accepts optional parameters to customize the canvas dimensions, styling, button labels, and behavior.

### Method
Constructor

### Signature
```php
public function __construct(
    ?float $width = null,
    ?float $height = null,
    string $padClasses = '',
    string $buttonClasses = '',
    string $borderColor = '#777777',
    string $submitName = 'Submit',
    string $clearName = 'Clear',
    bool $disabledWithoutSignature = false
)
```

### Parameters
- **width** (?float) - Optional - Canvas width in pixels. Defaults to `config('sign-pad.width')` (600).
- **height** (?float) - Optional - Canvas height in pixels. Defaults to `config('sign-pad.height')` (200).
- **padClasses** (string) - Optional - CSS classes for the canvas element. Defaults to `''`.
- **buttonClasses** (string) - Optional - CSS classes for both buttons. Defaults to `''`.
- **borderColor** (string) - Optional - CSS border color of the canvas, rendered as `border: 1px solid {color}`. Defaults to `'#777777'`.
- **submitName** (string) - Optional - Label of the submit button (output raw via `{!! !!}`). Defaults to `'Submit'`.
- **clearName** (string) - Optional - Label of the clear button (output raw via `{!! !!}`). Defaults to `'Clear'`.
- **disabledWithoutSignature** (bool) - Optional - When `true`, the submit button starts disabled and is only enabled once a stroke is drawn; the JS resets it on clear. Defaults to `false`.

### Usage Example
```blade
<x-creagia-signature-pad
    width="500"
    height="200"
    padClasses="border rounded"
    buttonClasses="btn btn-primary"
    borderColor="#000000"
    submitName="Save"
    clearName="Reset"
    :disabledWithoutSignature="true"
/>
```

### Notes
- The nullable float parameters are PHP-typed `?float`, so passing integer literals such as `width="500"` from Blade works because Blade attribute values arrive as strings and integer literals coerce to float.
- The component renders a `<canvas>` plus Submit/Clear buttons and a hidden `sign` input whose value is filled by the bundled JS asset (`resources/assets/sign-pad.js`).
```

--------------------------------

### render()

Source: https://github.com/creagia/laravel-sign-pad/blob/main/_autodocs/api-reference/signature-pad-component.md

Renders the signature pad component view. This method is called by the Livewire component lifecycle to output the Blade template.

```APIDOC
## render()

### Description
Renders the signature pad component view. This method is called by the Livewire component lifecycle to output the Blade template.

### Method
render

### Endpoint
N/A (PHP method)

### Parameters
None

### Return Type
`Illuminate\Contracts\View\View|\Closure|string` - the view `laravel-sign-pad::components.signature-pad`.

### Example
```php
public function render()
{
    return view('laravel-sign-pad::components.signature-pad');
}
```
```

--------------------------------

### Direct integration test request

Source: https://github.com/creagia/laravel-sign-pad/blob/main/_autodocs/api-reference/laravel-sign-pad-controller.md

Shows the wire format for posting a signature to the route. The sign field is a base64 PNG data URL, and the route includes model, id, and token parameters.

```php
use Illuminate\Support\Facades\Storage;

$route = $myModel->getSignatureRoute(); // /creagia/sign-pad?model=App\Models\MyModel&id=1&token=...

$response = $this->post($route, [
    'sign' => 'data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJ...',
]);
```

--------------------------------

### SignaturePad render() method

Source: https://github.com/creagia/laravel-sign-pad/blob/main/_autodocs/api-reference/signature-pad-component.md

Returns the view 'laravel-sign-pad::components.signature-pad' (resources/views/components/signature-pad.blade.php). No parameters; return type per docblock is Illuminate\Contracts\View\View|\Closure|string.

```php
public function render()
{
    return view('laravel-sign-pad::components.signature-pad');
}
```

--------------------------------

### Demo form view rendering signature-pad component

Source: https://github.com/creagia/laravel-sign-pad/blob/main/_autodocs/api-reference/service-provider.md

Blade template that posts to the 'sign-pad::signature' route with CSRF protection and renders the signature-pad component with explicit attributes. Uses the fully-qualified component reference 'x-laravel-sign-pad::signature-pad'.

```blade
<form action="{{ route('sign-pad::signature')}}" method="POST">
    @csrf
    <div style="text-align: center">
        <x-laravel-sign-pad::signature-pad
            width="500"
            height="250"
            border-color="#eaeaea"
            pad-classes=""
            button-classes=""
        />
    </div>
</form>
```

--------------------------------

### DocumentTemplate::__construct

Source: https://github.com/creagia/laravel-sign-pad/blob/main/_autodocs/types.md

Constructor for the abstract DocumentTemplate class. Initializes the template with a Blade view name or source PDF path.

```APIDOC
## DocumentTemplate::__construct

### Description
Constructor for the abstract DocumentTemplate class. Initializes the template with a Blade view name or source PDF path.

### Method
Constructor

### Signature
```php
public function __construct(
    public string $path
) {}
```

### Parameters
- **path** (string) - Required - Blade view name (`BladeDocumentTemplate`) or source PDF path (`PdfDocumentTemplate`).
```

--------------------------------

### Basic usage with form and script

Source: https://github.com/creagia/laravel-sign-pad/blob/main/_autodocs/api-reference/signature-pad-component.md

Basic usage: a form posting to the model's signature route with CSRF, the component, and the JavaScript asset. The script tag loads vendor/sign-pad/sign-pad.min.js.

```blade
<form action="{{ $myModel->getSignatureRoute() }}" method="POST">
    @csrf
    <x-creagia-signature-pad />
</form>
<script src="{{ asset('vendor/sign-pad/sign-pad.min.js') }}"></script>
```

--------------------------------

### resizeCanvas() for high-DPI canvas resizing

Source: https://github.com/creagia/laravel-sign-pad/blob/main/_autodocs/api-reference/javascript-asset.md

Re-creates the canvas at device-pixel-ratio resolution when the intrinsic width exceeds the viewport. Re-attaches beginStroke gating for the new SignaturePad instance in that branch.

```javascript
let resizeCanvas = () => {
    document.querySelectorAll('.e-signpad').forEach(function(eSignpad) {
        let canvas = eSignpad.querySelector('canvas'),
            submit = eSignpad.querySelector('.sign-pad-button-submit'),
            disabledWithoutSignature = parseInt(eSignpad.getAttribute('data-disabled-without-signature'));

        if (canvas.width > window.innerWidth) {
            let signaturePad = new SignaturePad(eSignpad.querySelector('canvas'));
            const ratio = Math.max(window.devicePixelRatio || 1, 1);

            if(disabledWithoutSignature) {
                submit.setAttribute('disabled', 'disabled');
            }

            signaturePad.addEventListener("beginStroke", () => {
                if(disabledWithoutSignature) {
                    submit.removeAttribute('disabled');
                }
            });

            canvas.width = canvas.offsetWidth * ratio;
            canvas.height = canvas.offsetHeight * ratio;
            canvas.getContext("2d").scale(ratio, ratio);
            signaturePad.clear();
        }
    });
}
```

--------------------------------

### Using PdfDocumentTemplate with a PDF path

Source: https://github.com/creagia/laravel-sign-pad/blob/main/_autodocs/api-reference/document-templates.md

Shows how to instantiate PdfDocumentTemplate with an absolute path to an existing PDF file.

```php
use Creagia\LaravelSignPad\Templates\PdfDocumentTemplate;

new PdfDocumentTemplate(storage_path('pdf/template.pdf'));
```

--------------------------------

### Controller __invoke method signature

Source: https://github.com/creagia/laravel-sign-pad/blob/main/_autodocs/api-reference/laravel-sign-pad-controller.md

The main entry point of the sign pad controller, invoked by the router with an injected request and action. Returns a redirect response after processing the signature.

```php
public function __invoke(Request $request, GenerateSignatureDocumentAction $generateSignatureDocumentAction): RedirectResponse
```

--------------------------------

### Create signature record

Source: https://github.com/creagia/laravel-sign-pad/blob/main/_autodocs/api-reference/laravel-sign-pad-controller.md

Creates a new signature record for the model with a UUID, filename, IPs, and certification flag from config. The UUID is used for the filename and later redirect.

```php
$uuid = Str::uuid()->toString();
$filename = "{$uuid}.png";
$signature = $model->signature()->create([
    'uuid' => $uuid,
    'from_ips' => $request->ips(),
    'filename' => $filename,
    'certified' => config('sign-pad.certify_documents'),
]);
```

--------------------------------

### Include sign-pad.min.js in Blade template

Source: https://github.com/creagia/laravel-sign-pad/blob/main/_autodocs/api-reference/javascript-asset.md

Required on any page rendering the <x-creagia-signature-pad> component. Served from public/vendor/sign-pad/sign-pad.min.js after publishing with php artisan vendor:publish --tag=sign-pad-assets.

```blade
<script src="{{ asset('vendor/sign-pad/sign-pad.min.js') }}"></script>
```

--------------------------------

### Complete config file (config/sign-pad.php)

Source: https://github.com/creagia/laravel-sign-pad/blob/main/_autodocs/configuration.md

Full configuration file for the Laravel Sign Pad package. It defines the disk name via the SIGNATURES_DISK environment variable (default 'local'), paths for signatures and signed documents, canvas dimensions, certificate settings, and certification options. The certificate_file uses storage_path('app/certificate.crt') and cert_type defaults to 2.

```php
<?php

return [
    'disk_name' => env('SIGNATURES_DISK', 'local'),

    'signatures_path' => 'signatures',

    'documents_path' => 'signed_documents',

    'redirect_route_name' => null,

    'width' => 600,
    'height' => 200,

    'certify_documents' => false,

    'certificate_file' => storage_path('app/certificate.crt'),

    'certificate_info' => [
        'Name' => '',
        'Location' => '',
        'Reason' => '',
        'ContactInfo' => '',
    ],

    'cert_type' => 2,
];
```

--------------------------------

### Error handling for already-signed model

Source: https://github.com/creagia/laravel-sign-pad/blob/main/_autodocs/api-reference/laravel-sign-pad-controller.md

Catches the ModelHasAlreadyBeenSigned exception when a signature already exists for the model. The second submission is rejected.

```php
use Creagia\LaravelSignPad\Exceptions\ModelHasAlreadyBeenSigned;

try {
    $response = $this->post($myModel->getSignatureRoute(), ['sign' => $signDataUrl]);
} catch (ModelHasAlreadyBeenSigned $e) {
    // A signature already exists for this model; the second submission was rejected.
}
```

--------------------------------

### GenerateSignatureDocumentAction __invoke implementation steps

Source: https://github.com/creagia/laravel-sign-pad/blob/main/_autodocs/api-reference/actions.md

Core logic of the action: configures PDF, optionally certifies, appends pages and signature, stores the PDF, and persists the document filename. Requires sign-pad.certify_documents config and documents_path/disk_name settings.

```php
$this->pdf->SetPrintHeader(false);
$this->pdf->SetPrintFooter(false);
$this->pdf->SetMargins(PDF_MARGIN_LEFT - 5, PDF_MARGIN_TOP - 14, PDF_MARGIN_RIGHT - 5);
$this->pdf->SetAutoPageBreak(true, 0);

if (config('sign-pad.certify_documents')) {
    $this->pdf = $signatureDocumentTemplate->template->certify($this->pdf);
}

$this->pdf = $signatureDocumentTemplate->template->appendPages($this->pdf, $signature);

$this->pdf = $signatureDocumentTemplate->template->appendSignature($this->pdf, $decodedImage, $signatureDocumentTemplate);

$destinationFilename = "{$signatureDocumentTemplate->outputPdfPrefix}-{$signature->uuid}.pdf";
$filePath = config('sign-pad.documents_path').'/'.$destinationFilename;

Storage::disk(config('sign-pad.disk_name'))->put($filePath, $this->pdf->Output($filePath, 'S'));

$signature->document_filename = $destinationFilename;
$signature->save();
```

--------------------------------

### Using BladeDocumentTemplate with a model

Source: https://github.com/creagia/laravel-sign-pad/blob/main/_autodocs/api-reference/document-templates.md

Shows how to instantiate BladeDocumentTemplate with a Blade view name. The $model variable is available inside the template.

```php
// In a model implementing ShouldGenerateSignatureDocument:
use Creagia\LaravelSignPad\Templates\BladeDocumentTemplate;

new BladeDocumentTemplate('pdf/my-pdf-blade-template');
```

--------------------------------

### getSignatureRoute() method - route with query parameters

Source: https://github.com/creagia/laravel-sign-pad/blob/main/_autodocs/api-reference/requires-signature.md

Returns the absolute URL to POST /creagia/sign-pad with query parameters model, id, and token. The token is md5(app_key + model_class), class-scoped not per-model. Used as the action of the signing form.

```php
public function getSignatureRoute(): string
{
    return route('sign-pad::signature', [
        'model' => get_class($this),
        'id' => $this->id,
        'token' => md5(config('app.key').get_class($this)),
    ]);
}
```

--------------------------------

### Add new config values and rename store_path to signatures_path

Source: https://github.com/creagia/laravel-sign-pad/blob/main/UPGRADING.md

Add the new config values disk_name, signatures_path, and documents_path. The disk_name uses the SIGNATURES_DISK environment variable with a default of 'local'.

```php
/**
 * The disk on which to store signature images. Choose one or more of
 * the disks you've configured in config/filesystems.php.
 */
'disk_name' => env('SIGNATURES_DISK', 'local'),

/**
 * Path where the signature images will be stored.
 */
 'signatures_path' => 'signatures',
 
/**
 * Path where the documents will be stored.
 */
'documents_path' => 'signed_documents',
```

--------------------------------

### Abstract DocumentTemplate class

Source: https://github.com/creagia/laravel-sign-pad/blob/main/_autodocs/api-reference/document-templates.md

Base class for building PDF pages. Constructor takes a path (Blade view name or PDF file path). Subclasses must implement appendPages(). certify() and appendSignature() delegate to container-resolved actions.

```php
abstract class DocumentTemplate
{
    /**
     * @phpstan-param view-string $path
     */
    public function __construct(
        public string $path
    ) {}

    abstract public function appendPages(Fpdi $pdf, Signature $signature): Fpdi;

    public function certify(Fpdi $pdf): Fpdi
    {
        return app(CertifyDocumentAction::class)($pdf);
    }

    public function appendSignature(Fpdi $pdf, string $decodedImage, SignatureDocumentTemplate $signatureDocumentTemplate): Fpdi
    {
        return app(AppendSignatureDocumentAction::class)($pdf, $decodedImage, $signatureDocumentTemplate);
    }
}
```

--------------------------------

### PdfDocumentTemplate class implementation

Source: https://github.com/creagia/laravel-sign-pad/blob/main/_autodocs/api-reference/document-templates.md

Defines a document template that imports pages from an existing PDF file. The constructor takes an absolute path to a PDF, and each page is added to the FPDI document.

```php
class PdfDocumentTemplate extends DocumentTemplate
{
    public function appendPages(Fpdi $pdf, Signature $signature): Fpdi
    {
        $totalPdfPages = $pdf->setSourceFile($this->path);

        foreach (range(1, $totalPdfPages) as $pageNumber) {
            $pdf->AddPage();
            $tplIdx = $pdf->importPage($pageNumber);
            $pdf->useTemplate($tplIdx, ['adjustPageSize' => true]);
        }

        return $pdf;
    }
}
```

--------------------------------

### DocumentTemplate::appendPages

Source: https://github.com/creagia/laravel-sign-pad/blob/main/_autodocs/types.md

Abstract method that appends pages to the PDF document. Must be implemented by concrete template classes.

```APIDOC
## DocumentTemplate::appendPages

### Description
Abstract method that appends pages to the PDF document. Must be implemented by concrete template classes.

### Method
Abstract Method

### Signature
```php
abstract public function appendPages(Fpdi $pdf, Signature $signature): Fpdi;
```

### Parameters
- **pdf** (Fpdi) - Required - The FPDI PDF instance.
- **signature** (Signature) - Required - The Signature model instance.

### Return Value
- **Fpdi** - The modified FPDI PDF instance.
```

--------------------------------

### Using SignaturePosition in SignatureDocumentTemplate

Source: https://github.com/creagia/laravel-sign-pad/blob/main/_autodocs/api-reference/signature-position.md

Shows how to instantiate SignaturePosition objects inside the signaturePositions array of a SignatureDocumentTemplate. Each position specifies the page and millimeter coordinates for stamping the signature image.

```php
use Creagia\LaravelSignPad\SignaturePosition;
use Creagia\LaravelSignPad\SignatureDocumentTemplate;
use Creagia\LaravelSignPad\Templates\PdfDocumentTemplate;

new SignatureDocumentTemplate(
    outputPdfPrefix: 'document',
    template: new PdfDocumentTemplate(storage_path('pdf/template.pdf')),
    signaturePositions: [
        new SignaturePosition(
            signaturePage: 1,
            signatureX: 20,
            signatureY: 25,
        ),
        new SignaturePosition(
            signaturePage: 2,
            signatureX: 25,
            signatureY: 50,
        ),
    ],
);
```

--------------------------------

### SignatureDocumentTemplate::__construct

Source: https://github.com/creagia/laravel-sign-pad/blob/main/_autodocs/api-reference/signature-document-template.md

Creates a value object that tells the package how to generate the signed PDF document for a model. It specifies the output PDF file name prefix, the document template to render pages, and the positions where signature images are stamped.

```APIDOC
## SignatureDocumentTemplate::__construct

### Description
Creates a value object that tells the package how to generate the signed PDF document for a model. It specifies the output PDF file name prefix, the document template to render pages, and the positions where signature images are stamped.

### Method
Constructor

### Signature
```php
public function __construct(
    public string $outputPdfPrefix,
    public DocumentTemplate $template,
    public array $signaturePositions = [],
)
```

### Parameters
- **outputPdfPrefix** (string) - Required - Prefix of the generated PDF file name. Final name is `{outputPdfPrefix}-{signature.uuid}.pdf`
- **template** (DocumentTemplate) - Required - Page-builder template. Must be a `BladeDocumentTemplate` or `PdfDocumentTemplate` instance (both extend the abstract `DocumentTemplate`)
- **signaturePositions** (array<SignaturePosition>) - Optional - Default: `[]` - List of `SignaturePosition` value objects; one stamp is drawn per entry. If empty, the image is never stamped

### Return Value
Returns a `SignatureDocumentTemplate` instance.

### Usage Example
```php
use App\Models\MyModel;
use Creagia\LaravelSignPad\Contracts\CanBeSigned;
use Creagia\LaravelSignPad\Contracts\ShouldGenerateSignatureDocument;
use Creagia\LaravelSignPad\Concerns\RequiresSignature;
use Creagia\LaravelSignPad\SignatureDocumentTemplate;
use Creagia\LaravelSignPad\SignaturePosition;
use Creagia\LaravelSignPad\Templates\BladeDocumentTemplate;
use Illuminate\Database\Eloquent\Model;

class MyModel extends Model implements CanBeSigned, ShouldGenerateSignatureDocument
{
    use RequiresSignature;

    public function getSignatureDocumentTemplate(): SignatureDocumentTemplate
    {
        return new SignatureDocumentTemplate(
            outputPdfPrefix: 'document',
            template: new BladeDocumentTemplate('pdf/my-pdf-blade-template'),
            signaturePositions: [
                new SignaturePosition(signaturePage: 1, signatureX: 20, signatureY: 25),
            ],
        );
    }
}
```

### Error Handling
Constructor arguments are validated later at document-generation time. A non-numeric `sign-pad.width`/`sign-pad.height` config value or a non-boolean `sign-pad.certify_documents` will surface as `Creagia\LaravelSignPad\Exceptions\InvalidConfiguration` from `AppendSignatureDocumentAction::validateConfig()`.
```

--------------------------------

### BladeDocumentTemplate class implementation

Source: https://github.com/creagia/laravel-sign-pad/blob/main/_autodocs/api-reference/document-templates.md

Defines a document template that renders a Blade view into a PDF page. The constructor takes a Blade view name, and the view receives a $model variable set to the signed model.

```php
class BladeDocumentTemplate extends DocumentTemplate
{
    public function appendPages(Fpdi $pdf, Signature $signature): Fpdi
    {
        $pdf->AddPage();
        $html = view($this->path, ['model' => $signature->model]);
        $pdf->writeHTML($html, true, false, true, false);

        return $pdf;
    }
}
```

--------------------------------

### DocumentTemplate::certify

Source: https://github.com/creagia/laravel-sign-pad/blob/main/_autodocs/types.md

Certifies the PDF document by delegating to the CertifyDocumentAction.

```APIDOC
## DocumentTemplate::certify

### Description
Certifies the PDF document by delegating to the CertifyDocumentAction.

### Method
Method

### Signature
```php
public function certify(Fpdi $pdf): Fpdi;
```

### Parameters
- **pdf** (Fpdi) - Required - The FPDI PDF instance.

### Return Value
- **Fpdi** - The certified FPDI PDF instance.
```

--------------------------------

### Catching InvalidConfiguration exception

Source: https://github.com/creagia/laravel-sign-pad/blob/main/_autodocs/errors.md

Shows how to catch the InvalidConfiguration exception when generating a signature document. The exception message contains the config key to fix. If uncaught during an HTTP request, Laravel renders it as a 500 error.

```php
use Creagia\LaravelSignPad\Exceptions\InvalidConfiguration;

try {
    $signature = $model->signature()->create([...]);
    app(GenerateSignatureDocumentAction::class)($signature, $template, $decodedImage);
} catch (InvalidConfiguration $e) {
    report($e); // or handle: $e->getMessage() contains the config key to fix
}
```

--------------------------------

### POST /creagia/sign-pad

Source: https://github.com/creagia/laravel-sign-pad/blob/main/_autodocs/endpoints.md

Creates a Signatures row for the specified model, stores the drawn PNG, optionally generates a signed PDF, and redirects to the configured redirect route. The endpoint is invoked via a standard HTML form POST with CSRF protection.

```APIDOC
## [POST] /creagia/sign-pad

### Description
Creates a Signatures row for the model identified by `model` and `id`, stores the drawn PNG, optionally generates the signed PDF, and redirects to the configured `redirect_route_name`.

### Method
POST

### Endpoint
/creagia/sign-pad

### Parameters
#### Query Parameters
- **model** (string) - Required - FQCN of the signable model class, e.g. `App\Models\MyModel`
- **id** (string) - Required - Primary key of the model instance
- **token** (string) - Required - `md5(config('app.key').$modelClass)`

#### Request Body
- **sign** (string) - Required - Base64 PNG data URL, e.g. `data:image/png;base64,<base64>`; produced by `signaturePad.toDataURL()` in the JS asset
- **_token** (string) - Required (due to web middleware) - Laravel CSRF token (`@csrf`)

### Request Example
```http
POST /creagia/sign-pad?model=App%5CModels%5CMyModel&id=1&token=1a2b3c4d... HTTP/1.1
Host: example.com
Content-Type: application/x-www-form-urlencoded

_token=abc123...&sign=data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8z8BQDwAEhQGAhKmMIQAAAABJRU5ErkJggg==
```

### Response
#### Success Response (302 Found)
- Redirect to `route(config('sign-pad.redirect_route_name'), ['uuid' => $uuid])` - Location header carrying the `uuid` of the created signature; `redirect_route_name` must be configured (default `null`)

#### Response Example
```http
HTTP/1.1 302 Found
Location: http://example.com/signature/thanks?uuid=04d28fe4-3f4f-48f1-a8ce-7d6c3a26be4e
```

#### Error Responses
- **422 Unprocessable Entity** - Any of `model`, `sign`, `id`, `token` missing - Standard Laravel validation redirect back with `$errors` in session
- **403 Forbidden** - Token mismatch - Abort response `403` with message `Invalid token`
- **404 Not Found** - `findOrFail` on the model id - Standard 404
- **500 Internal Server Error** - `ModelHasAlreadyBeenSigned` thrown uncaught; `Exception('Invalid signature')`; or document-generation failures (`InvalidConfiguration`, FPDI errors) - Standard exception page unless handled
```

--------------------------------

### getSignatureImageAbsolutePath() method

Source: https://github.com/creagia/laravel-sign-pad/blob/main/_autodocs/api-reference/signature.md

Returns the absolute filesystem path of the signature image.

```php
public function getSignatureImageAbsolutePath(): string
```

--------------------------------

### BladeDocumentTemplate::appendPages(Fpdi $pdf, Signature $signature): Fpdi

Source: https://github.com/creagia/laravel-sign-pad/blob/main/_autodocs/api-reference/document-templates.md

Adds a single page to the PDF, renders the Blade view specified by the path constructor argument with the signed model available as $model, and writes the HTML into the PDF. This method is called by the library when generating the signature document.

```APIDOC
## BladeDocumentTemplate::appendPages(Fpdi $pdf, Signature $signature): Fpdi

### Description
Adds a single page to the PDF, renders the Blade view specified by the `path` constructor argument with the signed model available as `$model`, and writes the HTML into the PDF.

### Method
appendPages

### Signature
`appendPages(Fpdi $pdf, Signature $signature): Fpdi`

### Parameters
- **$pdf** (Fpdi) - Required - The FPDI PDF document to append the page to.
- **$signature** (Signature) - Required - The signature object containing the model to pass to the view.

### Return Type
Fpdi

### Usage Example
```php
use Creagia\LaravelSignPad\Templates\BladeDocumentTemplate;

new BladeDocumentTemplate('pdf/my-pdf-blade-template');
```

### Blade Template Example
```blade
{{-- resources/views/pdf/my-pdf-blade-template.blade.php --}}
<h1>Contract for {{ $model->name }}</h1>
<p>Drawn up on {{ $model->created_at->format('d/m/Y') }}.</p>
```
```

--------------------------------

### SignaturePosition class constructor

Source: https://github.com/creagia/laravel-sign-pad/blob/main/_autodocs/types.md

Value object defining a signature stamp position on a document page. Constructor requires an integer page number (1-based) and X/Y coordinates in millimeters for the stamp's top-left corner. Accepted by SignatureDocumentTemplate and consumed by AppendSignatureDocumentAction.

```php
class SignaturePosition
{
    public function __construct(
        public int $signaturePage,
        public int $signatureX,
        public int $signatureY,
    ) {}
}
```

--------------------------------

### getSignedDocumentAbsolutePath() method

Source: https://github.com/creagia/laravel-sign-pad/blob/main/_autodocs/api-reference/signature.md

Returns the absolute filesystem path of the signed PDF document, or null when document_filename is empty.

```php
public function getSignedDocumentAbsolutePath(): ?string
```

--------------------------------

### Register sign-pad route in routes/web.php

Source: https://github.com/creagia/laravel-sign-pad/blob/main/_autodocs/endpoints.md

Defines the POST route for the sign-pad endpoint, mapping to LaravelSignPadController and named 'sign-pad::signature'.

```php
<?php

use Creagia\LaravelSignPad\Controllers\LaravelSignPadController;

Route::post('creagia/sign-pad', LaravelSignPadController::class)->name('sign-pad::signature');
```

--------------------------------

### Usage - model implementing CanBeSigned with RequiresSignature

Source: https://github.com/creagia/laravel-sign-pad/blob/main/_autodocs/api-reference/requires-signature.md

Shows how to apply the trait to an Eloquent model. The model must implement CanBeSigned and use RequiresSignature as instructed in the README.

```php
use App\Models\MyModel;
use Creagia\LaravelSignPad\Concerns\RequiresSignature;
use Creagia\LaravelSignPad\Contracts\CanBeSigned;
use Illuminate\Database\Eloquent\Model;

class MyModel extends Model implements CanBeSigned
{
    use RequiresSignature;
}
```
Tokens:
Raw