Download the PHP package tomedio/pdf-watermark without Composer

PDF Watermark

A PHP library for adding text and image watermarks to PDF files using FPDI.

Features

• Add text watermarks with customizable:

  • Font size, color, and opacity
  • Font style (bold, italic, etc.)
  • Background color and opacity
  • Rotation angle (only available with center position)
  • Position (top-left, center, bottom-right, etc.)
  • Pages to apply the watermark to (specific pages, ranges, last page, all pages)
  • Page number placeholder support (%d)

• Add image watermarks with customizable:

  • Opacity
  • Rotation angle (only available with center position)
  • Scaling or explicit dimensions
  • Position
  • Pages to apply the watermark to
  • Automatic scaling to fit page boundaries
• Works with compressed PDF files and PDFs with versions higher than 1.4
• Recognizes page sizes and orientations
• Modifies existing pages without adding new ones
• Configuration-based approach
• Configurable temporary directory for processing files

Requirements

• PHP 8.1 or higher
• pdftk (recommended for handling compressed PDFs with versions higher than 1.4)

Installation

1. Install pdftk (optional but recommended)

pdftk is used as a workaround for handling compressed PDFs with versions higher than 1.4.

On Ubuntu/Debian:

On macOS (using Homebrew):

On Windows:

Download and install pdftk from the official website.

2. Install the library via Composer

Basic Usage

Adding a Text Watermark

Adding an Image Watermark

Note: If the image watermark exceeds the page size, it will be automatically scaled down proportionally to fit within the page boundaries while maintaining its aspect ratio.

Adding Multiple Watermarks

Page Selection

You can specify which pages to apply the watermark to:

Custom Temporary Directory

You can specify a custom temporary directory for processing files:

If no temporary directory is specified, the system's default temporary directory (sys_get_temp_dir()) will be used.

API Documentation

PdfWatermarkerFactory

The factory class provides methods to create watermarkers, watermark configurations, and watermarks.

Methods

• __construct(?string $pdftk = null, ?string $tempDir = null): Constructor
• create(): PdfWatermarker: Create a new PdfWatermarker instance
• createTextWatermarkConfig(string $text): TextWatermarkConfig: Create a new text watermark configuration
• createImageWatermarkConfig(string $imagePath): ImageWatermarkConfig: Create a new image watermark configuration
• createTextWatermark(TextWatermarkConfig $config): TextWatermark: Create a new text watermark
• createImageWatermark(ImageWatermarkConfig $config): ImageWatermark: Create a new image watermark
• createWithTextWatermark(TextWatermarkConfig $config): PdfWatermarker: Create a PdfWatermarker with a text watermark
• createWithImageWatermark(ImageWatermarkConfig $config): PdfWatermarker: Create a PdfWatermarker with an image watermark

PdfWatermarker

The main class for applying watermarks to PDF files.

Methods

• __construct(?string $pdftk = null, ?string $tempDir = null): Constructor
• addWatermark(AbstractWatermark $watermark): self: Add a watermark to be applied
• apply(string $inputFile, string $outputFile): void: Apply watermarks to a PDF file

AbstractWatermark

The base class for all watermarks.

Constants

• POSITION_TOP_LEFT: Position at the top-left corner
• POSITION_TOP_CENTER: Position at the top-center
• POSITION_TOP_RIGHT: Position at the top-right corner
• POSITION_MIDDLE_LEFT: Position at the middle-left
• POSITION_CENTER: Position at the center
• POSITION_MIDDLE_RIGHT: Position at the middle-right
• POSITION_BOTTOM_LEFT: Position at the bottom-left corner
• POSITION_BOTTOM_CENTER: Position at the bottom-center
• POSITION_BOTTOM_RIGHT: Position at the bottom-right corner

TextWatermarkConfig

Configuration class for text watermarks.

Constants

• FONT_STYLE_REGULAR: Regular font style (no formatting)
• FONT_STYLE_BOLD: Bold font style
• FONT_STYLE_ITALIC: Italic font style
• FONT_STYLE_UNDERLINE: Underlined font style
• FONT_STYLE_STRIKETHROUGH: Strikethrough font style

Methods

• __construct(string $text): Constructor
• setPosition(string $position): self: Set the position of the watermark
• setOpacity(float $opacity): self: Set the opacity of the watermark (0.0 to 1.0)
• setAngle(float $angle): self: Set the rotation angle of the watermark in degrees (only works with center position)
• setPages(array|string $pages): self: Set pages to apply the watermark to
• setFontSize(int $fontSize): self: Set the font size in points
• setTextColor(int $r, int $g, int $b): self: Set the text color in RGB format (0-255)
• setTextOpacity(float $opacity): self: Set the text opacity (0.0 to 1.0)
• setBackgroundColor(int $r, int $g, int $b): self: Set the background color in RGB format (0-255)
• setBackgroundOpacity(float $opacity): self: Set the background opacity (0.0 to 1.0)
• setFontName(string $fontName): self: Set the font name
• setFontStyle(int $fontStyle): self: Set the font style using constants (e.g., TextWatermarkConfig::FONT_STYLE_BOLD, TextWatermarkConfig::FONT_STYLE_ITALIC)

ImageWatermarkConfig

Configuration class for image watermarks.

Methods

• __construct(string $imagePath): Constructor
• setPosition(string $position): self: Set the position of the watermark
• setOpacity(float $opacity): self: Set the opacity of the watermark (0.0 to 1.0)
• setAngle(float $angle): self: Set the rotation angle of the watermark in degrees (only works with center position)
• setPages(array|string $pages): self: Set pages to apply the watermark to
• setScale(float $scale): self: Set the scale of the image (1.0 = original size). If the scaled image exceeds the page size, it will be automatically scaled down proportionally to fit within the page boundaries.
• setWidth(int $width): self: Set the width of the image (height will be calculated to maintain aspect ratio). If the resulting image exceeds the page size, it will be automatically scaled down proportionally to fit within the page boundaries.
• setHeight(int $height): self: Set the height of the image (width will be calculated to maintain aspect ratio). If the resulting image exceeds the page size, it will be automatically scaled down proportionally to fit within the page boundaries.

PDF Version Compatibility

This library uses FPDI to process PDF files, which has a limitation with compressed PDFs that have versions higher than 1.4. To overcome this limitation, the library implements a workaround using pdftk:

1. When a PDF cannot be processed directly with FPDI (typically due to being a compressed PDF with version > 1.4), the library automatically falls back to using pdftk.
2. pdftk is used to uncompress the PDF, making it compatible with FPDI.
3. The watermarks are applied to the uncompressed PDF using FPDI.
4. The resulting PDF is recompressed using pdftk.

This approach allows the library to work with a wide range of PDF files, including those with higher versions, without requiring the paid version of FPDI.

Advanced Usage

Using Page Number Placeholder

You can include the page number in your text watermark using the %d placeholder:

Setting Font Name and Style

Font Name

You can set the font name for text watermarks using predefined constants or custom font names:

Font Style

You can set the font style for text watermarks using constants:

You can also combine multiple font styles using the bitwise OR operator:

Setting Explicit Dimensions for Image Watermarks

Instead of scaling, you can set explicit dimensions for image watermarks:

Note: If the resulting image dimensions exceed the page size, the image will be automatically scaled down proportionally to fit within the page boundaries while maintaining its aspect ratio.

Development

Available Makefile Commands

The library includes a Makefile with several useful commands:

License

This library is licensed under the MIT License.