Paint gradients and use transparency and blend modes

At a glance

Fill an area with a two-stop axial (linear) or radial gradient. Then composite overlapping shapes with constant alpha and an optional blend mode. The code follows examples/25-gradients.php and examples/20-transparency.php.

A gradient is an ISO 32000-2 shading. linearGradient() emits a Type 2 (axial) shading, and radialGradient() emits a Type 3 (radial) shading. Transparency uses the graphics-state alpha constant. setAlpha() sets the non-stroking ca value and the stroking CA value.

Install

composer require nextpdf/core:^3

You do not need an optional extension. The gradient, alpha, and blend-mode API has been stable since 1.0.0, and it runs on the 8.1–8.4 backport matrix.

Conceptual overview

linearGradient(x, y, w, h, start, end) paints a color blend along the box’s axis between two Color stops. ISO 32000-2 defines an axial shading’s Coords as [x0 y0 x1 y1]. If the endpoints coincide, nothing is painted. radialGradient(...) blends between two circles. The radial Coords is [x0 y0 r0 x1 y1 r1], and both radii must be ≥ 0.

setAlpha($alpha, $mode) sets constant opacity for the painting that follows. The first argument is the alpha constant (ca/CA). The second argument selects the blend mode (BM in the transparent imaging model). Reset alpha to 1.0 and the blend mode to Normal before you draw unrelated content.

API surface

The API surface is generated from PHPDoc. This recipe uses these methods:

linearGradient(float $x, float $y, float $w, float $h, Color $start, Color $end): static
radialGradient(float $x, float $y, float $w, float $h, Color $start, Color $end): static
setAlpha(float $alpha, BlendMode $mode = BlendMode::Normal): static
Color::rgb(int $r, int $g, int $b), Color::white(), Color::black() provide gradient stops.
setFillColor(...) sets the color that alpha and the blend mode composite.

Code sample — Quick start

<?php

declare(strict_types=1);

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

use NextPDF\Core\Document;
use NextPDF\Graphics\BlendMode;
use NextPDF\Graphics\Color;

$doc = Document::createStandalone();
$doc->addPage();

// Axial gradient: blue -> white across a 190 x 40 box.
$doc->linearGradient(10, 30, 190, 40, Color::rgb(30, 58, 138), Color::white());

// Two overlapping rectangles at 70% opacity with Multiply blend.
$doc->setAlpha(0.7, BlendMode::Multiply);
$doc->setFillColor(220, 38, 38);
$doc->rect(20, 90, 60, 40, 'F');
$doc->setFillColor(37, 99, 235);
$doc->rect(50, 90, 60, 40, 'F');
$doc->setAlpha(1.0, BlendMode::Normal); // reset

$doc->save(getenv('NEXTPDF_COOKBOOK_OUTPUT') ?: __DIR__ . '/gradients.pdf');

Code sample — Production

This is the complete, harness-ready example. It honors NEXTPDF_COOKBOOK_OUTPUT and adds no entropy of its own.

<?php

declare(strict_types=1);

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

use NextPDF\Core\Document;
use NextPDF\Graphics\BlendMode;
use NextPDF\Graphics\Color;

$doc = Document::createStandalone();
$doc->setTitle('Gradients and Transparency');
$doc->addPage();

$doc->setFont('helvetica', 'B', 18);
$doc->cell(0, 12, 'Gradients and Transparency', newLine: true);
$doc->ln(4);

// 1. Axial gradient — blue to white.
$doc->setFont('helvetica', 'B', 12);
$doc->cell(0, 8, '1. Axial gradient', newLine: true);
$doc->ln(2);
$doc->linearGradient(
    x: 10, y: $doc->getY(), w: 190, h: 40,
    start: Color::rgb(30, 58, 138), end: Color::white(),
);
$doc->ln(44);

// 2. Radial gradient — red centre fading to white.
$doc->setFont('helvetica', 'B', 12);
$doc->cell(0, 8, '2. Radial gradient', newLine: true);
$doc->ln(2);
$doc->radialGradient(
    x: 50, y: $doc->getY(), w: 110, h: 55,
    start: Color::rgb(220, 38, 38), end: Color::white(),
);
$doc->ln(59);

// 3. Constant alpha + blend mode over a light backdrop.
$doc->setFont('helvetica', 'B', 12);
$doc->cell(0, 8, '3. Alpha 0.7 with Multiply blend', newLine: true);
$doc->ln(2);
$baseY = $doc->getY();
$doc->setAlpha(1.0, BlendMode::Normal);
$doc->setFillColor(245, 245, 245);
$doc->rect(15, $baseY, 90, 40, 'F');
$doc->setAlpha(0.7, BlendMode::Multiply);
$doc->setFillColor(220, 38, 38);
$doc->rect(20, $baseY + 5, 40, 30, 'F');
$doc->setFillColor(37, 99, 235);
$doc->rect(40, $baseY + 5, 40, 30, 'F');

// Always reset compositing state before continuing.
$doc->setAlpha(1.0, BlendMode::Normal);
$doc->setFillColor(255);

$out = getenv('NEXTPDF_COOKBOOK_OUTPUT') ?: __DIR__ . '/gradients.pdf';
$doc->save($out);

echo "Created gradients.pdf\n";

Edge cases & gotchas

Coincident gradient endpoints paint nothing. A zero-size box, where w or h collapses the axis, yields an empty axial shading per ISO 32000-2. Confirm that the box has extent.
Radii must be non-negative. A negative radius into radialGradient() is invalid. Two zero radii paint nothing.
Alpha persists across paints. setAlpha(0.7, …) stays in effect for every later paint until you reset it. Restore setAlpha(1.0, BlendMode::Normal) after a transparent block, or later content appears faded.
A blend mode needs a backdrop. A blend mode such as Multiply or Screen composites against what is already drawn. Over an empty page the effect is invisible, so draw a backdrop first.
The PDF 2.0 blend-mode array is deprecated. NextPDF emits a single blend-mode name, which is the PDF 2.0 form. The specification deprecates the legacy array form.

Performance

A gradient is one shading object plus a fill. Alpha and blend mode are graphics-state parameters. Each one has a constant cost per use, and both stay within the 2000 ms / 64 MB budget. No rasterization occurs, so gradients remain resolution-independent shadings.

Security notes

This recipe paints only the geometry and colors that your code supplies. It performs no input parsing or network access. Validate color and coordinate values from untrusted data before you use them.

Conformance

Statement	Spec	Clause
`ShadingType` 2 is axial, 3 is radial.	ISO 32000-2	§8.7.4.3
Axial `Coords` is `[x0 y0 x1 y1]`; coincident endpoints paint nothing.	ISO 32000-2	§8.7.4.5.3
Radial `Coords` is `[x0 y0 r0 x1 y1 r1]`; radii ≥ 0.	ISO 32000-2	§8.7.4.5.4
`CA`/`ca` are the stroking/non-stroking alpha constants.	ISO 32000-2	§8.4.5
`BM` is the current blend mode.	ISO 32000-2	§11.3.5

Reproducibility profile — structural. The trailer /ID and date atoms vary on each save. The harness strips those atoms, then compares the qpdf-normalized structure. This recipe describes how NextPDF produces the structure. It does not make a blanket claim of ISO 32000-2 conformance.

Commercial context

Not applicable. Gradients, alpha, and blend modes are Core capabilities. They have no Premium gate.