SetaPDF_Core_Document A class representing a PDF document
File: /SetaPDF v2/Core/Document.php
This class represents a PDF document in all SetaPDF components. It offers the main functionalities for managing objects, cross reference tables and writers of the document instance.
It also tracks changes of objects and security handlers.
Class hierarchy
Implements
Summary
Methods
- __construct()
- __call()
- _cleanUpTrailer()
- _releaseObjects()
- _updateFileIdentifier()
- _writeCrossReferenceTable()
- _writeFileBody()
- _writeFileHeader()
- _writeObject()
- _writeTrailer()
- addBeforeSaveCallback()
- addCache()
- addIndirectObjectReferenceWritten()
- blockReferencedObject()
- cleanUp()
- clearCache()
- cloneIndirectObject()
- createNewObject()
- deleteObject()
- deleteObjectById()
- ensureObject()
- finish()
- getCache()
- getCacheReferencedObjects()
- getCatalog()
- getCompressXref()
- getCurrentObject()
- getCurrentObjectData()
- getCurrentObjectDocument()
- getDirectWrite()
- getFileIdentifier()
- getIdForObject()
- getInfo()
- getInstanceIdent()
- getOwnerPdfDocument()
- getParser()
- getPdfVersion()
- getSaveMethod()
- getSecHandler()
- getSecHandlerIn()
- getState()
- getTrailer()
- getWriter()
- getXref()
- handleWriteCallback()
- hasCache()
- hasSecHandler()
- hasSecurityHandler()
- objectRegistered()
- registerWriteCallback()
- releaseObject()
- removeBeforeSaveCallback()
- removeReferencedObject()
- resolveIndirectObject()
- save()
- setCacheReferencedObjects()
- setCleanUpObjects()
- setCompressXref()
- setDirectWrite()
- setFileBodyMethod()
- setMinPdfVersion()
- setNewFileIdentifier()
- setPdfVersion()
- setSecHandler()
- setWriter()
- unBlockReferencedObject()
- unRegisterWriteCallback()
- update()
- write()
- writeChangedObjects()
- writeObject()
- writeReferencedObjects()
Properties
- $_beforeSaveCallbacks
- $_blockedReferencedObjects
- $_cache
- $_cacheReferencedObjects
- $_catalog
- $_changedObjects
- $_cleanUpObjects
- $_compressXref
- $_currentObject
- $_currentObjectData
- $_deletedObjects
- $_directWrite
- $_fileBodyMethod
- $_info
- $_instanceIdent
- $_maxObjId
- $_newFileIdentifier
- $_objectStreams
- $_objectStreamsParser
- $_objects
- $_objectsToIds
- $_parser
- $_pdfVersion
- $_referencedObjects
- $_saveMethod
- $_secHandler
- $_secHandlerIn
- $_state
- $_trailer
- $_trailerChanged
- $_useWriteCallbacks
- $_writeCallbacks
- $_writer
- $_xref
Constants
CACHE_ENCAPSULATED_CONTENT_STREAMS
Cache constant
CACHE_FONT
Cache constant
CACHE_FONT_DESCRIPTOR
Cache constant
CACHE_ICC_PROFILE
Cache constant
CACHE_X_OBJECT
Cache constant
SAVE_METHOD_REWRITE
Save method constant defining a rewrite by resolving objects starting at the root object
SAVE_METHOD_REWRITE_ALL
Save method constant defining a rewrite by writing all available objects
SAVE_METHOD_UPDATE
Save method constant defining an incremental update
STATE_CLEANED_UP
State constant
STATE_FINISHED
State constant
STATE_NONE
State constant
STATE_SAVED
State constant
STATE_WRITING_BODY
State constant
STATE_WRITING_XREF
State constant
Static Properties
$_instanceIdentPrefix
A random prefix for generating unique instance identifications
Properties
$_beforeSaveCallbacks
An array of callbacks that should be called before the save method is executed.
$_blockedReferencedObjects
Blocked referenced objects
This array holds objects which should NOT be automatically resolved.
$_changedObjects
Changed objects
$_currentObjectData
The object id and generation number of the currently written object
$_deletedObjects
Deleted objects
$_fileBodyMethod
A method/function which should be called to fill the document body
$_instanceIdent
Identification of a document instance
$_newFileIdentifier
The none permanent file identifier
$_parser
The parser object of the existing document
$_referencedObjects
Referenced objects
This array holds information about objects to which references were written. Needed to create deep copies of an object from one to another document
$_xref
An instance of a cross-reference
If the document is created of an existing one
this will be an instance of SetaPDF_Core_Parser_CrossReferenceTable
Static Methods
load()
Creates an instance of a document based on an existing PDF.
Parameters
- $reader : SetaPDF_Core_Reader_ReaderInterface
A reader instance
- $writer : SetaPDF_Core_Writer_WriterInterface
A writer instance
- $className : string
The class name to initiate
Return Values
Returns a SetaPDF_Core_Document
instance
Exceptions
Throws SetaPDF_Core_Parser_CrossReferenceTable_Exception,Exception
loadByFilename()
Initiate an instance by a filename.
Parameters
- $filename : string
The path to the pdf file
- $writer : SetaPDF_Core_Writer_WriterInterface
A writer instance
- $className : string
The class name to initiate
Exceptions
loadByString()
Initiate an instance by a pdf string.
Parameters
- $string : string
Content of the pdf
- $writer : SetaPDF_Core_Writer_WriterInterface
A writer instance
- $className : string
The class name to initiate
Exceptions
Methods
__construct()
The constructor.
Parameters
- $writer : SetaPDF_Core_Writer_WriterInterface
The writer to which the document should be written
__call()
Implement magic methods for getting helper objects.
You can use the methods from SetaPDF_Core_Document_Catalog::getDocumentMagicMethods()
.
Additional you can use "getFormFiller", "getMerger", "getSigner" and "getStamper" if you want to receive instances of these components.
Parameters
- $method : string
The method name
- $arguments : array
The arguments
Exceptions
Throws BadMethodCallException
See
_cleanUpTrailer()
_writeCrossReferenceTable()
_writeFileBody()
Main method which writes the file body.
This method should extended/overwritten to implement individual logic if the document should be build at runtime.
Return Values
The objects metadata that written
_writeFileHeader()
_writeObject()
Writes an object to the resulting document but evaluates first if this is neccesarry.
Parameters
- $document : SetaPDF_Core_Document
- $objectId : integer
- $generation : integer|null
- $cache : boolean
Exceptions
Throws SetaPDF_Core_Document_ObjectNotDefinedException
Throws SetaPDF_Core_Document_ObjectNotFoundException
Throws SetaPDF_Core_Exception
Throws SetaPDF_Core_Parser_Exception
Throws SetaPDF_Core_Type_Exception
Throws SetaPDF_Exception
_writeTrailer()
Write the trailer dictionary and the pointer top the initial xref table.
Exceptions
Throws SetaPDF_Core_Exception
addBeforeSaveCallback()
Adds a callback that will get executed before the save method is processed.
Parameters
- $name : string
- $callback : callable
See
addCache()
Adds a cache item by its type and name.
Parameters
- $type : string
- $name : string
- $value : mixed
addIndirectObjectReferenceWritten()
Cache written object references.
This method is called if an indirect object reference is written. This makes sure that the class knows about maybe unwritten objects.
Parameters
- $indirectObject : SetaPDF_Core_Type_IndirectObjectInterface
The indirect object
Exceptions
blockReferencedObject()
This prohibits that a reference to this objects will be written.
Objects defined via this method will not automatically be resolved if a reference to them was written.
Parameters
- $indirectObject : SetaPDF_Core_Type_IndirectObjectInterface
The indirect object
See
cleanUp()
Release objects to free memory and cycled references.
After calling this method the instance of this object is unusable!
clearCache()
Clears the complete cache, an item by type or by type and name.
Parameters
- $type : string
- $name : null|string
cloneIndirectObject()
Clones an indirect object.
Parameters
- $indirectObject : SetaPDF_Core_Type_IndirectObject
The indirect object to clone
createNewObject()
Create a new indirect object.
Parameters
- $value : SetaPDF_Core_Type_AbstractType
The value of the new indirect object
deleteObject()
Delete an indirect object.
Parameters
- $object : SetaPDF_Core_Type_IndirectObjectInterface
The indirect object to delete
deleteObjectById()
Deletes an indirect object by its object id and generation number.
Parameters
- $objectId : integer
The object id of the object
- $generation : integer
The generation id of the object
Exceptions
Throws SetaPDF_Core_Document_ObjectNotDefinedException
Throws SetaPDF_Core_Document_ObjectNotFoundException
Throws SetaPDF_Core_Exception
Throws SetaPDF_Core_Parser_Pdf_InvalidTokenException
Throws SetaPDF_Core_Reader_Exception
Throws SetaPDF_Core_Type_Exception
Throws SetaPDF_Exception
ensureObject()
Makes sure that an object is ensured through this document (if possible).
Parameters
- $indirectObject : SetaPDF_Core_Type_IndirectObjectInterface
The indirect object to ensure
getDirectWrite()
Gets whether the PDF objects should be written individually (true) or after assembling a single string (false).
getFileIdentifier()
Get a file identifier.
Parameters
- $permanent : boolean
- $create : boolean
Exceptions
Throws SetaPDF_Core_Type_Exception
getIdForObject()
Return the object id and generation number for an indirect object or reference.
This method makes sure that objects are nearly independent of their original document and the matching between document, object and their ids is handled at one place: in this method.
Parameters
- $indirectObject : SetaPDF_Core_Type_IndirectObjectInterface
The indirect object
getOwnerPdfDocument()
Implementation of the SetaPDF_Core_Type_Owner
interface.
getSaveMethod()
Get the current used save method.
This method can be used by objects at writing time to evaluate if it is possible to edit referencing values or not.
getSecHandler()
Get the security handler for the output document.
getSecHandlerIn()
Returns the security handler of the original document.
handleWriteCallback()
Method called when a PDF type will be written.
This method could be used to manipulate a value just before it will get written to the writer object.
Parameters
- $value : SetaPDF_Core_Type_AbstractType
hasCache()
Checks if a cache item with a specific type and name exists.
Parameters
- $type : string
- $name : string
hasSecurityHandler()
WARNING: This method is marked as deprecated!
Use SetaPDF_Core_Document::hasSecHandler()
instead.
Alias for hasSecHandler().
objectRegistered()
Checks if an indirect object is already registered for/in this document instance.
Parameters
- $indirectObject : SetaPDF_Core_Type_IndirectObjectInterface
The indirect object to check
registerWriteCallback()
Register a write callback.
Parameters
- $callback : callback
- $type : string
- $name : string
releaseObject()
Releases an indirect object from the internal object cache.
Parameters
- $object : SetaPDF_Core_Type_IndirectObject
- $cleanUp : boolean
Whether to call cleanUp() on the object or not.
removeReferencedObject()
Remove referenced objects.
This method is needed if an object is e.g. moved to a compressed cross-reference stream and alredy written there. In that case it needs to be removed from this "list".
Parameters
- $indirectObject : SetaPDF_Core_Type_IndirectObjectInterface
resolveIndirectObject()
Resolves an indirect object.
Parameters
- $objectId : integer
The object id
- $generation : integer|null
The generation number. Could be also "null" to find an object with an unknown generation number with the xref parser
- $cache : boolean
Should the object be cached?
Exceptions
Throws SetaPDF_Core_Document_ObjectNotDefinedException
Throws SetaPDF_Core_Document_ObjectNotFoundException
Throws SetaPDF_Core_Exception
Throws SetaPDF_Core_Parser_Pdf_InvalidTokenException
Throws SetaPDF_Core_Reader_Exception
Throws SetaPDF_Core_Type_Exception
Throws SetaPDF_Exception
save()
Saves the document.
The PDF format offers a way to add changes to a document by simply appending the changes to the end of the file. This method is called incremental update and has the advantage that it is very fast, because only changed objects have to be written. This behavior is the default one, when calling the save()-method. Sadly it makes it easy to revert the document to the previous state by simply cutting the bytes of the last revision.
The parameter of the save()-method allows you to define that the document should be rebuild
from scratch by resolving the complete object structure. Just pass
SetaPDF_Core_Document::SAVE_METHOD_REWRITE
to it. This task is very performance intensive, because the
complete document have to be parsed, interpreted and rewritten.
Additionally, it is possible to rewrite the whole document with all available objects. The benefit of this
solution is that it will keep compressed object streams intact:
SetaPDF_Core_Document::SAVE_METHOD_REWRITE_ALL
. The disadvantage is, that unused objects may be
copied/written, too.
Parameters
- $method : boolean|integer
Update or rewrite the document
Exceptions
Throws SetaPDF_Core_Document_ObjectNotDefinedException
Throws SetaPDF_Core_Document_ObjectNotFoundException
Throws SetaPDF_Core_Exception
Throws SetaPDF_Core_Parser_CrossReferenceTable_Exception
Throws SetaPDF_Core_Parser_Exception
Throws SetaPDF_Core_SecHandler_Exception
Throws SetaPDF_Core_Type_Exception
Throws SetaPDF_Core_Type_IndirectReference_Exception
Throws SetaPDF_Exception
Throws SetaPDF_Exception_NotImplemented
Throws BadMethodCallException
setCacheReferencedObjects()
Define if referenced objects should be cached or not.
Parameters
- $cacheReferencedObjects : boolean
The flag status
setCleanUpObjects()
Set the behavior if the cleanUp()-methods of objects get called automatically.
Parameters
- $cleanUpObjects : boolean
The flag status
setCompressXref()
Define whether the cross-reference should be compressed or not.
By default, the SetaPDF-Core component writes the cross-reference in the standard format or in the format which is defined in the source document, if any available.
Parameters
- $compressXref : bool
Pass true to enforce that the cross-reference will be compressed. Pass false to enforce a standard uncompressed cross-reference table.
Exceptions
Throws SetaPDF_Core_SecHandler_Exception
Throws SetaPDF_Core_Type_Exception
Throws BadMethodCallException
setDirectWrite()
Defines whether the PDF objects should be written individually (true) or after assembling a single string (false).
Parameters
- $directWrite : bool
setFileBodyMethod()
Set the callback method/function which will write the file body.
Parameters
- $callback : callback
setMinPdfVersion()
Set the minimal PDF version.
Parameters
- $minPdfVersion : string
The minimal pdf version
Exceptions
Throws SetaPDF_Core_SecHandler_Exception
Throws SetaPDF_Core_Type_Exception
setNewFileIdentifier()
Set a custom non-permanent file identifier.
Parameters
- $newFileIdentifier : string
setPdfVersion()
Set the PDF version of the document.
Parameters
- $pdfVersion : string|float
The pdf version
Exceptions
Throws SetaPDF_Core_SecHandler_Exception
Throws SetaPDF_Core_Type_Exception
setSecHandler()
Set the security handler for this document.
Parameters
- $secHandler : SetaPDF_Core_SecHandler_SecHandlerInterface
The new secHandler
Exceptions
Throws SetaPDF_Core_SecHandler_Exception
Throws SetaPDF_Core_Type_Exception
setWriter()
Set the writer object.
A writer instance can only be set prior the first call to save()
or
after a finish()
call.
Parameters
- $writer : SetaPDF_Core_Writer_WriterInterface
The new writer object
Exceptions
Throws BadMethodCallException
unBlockReferencedObject()
Remove a blocked object.
Parameters
- $indirectObject : SetaPDF_Core_Type_IndirectObjectInterface
The indirect object
See
update()
Implementation of the observer pattern.
This method is automatically called if an observed object was changed.
Parameters
- $subject : SplSubject
The SplSubject notifying the observer of an update.
write()
Writes content to the attached writer.
Parameters
- $bytes : string
Exceptions
Throws SetaPDF_Core_Exception
writeObject()
Writes an object to the resulting document.
This method should only be called in the _writeFileBody()-method or in the callback method of it.
Parameters
- $object : SetaPDF_Core_Type_IndirectObject
writeReferencedObjects()
Write referenced objects.
Exceptions
Throws SetaPDF_Core_Document_ObjectNotDefinedException
Throws SetaPDF_Core_Document_ObjectNotFoundException
Throws SetaPDF_Core_Exception
Throws SetaPDF_Core_Parser_Exception
Throws SetaPDF_Core_Type_Exception
Throws SetaPDF_Exception