Download the PHP package tcc/laravel-emdha-esign without Composer

tcc/laravel-emdha-esign

Laravel package for EMDHA eSign digital signature integration — Saudi Arabia's government-grade digital signing platform.

Requirements

• PHP 8.1+
• Laravel 9.x / 10.x / 11.x / 12.x
• Java JRE 8+ installed and available in PATH
• EMDHA SDK JAR files (provided by EMDHA CA)

Installation

Publish the configuration file:

This creates config/emdha.php in your application.

SDK Setup

The EMDHA SDK consists of Java JAR files that must be available on your server. They are not included in this package.

1. Create a secure directory

Add to your .gitignore:

2. Copy SDK files

Place these files from your EMDHA SDK distribution into storage/app/emdha/sdk/:

3. Set directory permissions

Configuration

Add the following to your .env file:

Configuration Reference

Using Classpath (Multiple JARs)

When EMDHA_SDK_CLASSPATH is set, the package uses java -cp <classpath> com.emdha.cli.Main instead of java -jar. This is needed when eaCore.jar and gson-2.8.5.jar must be on the classpath alongside emdhaCLI.jar:

Quick Start

API Reference

Facade: Emdha

The Emdha facade provides the primary interface to the EMDHA signing service.

signDocument()

Signs a single PDF document.

signMultipleDocuments()

Signs multiple PDF documents in a single transaction (shared signer info).

generateTransactionId()

Generates a unique 26-character transaction ID.

DTO: SignerInfo

Create from array:

DTO: DocOptions

Positions: bottomRight, bottomLeft, bottomMiddle, topRight, topLeft, topMiddle

Pages: all, Last, First, or specific page coordinates like 1,50,50,170,110

DTO: EmdhaSigningResult

The result object returned from all signing operations.

Signature Appearance Types

No Image

Minimal text-only signature appearance.

EMDHA Logo (default)

Displays the EMDHA logo alongside signature text.

Custom Logo

Displays your custom image alongside the signature. Pass the image as a base64-encoded string in appearanceBackgroundImage.

Multi-Document Signing

Sign multiple PDFs in a single EMDHA transaction:

All documents share the same signer info and transaction ID.

Error Handling

Error Codes

Error Lookup

Handling Errors in Signing

Integration Guide

Example: Blade Application

Migration:

Controller:

Example: Inertia + React Application

The package works the same way — use the Emdha facade in your controllers and return Inertia responses:

Example: API-Only (Sanctum)

Artisan Commands

emdha:check

Verifies your EMDHA SDK setup:

Checks:

• Java runtime availability
• SDK JAR file existence
• Classpath validity (if configured)
• Required configuration values (SIP ID, license, PFX, password, alias)
• API base URL
• Temp directory writability

How It Works

The EMDHA signing flow consists of three steps:

1. Generate Request XML — The SDK JAR (GenerateSignDocRequestXML) creates a digitally-signed XML request containing the PDF hash, signer identity, and signing parameters.

2. Send to EMDHA API — The request XML is sent to the EMDHA gateway via HTTP POST (application/x-www-form-urlencoded). The API verifies the signer's identity against the Saudi KYC system and returns a signed response.

3. Append Response — The SDK JAR (AppendSignDocResponse) merges the API's digital signature back into the original PDF, producing a fully-signed document.

Important Technical Notes

• API Content-Type: Must be application/x-www-form-urlencoded with URL-encoded decoded XML. NOT application/xml and NOT raw XML.
• PFX Certificate: Uses RC2-40-CBC legacy encryption. PHP OpenSSL 3.x cannot read it — only the Java SDK can. Do not attempt to parse the PFX with PHP.
• KYC ID Provider: Use nid (lowercase), not SELF-NID.
• Base URL: The EMDHA_BASE_URL should include /SignDoc in the path. The package guards against double /SignDoc.

Troubleshooting

"SDK JAR file not found" (SDK-0001)

• Verify EMDHA_SDK_JAR_PATH in .env points to the absolute path of emdhaCLI.jar
• Ensure the file exists and is readable: ls -la /path/to/emdhaCLI.jar

"Invalid SIP Access Key Hash" (ESIGN-1004)

• Verify your PFX certificate, password, alias, and license file all match the SIP ID registered with EMDHA CA
• Check that EMDHA_PFX_PASSWORD and EMDHA_PFX_ALIAS are correct
• Ensure EMDHA_LICENSE_PATH points to the correct .lics file

"java: command not found"

• Install Java JRE 8+: sudo apt install default-jre (Ubuntu) or brew install openjdk (macOS)
• Verify: java -version

Classpath Issues

If you see class loading errors, set the classpath to include all JARs:

On Windows, use ; as the separator instead of :.

"Invalid KYC XML data" (ESIGN-1011)

• Ensure kycId is a valid Saudi National ID
• Ensure englishName does not contain special characters
• Check that all required signer fields are populated

Temp Directory Issues

If the SDK cannot write temp files:

Or set a custom path:

Security Considerations

• Never commit PFX certificates, license files, or passwords to version control
• Add storage/app/emdha/ to your .gitignore
• Store the SDK JARs outside the public web directory
• Use environment-specific .env files for sandbox vs. production credentials
• The PFX password is stored in .env — ensure proper file permissions (chmod 600 .env)

Changelog

v1.0.0

• Initial release
• Emdha facade with signDocument() and signMultipleDocuments()
• SignerInfo, DocOptions, EmdhaSigningResult DTOs
• EmdhaSdkService — Java CLI JAR bridge with classpath support
• EmdhaApiService — HTTP client with form-urlencoded + URL-encoded XML
• EmdhaXmlService — SDK input JSON builder for single and multi-doc signing
• EmdhaErrorCode — centralized error code map
• EmdhaServiceProvider — Laravel service provider with singleton bindings
• php artisan emdha:check — setup verification command

License

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