tc-lib-pdf-graph

Overview

tc-lib-pdf-graph implements low-level drawing operations used to build PDF graphic content streams.

The API stays close to the PDF graphics operators themselves: paths, paint, clipping, shadings, and transforms, with the operator tokens visible in the method names and enum values.

Repository and API Docs

• GitHub: https://github.com/tecnickcom/tc-lib-pdf-graph
• API docs: https://tcpdf.org/docs/srcdoc/tc-lib-pdf-graph
• Packagist: https://packagist.org/packages/tecnickcom/tc-lib-pdf-graph

Project Metadata

Installation

composer require tecnickcom/tc-lib-pdf-graph

Where It Fits

Diagrams, overlays, crop and registration marks, and any vector component you want to draw once and place many times.

Features

Drawing Primitives

• Points, lines, rectangles and Bezier curves
• Ellipses, circles, elliptical arcs and pie sectors
• Polygons, regular polygons, star polygons and rounded rectangles
• Arrows, crop marks and registration marks
• Path-painting and clipping operators

Styles and Painting

• Style stack with line width, cap, join, miter limit, dash pattern and colors
• Transparency, blend modes and overprint through ExtGState objects
• A notransparency constructor flag for the conformance modes that forbid transparency (PDF/A-1, PDF/X-1a, PDF/X-3), which suppresses alpha, blend modes and soft masks
• Spot colors are resolved to their alternate device color for the drawing commands

Gradients

• Axial and radial shadings with multiple color stops and per-stop opacity
• Coons patch meshes and color registration bars
• Stop and background colors are converted to the shading color space (DeviceGray, DeviceRGB or DeviceCMYK) instead of being emitted as raw model components
• Under notransparency the shading itself survives: it is emitted fully opaque, and only the soft mask carrying the stop opacities is dropped

Transformations

• Scaling, rotation, mirroring, reflection, translation and skewing
• Transformation matrix product and transformation stack
• Coordinate conversion helpers, with the unit conversion ratio validated by setKUnit()

Transparency State

• Extended graphic states (ExtGState) are tracked, and the library reports which of them actually carry transparency. tc-lib-pdf uses that signal to omit the page transparency /Group on fully opaque pages.
• The transparency ExtGState carries /AIS false, and the DeviceGray override applies only to luminosity soft-mask shadings, which are emitted without a background.
• Gradient soft-mask state is isolated per gradient, so a soft mask set for one shading no longer leaks into the next.
• Borders are not emitted in fill-only paint modes, and uniform polygon border segments are joined instead of being stroked segment by segment.

Typed Enums

The backing value of each case is the exact token written to the content stream, so enum cases and raw strings are interchangeable.

Integration Notes

Transforms compose, and a helper that leaves one on the stack corrupts everything drawn after it. Push and pop around anything reusable, and keep the coordinate system a helper expects in its signature rather than in its caller’s head.

Snapshot the content stream of a complex drawing in a test. Graphics regressions are silent: the PDF still opens, the shape is just wrong.

Repeated artwork belongs in an XObject template rather than in the page content, both for size and to keep the two copies identical.

Requirements

• PHP 8.2 or later
• Extension: zlib
• Package dependencies: tecnickcom/tc-lib-color, tecnickcom/tc-lib-pdf-encrypt
• Composer

Example

<?php

require_once __DIR__ . '/vendor/autoload.php';

$draw = new \Com\Tecnick\Pdf\Graph\Draw(
	1.0,
	210,
	297,
	new \Com\Tecnick\Color\Pdf(),
	new \Com\Tecnick\Pdf\Encrypt\Encrypt(),
	notransparency: false,
);

echo $draw->getClippingRect(10, 10, 50, 20);

Development and Packaging

• QA and local checks: make deps, make help, make qa
• Coverage report: make qa-coverage
• Packaging: make rpm, make deb

Support and Contribution

• Sponsor: https://github.com/sponsors/tecnickcom
• Contribution guide: https://github.com/tecnickcom/tc-lib-pdf-graph/blob/main/CONTRIBUTING.md
• Security policy: https://github.com/tecnickcom/tc-lib-pdf-graph/blob/main/SECURITY.md