phpdftk API Documentation

PdfFileWriter
in package

Byte-level PDF file emitter — ISO 32000-2 §7.5.

Given a Catalog root, an Info (optional), a working ObjectRegistry, and optionally a signer, generate() produces the exact bytes of a spec-compliant PDF file: header, binary comment, indirect-object body, cross-reference table, trailer, startxref, %%EOF. With a signer configured, the output is post-processed to compute /ByteRange and patch /Contents in place.

This class deliberately knows nothing about pages, fonts, resources, or any other high-level document assembly concern. Those live in Phpdftk\Pdf\Writer\PdfWriter, which composes an instance of this class.

Table of Contents

Constants

DEFAULT_PDF_VERSION  = \Phpdftk\Pdf\Core\PdfVersion::V1_7
DEFAULT_VERSION  = '1.7'

Methods

__construct()  : mixed
generate()  : string
Generate the complete PDF as a binary string.
generateLinearized()  : string
Generate a linearized (web-optimized) PDF per ISO 32000-2 Annex F.
getInfo()  : Info|null
Return the Info dict, if set.
getPdfVersion()  : PdfVersion
getRegistry()  : ObjectRegistry
The underlying object registry. Exposed so callers that want fine-grained control over registration order can drive it directly. Most callers should use {@see register()}.
getVersion()  : string
getVersionWarnings()  : array<int, string>
register()  : PdfReference
Register any PdfObject and return a reference to it.
save()  : void
Write the generated PDF to a file, creating parent directories as needed.
setCatalog()  : PdfReference
Register the document catalog and return its reference. The catalog becomes the `/Root` of the emitted file.
setCeilingVersion()  : void
Set a ceiling version — properties requiring a higher version are silently stripped (set to null) during registration. Objects whose class-level requirement exceeds the ceiling throw CeilingVersionException.
setCompressStreams()  : void
Enable or disable automatic FlateDecode compression of streams that have no filter already set.
setDeprecationHandler()  : void
setEncryption()  : void
Configure encryption for the generated PDF.
setInfo()  : void
Set the document info dict. Pass null to clear. Registers the object if non-null.
setSigner()  : void
Configure a signer. After calling this, {@see generate()} will:
setStrictDeprecation()  : void
setStrictVersionMode()  : void
setTimestamper()  : void
Configure a document-level timestamp using a TSA client.
setTsaClient()  : void
Configure a TSA client for RFC 3161 timestamping.
setVersion()  : void
toBytes()  : string
Alias for {@see generate()} — returns the raw PDF bytes as a string.
writeTo()  : int
Write the generated PDF to an open stream resource (anything `fwrite()` accepts: a file handle, `php://memory`, `php://output`, a socket, …). Returns the number of bytes written.

Constants

DEFAULT_PDF_VERSION

public mixed DEFAULT_PDF_VERSION = \Phpdftk\Pdf\Core\PdfVersion::V1_7

Methods

__construct()

public __construct([bool $compressStreams = true ][, bool $useXRefStream = false ][, bool $useObjectStreams = false ][, PdfVersion|string $version = self::DEFAULT_PDF_VERSION ]) : mixed
Parameters
$compressStreams : bool = true
$useXRefStream : bool = false
$useObjectStreams : bool = false
$version : PdfVersion|string = self::DEFAULT_PDF_VERSION

generate()

Generate the complete PDF as a binary string.

public generate() : string

Assembles the file as an array of string chunks and implodes once at the end -- this is O(N) in total output size, whereas repeated string concatenation would be O(N^2) because PHP copies the growing string on every .=.

The chunk order follows ISO 32000-2 section 7.5:

  1. %PDF-X.Y header
  2. Binary comment (%\xE2\xE3\xCF\xD3) so transfer tools treat the file as binary rather than ASCII
  3. Indirect-object body (one chunk per registered object)
  4. Cross-reference table (or xref stream for PDF >= 1.5)
  5. Trailer dictionary
  6. startxref pointer
  7. %%EOF marker

When a signer is configured, the serialized bytes are post-processed by applySignature() to fill /ByteRange and /Contents.

Return values
string

generateLinearized()

Generate a linearized (web-optimized) PDF per ISO 32000-2 Annex F.

public generateLinearized([array<int, int> $firstPageObjectNumbers = [] ]) : string

Linearized PDFs place the first page's objects at the front of the file so a viewer can display it before downloading the rest. The structure is:

  1. Header + linearization parameters dict (object 1)
  2. First-page cross-reference section
  3. Catalog, page tree, first page, and its resources
  4. Hint stream
  5. Remaining pages and objects
  6. Main cross-reference section + trailer
