GravityKit\GravityMigrate\Schema\GfMergeTag
Parses and rewrites Gravity Forms field merge tags.
Gravity Forms writes a field merge tag as {Label:ID}, where the label is the
field's admin label and the ID follows the colon: {Email:2}, {Name (First):1.3},
{Checkbox:4:value}. The colon is required; a tag Gravity Forms does not match is passed
through to the recipient as literal text, so a notification mails out its own placeholders.
The pattern mirrors GFCommon::replace_variables() so this agrees with what Gravity Forms itself considers a field tag, including labels that contain a colon.
Since: %ver%
Source: src/Schema/GfMergeTag.php:23
Details
- Kind:
class - Namespace:
GravityKit\GravityMigrate\Schema
Methods
| Method | Description |
|---|---|
replace_field_tags() | Rewrites every field merge tag in a string. |
find_field_tags() | Returns every field merge tag found in a string. |
field_tag() | Writes a Gravity Forms field merge tag. |
labels_from_fields() | What each field and each of its inputs is called, keyed by the id a tag would name. |
composite_expansions() | The tag text that stands in for a reference to a whole composite field. |
expansion_for() | The replacement text for a bare tag on $field_id, or '' when it needs none. |
has_field_tag() | Whether a string contains at least one field merge tag. |
Method Reference
replace_field_tags()
public static function replace_field_tags( string $text, callable $callback ): string
Rewrites every field merge tag in a string.
The callback receives an array with raw, field_id, input_id, input and
modifiers, and returns the replacement string. Returning $tag['raw'] leaves
the tag untouched.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
$text | string | Text possibly containing merge tags. | |
$callback | callable | Replacement callback. |
Returns
string
Since: %ver%
Source: src/Schema/GfMergeTag.php:51
find_field_tags()
public static function find_field_tags( string $text ): array
Returns every field merge tag found in a string.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
$text | string | Text possibly containing merge tags. |
Returns
array[]— List of tag descriptors; see describe().
Since: %ver%
Source: src/Schema/GfMergeTag.php:78
field_tag()
public static function field_tag( $field_id, string $label='' ): string
Writes a Gravity Forms field merge tag.
GFCommon::replace_variables() matches /{[^{]?:(\d+(.\w+)?)(:(.?))?}/ — the colon is required. A tag written as {1}, or left in another platform's syntax such as [1], matches nothing and Gravity Forms prints it to the recipient verbatim.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
$field_id | int | string | Field ID, optionally with an input suffix (1.3). | |
$label | string | '' | Field label, shown in the editor. Never affects resolution. |
Returns
string
Since: %ver%
Source: src/Schema/GfMergeTag.php:111
labels_from_fields()
public static function labels_from_fields( array $fields ): array
What each field and each of its inputs is called, keyed by the id a tag would name.
A composite's parts have their own wording, and a tag pointing at one wants that wording
rather than the name of the field around it -- {Last:1.6} rather than {First:1.6},
which is what a label map keyed only by field id produces once a part's reference has
followed it to its input.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
$fields | array | Gravity Forms fields. |
Returns
array<string,— string> Field or input id to label.
Since: %ver%
Source: src/Schema/GfMergeTag.php:135
composite_expansions()
public static function composite_expansions( array $fields ): array
The tag text that stands in for a reference to a whole composite field.
A source platform lets a person write "the name" and mean all of it -- Fluent's
{inputs.names}, Formidable's [298], Forminator's {name-1}, WPForms' {field_id="1"}.
Gravity Forms has no way to say that. A composite is stored one value per input --
get_lead_field_value() returns an array keyed 1.3, 1.6 and so on for any field whose
get_entry_inputs() is non-null (forms_model.php:6364-6381) -- and replace_field_variable()
reads that array with rgar( $value, $input_id ) using the id exactly as the tag wrote it
(common.php:7302-7305). rgar() answers '' for a key that is not there, so a bare
{Full name:1} renders as nothing at all. A field can opt out by overriding
get_value_merge_tag() to accept the whole array; GF_Field_Name does not, and
GF_Field_Address's override only special-cases the country input.
So the whole-field reference is answered with every part it was asking for, written as one tag each: "New request from {First:1.3} {Last:1.6}" mails out "New request from Ada Lovelace". Keeping only the first part would lose the surname with nothing said about it.
Two guards decide which fields get an expansion:
- The type has to be one whose input layout the model knows, which is what
\GfComposites::input_suffixes_for()answers. That excludes a credit card, whose parts nobody wants written into an email, and every non-composite field. - The field has to carry inputs. That is the same condition Gravity Forms branches on, so a
name stored whole under its bare id -- a
simplename field has no inputs -- keeps resolving the way it already does and is left alone.
A hidden input holds no answer, so it contributes no tag and no stray separator.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
$fields | array | Gravity Forms fields. |
Returns
array<string,— string> Field id to the replacement text for a bare tag on it.
Since: %ver%
Source: src/Schema/GfMergeTag.php:192
expansion_for()
public static function expansion_for( array $expansions, $field_id ): string
The replacement text for a bare tag on $field_id, or '' when it needs none.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
$expansions | array | Expansions from composite_expansions(). | |
$field_id | int | string | The id the source reference resolved to. |
Returns
string
Since: %ver%
Source: src/Schema/GfMergeTag.php:247
has_field_tag()
public static function has_field_tag( string $text ): bool
Whether a string contains at least one field merge tag.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
$text | string | Text possibly containing merge tags. |
Returns
bool
Since: %ver%
Source: src/Schema/GfMergeTag.php:266