Index

  1. \setasign\SetaPDF2
    1. FormFiller
      1. Xfa
      2. Xfa
        1. Bridge
        2. Som

setasign\SetaPDF2\FormFiller\Xfa

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

File: /SetaPDF v2/FormFiller/Xfa/Bridge.php
Old class name (alias): \SetaPDF_FormFiller_Xfa_Bridge

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

Methods

Properties

Properties

$_acroFormFieldNamesToTemplateNodes

protected array Bridge::$_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

protected string Bridge::$_currentBinding

The current found binding from an accestor node.

$_currentRootIndex

protected int Bridge::$_currentRootIndex

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

$_data

protected \DOMElement Bridge::$_data

The data node.

$_dataNodeByTemplateNode

protected \SplObjectStorage Bridge::$_dataNodeByTemplateNode

The data node for a template node.

$_dataPathByField

protected \SplObjectStorage Bridge::$_dataPathByField

The default data path by a field node.

$_dataProcessed

protected bool Bridge::$_dataProcessed = false

Flag indicating if the data were processed or not.

$_dataRefBinding

protected \SplObjectStorage Bridge::$_dataRefBinding

The dataRef bindings of field nodes.

$_fieldToFieldName

protected \SplObjectStorage Bridge::$_fieldToFieldName

Fieldnames by field nodes.

$_form

protected \DOMElement Bridge::$_form

The form node.

$_globalBinding

protected \SplObjectStorage Bridge::$_globalBinding

Global bindings by field nodes.

$_noneBinding

protected \SplObjectStorage Bridge::$_noneBinding

None bindings by field nodes.

$_template

protected \DOMElement Bridge::$_template

The template node.

$_xpathsToFields

protected \SplObjectStorage Bridge::$_xpathsToFields

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


Methods

__construct()

public Bridge::__construct (
\DOMElement $template,
\DOMElement $data,
\DOMElement $form
)

The constructor

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

Throws \setasign\SetaPDF2\FormFiller\Exception

_bindDataNode()

protected Bridge::_bindDataNode (
array $path,
\DOMNode $dataNode,
string $method,
bool $allowOverwrite = true
): bool

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 : bool
 

_createDataNode()

protected Bridge::_createDataNode (
\DOMElement $fieldNode
): \DOMElement

Creates of gets a data node by a field node.

Parameters
$fieldNode : \DOMElement
 

_doDirectMatch()

private Bridge::_doDirectMatch (
array $path
): bool|\DOMElement

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

Parameters
$path : array
 
Exceptions

Throws \Exception

_doScopeMatch()

private Bridge::_doScopeMatch (
array $path
): bool|\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
 
Exceptions

Throws \Exception

_ensureDataValue()

protected 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()

protected Bridge::_evaluateDataRefBindings (
\DOMElement $fieldNode
): bool

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

Parameters
$fieldNode : \DOMElement
 
Exceptions

Throws \Exception

_evaluateGlobalBindings()

protected Bridge::_evaluateGlobalBindings (
\DOMElement $fieldNode
): bool

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

Parameters
$fieldNode : \DOMElement
 
Exceptions

Throws \Exception

_filtertBindings()

private 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 Bridge::_isBind (
\DOMNode $dataNode
): bool|\DOMNode

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

Parameters
$dataNode : \DOMNode
 

_parseTemplate()

protected Bridge::_parseTemplate (
void
): void

Parses the template and evaluates direct and global bindings.

Exceptions

Throws \setasign\SetaPDF2\FormFiller\Exception

_processData()

protected 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 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 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 \setasign\SetaPDF2\FormFiller\Exception

cleanUp()

public Bridge::cleanUp (
void
): void

Release memory and cycled references.

getAcroFormFieldNamesToTemplateNodes()

public Bridge::getAcroFormFieldNamesToTemplateNodes (
void
): \DOMElement[]

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

getDataNodeByFieldName()

public Bridge::getDataNodeByFieldName (
string $name,
bool $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 : bool

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

Exceptions

Throws \InvalidArgumentException

See

getNoneBindingNodes()

public Bridge::getNoneBindingNodes (
void
): \SplObjectStorage

Get the fields with no bindings.

getSameBoundFields()

public 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 Bridge::getTemplateNode (
string $fieldName
): bool|\DOMElement

Get a fields node from the template packet.

Parameters
$fieldName : string
 

getXPathsToFields()

public Bridge::getXPathsToFields (
void
): \SplObjectStorage

Get a mapping from simple XPathes to field nodes.

isGlobalBinding()

public Bridge::isGlobalBinding (
string|\DOMElement $fieldNode
): bool

Checks a field node for a global binding.

Parameters
$fieldNode : string|\DOMElement
 

© 2025 Setasign GmbH & Co. KG · Contact / Imprint · Data Privacy Statement (German)