Documentation

Document
in package

Pdf extract document class

Tags
category

Pop

author

Nick Sagona, III nick@popphp.org

copyright

Copyright (c) 2009-2026 Nick Sagona, III

license

https://www.popphp.org/license New BSD License

version
6.0.0

Table of Contents

Constants

MAX_FONT_INFO_CACHE_BYTES  = 67108864
Maximum bytes retained by the font info cache
MAX_TOTAL_DECODED_BYTES  = 67108864
Maximum total bytes this document may decode across every stream over its lifetime.

Properties

$cache  : array<string|int, mixed>
Resolved object cache
$data  : string
Raw PDF data
$decodeBudget  : Budget
Total decoded-byte budget shared by every stream this document decodes
$expandingStreams  : array<string|int, mixed>
Object stream numbers currently being expanded, used to detect circular references
$fontInfoCache  : array<string|int, mixed>
Resolved FontInfo cache, keyed by a caller-supplied cache key
$fontInfoCacheBytes  : int
Running total of bytes retained in the font info cache
$fontInfoMruKey  : string|null
Most-recently-used font info cache key, used once the byte budget is exhausted
$fontInfoMruValue  : mixed
Most-recently-used font info cache value, used once the byte budget is exhausted
$objectStreamCache  : array<string|int, mixed>
Expanded object stream cache, keyed by stream object number
$objectStreamIndexCache  : array<string|int, mixed>
Positional view of each expanded object stream (index within the stream to object value), keyed by stream object number. Built once alongside objectStreamCache so index lookups don't re-run array_values() on every call.
$offsets  : array<string|int, mixed>
Object number to xref location map
$resolving  : array<string|int, mixed>
Object numbers currently being resolved, used to detect circular references
$trailer  : array<string|int, mixed>
Trailer dictionary

Methods

__construct()  : mixed
Constructor
fromFile()  : Document
Create a document from a PDF file
getDecodeBudget()  : Budget
Get this document's shared decode budget
getObject()  : mixed
Get an object by object number, from the cache or by parsing/expanding it
getObjectNumbers()  : array<string|int, mixed>
Get every object number this document's xref exposes
getOrResolveFontInfo()  : mixed
Get a cached FontInfo result for a key, or compute and (budget permitting) cache it
getRoot()  : array<string|int, mixed>
Get the resolved document catalog (Root)
getTrailer()  : array<string|int, mixed>
Get the trailer dictionary
resolve()  : mixed
Resolve a value, following indirect references until a direct value is reached
expandObjectStreamsFromRepair()  : array<string|int, mixed>
A brute-force repair scan only finds objects that appear as literal "N G obj ... endobj" text - objects packed inside a /Type /ObjStm container's stream body don't match that pattern at all, since they're serialized inline within the ObjStm's own stream data rather than as their own "obj" markers. Without this second pass, any object that only exists inside an object stream would be silently unrecoverable after repair fires.
findCatalogReference()  : Reference|null
Scan repair-recovered offsets for an object that looks like the document catalog
getFromObjectStream()  : mixed
Get an object at an index within an object stream, expanding and caching the stream if needed
isClassicXref()  : bool
Determine if the xref section at a position is a classic table (vs. an xref stream)
isUsable()  : bool
Determine if xref-derived offsets/trailer look usable (vs. needing repair)
load()  : void
Load offsets/trailer via xref, falling back to brute-force repair if unusable
loadViaRepair()  : array<string|int, mixed>
Load offsets/trailer via brute-force repair scan
loadViaXref()  : array<string|int, mixed>
Load offsets/trailer by following the startxref chain (classic tables and/or xref streams)
looksLikeObjectAt()  : bool
Determine if a byte offset looks like the start of an "N G obj" object
mergeXrefSection()  : void
Merge one xref section's offsets/trailer into the accumulated result
parseAt()  : mixed
Parse an object directly at a byte offset

Constants

MAX_FONT_INFO_CACHE_BYTES

Maximum bytes retained by the font info cache

protected mixed MAX_FONT_INFO_CACHE_BYTES = 67108864

MAX_TOTAL_DECODED_BYTES

Maximum total bytes this document may decode across every stream over its lifetime.

protected mixed MAX_TOTAL_DECODED_BYTES = 67108864