Parameters
$firstPageObjectNumbers : array<int, int> = []

Object numbers belonging to the first page (page, content streams, fonts, images). If empty, auto-detected from object order.

Return values
string

getRegistry()

The underlying object registry. Exposed so callers that want fine-grained control over registration order can drive it directly. Most callers should use {@see register()}.

public getRegistry() : ObjectRegistry
Return values
ObjectRegistry

getVersion()

public getVersion() : string
Return values
string

getVersionWarnings()

public getVersionWarnings() : array<int, string>
Return values
array<int, string>

save()

Write the generated PDF to a file, creating parent directories as needed.

public save(string $path) : void
Parameters
$path : string

setCeilingVersion()

Set a ceiling version — properties requiring a higher version are silently stripped (set to null) during registration. Objects whose class-level requirement exceeds the ceiling throw CeilingVersionException.

public setCeilingVersion(PdfVersion|null $ceiling) : void

Mutually exclusive with strict mode — setting a ceiling disables strict.

Parameters
$ceiling : PdfVersion|null

setCompressStreams()

Enable or disable automatic FlateDecode compression of streams that have no filter already set.

public setCompressStreams(bool $compress) : void
Parameters
$compress : bool

setDeprecationHandler()

public setDeprecationHandler(Closure $handler) : void
Parameters
$handler : Closure

setEncryption()

Configure encryption for the generated PDF.

public setEncryption(PdfEncryptor $encryptor) : void

The encrypt dictionary is registered as an indirect object and referenced from the trailer. All string values and stream data are encrypted per-object during generation.

Parameters
$encryptor : PdfEncryptor

A configured encryptor (use PdfEncryptor::rc4128() or ::aes128())

setInfo()

Set the document info dict. Pass null to clear. Registers the object if non-null.

public setInfo(Info|null $info) : void
Parameters
$info : Info|null

setSigner()

Configure a signer. After calling this, {@see generate()} will:

public setSigner(SignatureValue $signatureValue, Pkcs7Signer $signer[, int $placeholderBytes = 8192 ]) : void
  1. Serialize the document with a fixed-size /Contents hex placeholder and a 4-element /ByteRange of zero-padded 10-digit slots inside $signatureValue.
  2. Locate the placeholders in the serialized bytes.
  3. Patch /ByteRange with the real offsets (same byte length).
  4. Feed the two byte ranges to $signer to produce a PKCS#7 SignedData blob.
  5. Patch /Contents with the DER bytes (hex-encoded, zero-padded to the placeholder length).

$signatureValue must already be registered as an indirect object and referenced by a SignatureField::$v (directly or via reference). $placeholderBytes bounds the maximum signature size — 8 KiB is more than enough for typical RSA/ECDSA PKCS#7 blobs.

Parameters
$signatureValue : SignatureValue
$signer : Pkcs7Signer
$placeholderBytes : int = 8192

setStrictDeprecation()

public setStrictDeprecation([bool $strict = true ]) : void
Parameters
$strict : bool = true

setStrictVersionMode()

public setStrictVersionMode([bool $strict = true ]) : void
Parameters
$strict : bool = true

setTimestamper()

Configure a document-level timestamp using a TSA client.

public setTimestamper(SignatureValue $docTimeStamp, TsaClient $tsaClient[, int $placeholderBytes = 16384 ]) : void

This is the timestamp equivalent of setSigner(): it installs a DocTimeStamp signature value and TSA client, then patches /ByteRange and /Contents at generation time with the RFC 3161 timestamp token from the TSA.

Parameters
$docTimeStamp : SignatureValue

A DocTimeStamp instance to hold the token

$tsaClient : TsaClient

The TSA client to request the token from

$placeholderBytes : int = 16384

Size of the /Contents placeholder

setTsaClient()

Configure a TSA client for RFC 3161 timestamping.

public setTsaClient(TsaClient $tsaClient) : void

When set alongside a signer, the timestamp token will be embedded in the PKCS#7 signature. When set without a signer (with a DocTimeStamp signature value), produces a document-level timestamp.

Parameters
$tsaClient : TsaClient

toBytes()

Alias for {@see generate()} — returns the raw PDF bytes as a string.

public toBytes() : string
Return values
string

writeTo()

Write the generated PDF to an open stream resource (anything `fwrite()` accepts: a file handle, `php://memory`, `php://output`, a socket, …). Returns the number of bytes written.

public writeTo(resource $stream) : int
Parameters
$stream : resource
Return values
int 

        

        
    




    

    

                                

                

                                
    

        On this page

        
    


                

                            

            

    

        

            
Search results