SetaPDF_FormFiller_Xfa_Bridge The helper class for processing XFA data and template data.

File: /SetaPDF v2/FormFiller/Xfa/Bridge.php

This class matches data nodes to template nodes and creates data nodes if they are not available.

The class actually only supports the default "mergeMode": "consumeData" mode.

So the logic for updating a field by its AcroForm name will be:

  • Check if a data node is already found for this specific field.
    • if not, start the data parsing process which mappes all find value nodes to specific fields if they don't have a bind-value.
    • direct matches have a higher priority than scope matches.
  • The process have to be done twice in case a direct match had overwritten a scope matched relation.
  • If the field still have no data node attached to it create a node (tree) for it and attach it. (only if the match attribute of the bind-value is not set to "none".)
  • Update the node if available.

Updating by changed XML data:

  • remove all bounded data nodes from all available fields
  • start the data parsing process and attach the nodes to the fields.
  • Iterate over all fields (XML) and set their values in their corresponding AcroForm fields. (omit recursivity)

TODO:

  • “Extended Mapping Rules” on page 508. (XFA Specification - 3.3)
  • XSLT Transformations (see page 545 - XFA Specification - 3.3)
  • Resolve mergeMode-attribute from root node (introduced in XFA 3.1, so maybee obsolete atm)
  • Handling of "picture" clauses (see page 156 / 1150 - XFA Specification - 3.3)

Class hierarchy

Summary

Properties

$_acroFormFieldNamesToTemplateNodes

A hash map for relation between a field node and its corresponding AcroForm representation.

The keys are the field names used in the AcroForm field. The value is the field node itself.

$_currentBinding

The current found binding from an accestor node.

$_currentRootIndex

The current index of the data nodes in the data root element.

$_data

The data node.

$_dataNodeByTemplateNode

The data node for a template node.

$_dataPathByField

The default data path by a field node.

$_dataProcessed

Flag indicating if the data were processed or not.

$_dataRefBinding

The dataRef bindings of field nodes.

$_fieldToFieldName

Fieldnames by field nodes.

$_form

The form node.

$_globalBinding

Global bindings by field nodes.

$_noneBinding

None bindings by field nodes.

$_template

The template node.

$_xpathsToFields

A simple and direct XPath expression to field in either the template or form package.


Methods

__construct()

The constructor

Parameters
$template : DOMElement
 
$data : DOMElement
 
$form : DOMElement
 
Exceptions

Throws SetaPDF_FormFiller_Exception

_bindDataNode()

protected SetaPDF_FormFiller_Xfa_Bridge::_bindDataNode (
array $path, DOMNode $dataNode, string $method [, boolean $allowOverwrite = true ]
): boolean

Tries to bind a data node to a field node.

Both "direct match" and "scope match" are evaluated.

Parameters
$path : array
 
$dataNode : DOMNode
 
$method : string
 
$allowOverwrite : boolean
 

_createDataNode()

Creates of gets a data node by a field node.

Parameters
$fieldNode : DOMElement
 

_doDirectMatch()

Tries to find a field node by a "direct match".

Parameters
$path : array
 

_doScopeMatch()

private SetaPDF_FormFiller_Xfa_Bridge::_doScopeMatch (
array $path
): boolean|DOMElement

Tries to find a field node by a "scope match".

Example from the XFA specification:

Template: <template …> <field name="first" …>… <field name="last" …> … <field name="apt" …> … <field name="street" …> … <field name="city"…> … <field name="country"…> … <field name="postalcode"…> …

Data:

Jack Spratt 99 Candlestick Lane London UK SW1
Parameters
$path : array
 

_ensureDataValue()

protected SetaPDF_FormFiller_Xfa_Bridge::_ensureDataValue (
array $fieldNodes, DOMNode $dataNode
): array

Ensure that the field node and data node match to each other.

This method filters the field nodes by the dataGroup attribute/property of the data node.

Parameters
$fieldNodes : array
 
$dataNode : DOMNode
 

_evaluateDataRefBindings()

This method evaluates a data ref binding of a field node.

Parameters
$fieldNode : DOMElement
 

_evaluateGlobalBindings()

This method evaluates a global binding, if exists, for a field node.

Parameters
$fieldNode : DOMElement
 