The Budget only throws once a charge pushes the running total past this ceiling - by then, the decode that tipped it over (up to Flate's own 64MB per-call cap) has already completed and its output is retained in memory alongside every prior charged chunk, so real peak usage runs measurably higher than this number, on top of the PHP process's own baseline footprint. This must stay comfortably below common PHP memory_limit floors (128M on conservative/shared hosting) or the process hits a hard, uncatchable OOM fatal before the Budget ever gets to throw its catchable Exception - which is exactly what this constant exists to prevent.

Properties

$cache

Resolved object cache

protected array<string|int, mixed> $cache = []

$data

Raw PDF data

protected string $data

$decodeBudget

Total decoded-byte budget shared by every stream this document decodes

protected Budget $decodeBudget

$expandingStreams

Object stream numbers currently being expanded, used to detect circular references

protected array<string|int, mixed> $expandingStreams = []

$fontInfoCache

Resolved FontInfo cache, keyed by a caller-supplied cache key

protected array<string|int, mixed> $fontInfoCache = []

$fontInfoCacheBytes

Running total of bytes retained in the font info cache

protected int $fontInfoCacheBytes = 0

$fontInfoMruKey

Most-recently-used font info cache key, used once the byte budget is exhausted

protected string|null $fontInfoMruKey = null

$fontInfoMruValue

Most-recently-used font info cache value, used once the byte budget is exhausted

protected mixed $fontInfoMruValue = null

$objectStreamCache

Expanded object stream cache, keyed by stream object number

protected array<string|int, mixed> $objectStreamCache = []

$objectStreamIndexCache

Positional view of each expanded object stream (index within the stream to object value), keyed by stream object number. Built once alongside objectStreamCache so index lookups don't re-run array_values() on every call.

protected array<string|int, mixed> $objectStreamIndexCache = []

$offsets

Object number to xref location map

protected array<string|int, mixed> $offsets = []

$resolving

Object numbers currently being resolved, used to detect circular references

protected array<string|int, mixed> $resolving = []

$trailer

Trailer dictionary

protected array<string|int, mixed> $trailer = []

Methods

__construct()

Constructor

public __construct(string $data) : mixed

Instantiate a document from raw PDF data.

Parameters
$data : string

fromFile()

Create a document from a PDF file

public static fromFile(string $file) : Document
Parameters
$file : string
Tags
throws
Exception
Return values
Document

getDecodeBudget()

Get this document's shared decode budget

public getDecodeBudget() : Budget
Return values
Budget

getObject()

Get an object by object number, from the cache or by parsing/expanding it

public getObject(int $objNum) : mixed
Parameters
$objNum : int

getObjectNumbers()

Get every object number this document's xref exposes

public getObjectNumbers() : array<string|int, mixed>
Return values
array<string|int, mixed>

getOrResolveFontInfo()

Get a cached FontInfo result for a key, or compute and (budget permitting) cache it

public getOrResolveFontInfo(string $key, callable $factory) : mixed
Parameters
$key : string
$factory : callable

getRoot()

Get the resolved document catalog (Root)

public getRoot() : array<string|int, mixed>
Tags
throws
Exception
Return values
array<string|int, mixed>

getTrailer()

Get the trailer dictionary

public getTrailer() : array<string|int, mixed>
Return values
array<string|int, mixed>

resolve()

Resolve a value, following indirect references until a direct value is reached

public resolve(mixed $value) : mixed
Parameters
$value : mixed
Tags
throws
Exception

expandObjectStreamsFromRepair()

A brute-force repair scan only finds objects that appear as literal "N G obj ... endobj" text - objects packed inside a /Type /ObjStm container's stream body don't match that pattern at all, since they're serialized inline within the ObjStm's own stream data rather than as their own "obj" markers. Without this second pass, any object that only exists inside an object stream would be silently unrecoverable after repair fires.

protected expandObjectStreamsFromRepair(array<string|int, mixed> $offsets) : array<string|int, mixed>

These recovered objects don't have a byte offset the way normal repair-scanned objects do - they're already fully parsed values, not "here's where to find it" locations - so instead of trying to fit them into the offsets/inStream shape, this returns a ready-to-use [objNum => value] map that the caller seeds directly into the object cache (getObject() already checks the cache before consulting offsets).

Parameters
$offsets : array<string|int, mixed>
Return values
array<string|int, mixed>

findCatalogReference()

Scan repair-recovered offsets for an object that looks like the document catalog

protected findCatalogReference(array<string|int, mixed> $offsets) : Reference|null
Parameters
$offsets : array<string|int, mixed>
Return values
Reference|null

getFromObjectStream()

Get an object at an index within an object stream, expanding and caching the stream if needed

protected getFromObjectStream(int $streamObjNum, int $index) : mixed
Parameters
$streamObjNum : int
$index : int
Tags
throws
Exception

isClassicXref()

Determine if the xref section at a position is a classic table (vs. an xref stream)

protected isClassicXref(int $pos) : bool
Parameters
$pos : int
Return values
bool

isUsable()

Determine if xref-derived offsets/trailer look usable (vs. needing repair)

protected isUsable(array<string|int, mixed> $offsets, array<string|int, mixed> $trailer) : bool
Parameters
$offsets : array<string|int, mixed>
$trailer : array<string|int, mixed>
Return values
bool

load()

Load offsets/trailer via xref, falling back to brute-force repair if unusable

protected load() : void
Tags
throws
Exception

loadViaRepair()

Load offsets/trailer via brute-force repair scan

protected loadViaRepair() : array<string|int, mixed>
Return values
array<string|int, mixed>

loadViaXref()

Load offsets/trailer by following the startxref chain (classic tables and/or xref streams)

protected loadViaXref() : array<string|int, mixed>
Tags
throws
Exception
Return values
array<string|int, mixed>

looksLikeObjectAt()

Determine if a byte offset looks like the start of an "N G obj" object

protected looksLikeObjectAt(int $offset) : bool
Parameters
$offset : int
Return values
bool

mergeXrefSection()

Merge one xref section's offsets/trailer into the accumulated result

protected mergeXrefSection(array<string|int, mixed> $section, array<string|int, mixed> &$offsets, array<string|int, mixed> &$trailer) : void
Parameters
$section : array<string|int, mixed>
$offsets : array<string|int, mixed>
$trailer : array<string|int, mixed>

parseAt()

Parse an object directly at a byte offset

protected parseAt(int $offset) : mixed
Parameters
$offset : int
Tags
throws
Exception 

        

        
    




    

    

                                

                

                                
    

        On this page

        
    


                

                            

            

    

        

            
Search results