Exceptions

Throws Exception

_filtertBindings()

private SetaPDF_FormFiller_Xfa_Bridge::_filtertBindings (
DOMElement|DOMElement[] $fieldNodes [, bool $isDirect = false ]
): array

This method filters field nodes which are already bound.

Parameters
$fieldNodes : DOMElement|DOMElement[]
 
$isDirect : bool
 

_isBind()

protected SetaPDF_FormFiller_Xfa_Bridge::_isBind (
DOMNode $dataNode
): bool|DOMNode

Checks if a data node is already bound to a field node.

Parameters
$dataNode : DOMNode
 

_parseTemplate()

Parses the template and evaluates direct and global bindings.

Exceptions

Throws SetaPDF_FormFiller_Exception

_processData()

protected SetaPDF_FormFiller_Xfa_Bridge::_processData (
DOMNode $node [, array $path = array ( ) [, array &$pathes = array ( ) [, string $method = 'direct' ]]]
): void

Processes the data and bind the nodes to the template/field nodes.

Parameters
$node : DOMNode
 
$path : array
 
$pathes : array
 
$method : string
 

_processDataAttributes()

protected SetaPDF_FormFiller_Xfa_Bridge::_processDataAttributes (
DOMNode $node [, array $path = array ( ) [, array &$pathes = array ( ) [, string $method = 'direct' ]]]
): void

Process attributes to unbind tempalte/field nodes.

Parameters
$node : DOMNode
 
$path : array
 
$pathes : array
 
$method : string
 

_processTemplate()

private SetaPDF_FormFiller_Xfa_Bridge::_processTemplate (
DOMNode $node [, array $nameParts = array ( ) [, array &$namePathCache = array ( ) [, string $currentNamePath = '' [, array &$dataPathCache = array ( ) [, string $currentDataPath = '' [, array &$xpathCache = array ( ) [, string $currentXPath = '' ]]]]]]]
): void

Processes a template node recursively.

This method resolves the field names representing the AcroForm fields in the PDF structure and ensures direct data pathes.

Parameters
$node : DOMNode
 
$nameParts : array
 
$namePathCache : array
 
$currentNamePath : string
 
$dataPathCache : array
 
$currentDataPath : string
 
$xpathCache : array
 
$currentXPath : string
 
Exceptions

Throws SetaPDF_FormFiller_Exception

cleanUp()

public SetaPDF_FormFiller_Xfa_Bridge::cleanUp (
void
): void

Release memory and cycled references.

getAcroFormFieldNamesToTemplateNodes()

Get all template nodes by their corresponding name used in the AcroForm representation.

getDataNodeByFieldName()

public SetaPDF_FormFiller_Xfa_Bridge::getDataNodeByFieldName (
string $name [, boolean $create = true ]
): bool|DOMElement

Gets a data node by a field name.

This method returns the matching data node (DOMElement or DOMAttributeNode) object which is matched to the given field. If no data node is found it will create a new data node. If the field is defined to bind to nothing (match="none") the method will return false.

If an unknown fieldname is passed the method will throw an InvalidArgumentException exception.

Parameters
$name : string
 
$create : boolean

Defines if a data node should be created if it cannot be found.

Exceptions

Throws InvalidArgumentException

See

getNoneBindingNodes()

Get the fields with no bindings.

getSameBoundFields()

public SetaPDF_FormFiller_Xfa_Bridge::getSameBoundFields (
string|DOMElement $fieldNode [, bool $asNames = false ]
): array|DOMElement[]

Get field names or nodes which are bound to the same data node.

Parameters
$fieldNode : string|DOMElement
 
$asNames : bool

Defines whether the method should return the names or field nodes.

Return Values

An array of field names or fields (DOMElements).

getTemplateNode()

public SetaPDF_FormFiller_Xfa_Bridge::getTemplateNode (
string $fieldName
): bool|DOMElement

Get a fields node from the template packet.

Parameters
$fieldName : string
 

getXPathsToFields()

Get a mapping from simple XPathes to field nodes.

isGlobalBinding()

public SetaPDF_FormFiller_Xfa_Bridge::isGlobalBinding (
string|DOMElement $fieldNode
): bool

Checks a field node for a global binding.

Parameters
$fieldNode : string|DOMElement