feat: support GF 3.0 International (formatted) phone numbers

[jakejackson1]

What

Gravity Forms 3.0 adds an International (formatted) phone format that stores the value as a JSON object in the entry. Gravity PDF had no support for it, so it printed the raw JSON:

{"country":"US","national":"2015551232","formatted":"(201) 555-1232","e164":"+12015551232"}

Field_Phone now renders the ISO country code, the dial code, and the formatted number. The dial code is dropped when the field's Show country dial code setting is off, mirroring what the user saw on screen:

Setting	PDF output
Enabled (GF default)	US +1 (201) 555-1232
Disabled	US (201) 555-1232

Detection keys off the stored entry value being JSON, not the field's phoneFormat setting. Entries saved while the field was International (formatted) therefore still display correctly after the field is switched to a format that doesn't store JSON — otherwise those existing entries would revert to showing raw JSON.

Why the dial code is derived rather than looked up

It's obtained by removing the national number from the tail of the E.164 number. Two PHP-side alternatives were checked and rejected:

• GF_Field_Phone::get_dial_code() reads assets/js/src/theme/fields/international-phone/countries.json. That file is not in the distributed Gravity Forms zip (only assets/js/dist/ ships), so it returns an empty string in a real install. It's also private static.
• E164Validator::validate( $e164, true ) does return the dial code, but it's GF 2.9+ while Gravity PDF supports 2.5+, it's an undocumented internal in the global namespace, and the first call loads a 254 KB rules array.

$form_data

$form_data['field'] keeps the displayed number as a string, so templates that echo it keep working if a site switches an existing phone field to the new format. The parts are exposed under a new phone key:

$form_data['field'][14]         // 'US +1 (201) 555-1232'
$form_data['field']['14.Phone'] // 'US +1 (201) 555-1232'
$form_data['field']['Phone']    // 'US +1 (201) 555-1232'

$form_data['phone'][14] => [
    'country'   => 'US',
    'dial_code' => '+1',
    'national'  => '2015551232',
    'formatted' => '(201) 555-1232',
    'e164'      => '+12015551232',
]

This follows the Field_List / Field_Signature precedent of putting structured data under its own top-level key, and 'phone' was added to gfpdf_form_data_key_order.

⚠️ As with the existing list and signature_details_id keys, $form_data['phone'] is not populated for phone fields inside a Repeater, because Field_Repeater merges only the field and html_id keys from its sub-fields. Worth a docs note.

Testing

11 new tests in tests/phpunit/unit-tests/Helper/Fields/Test_Field_Phone.php, covering the US and multi-digit (GB +44) dial-code derivation, both showCountryCode states plus the unset default, the format-switch case, non-JSON pass-through, unrecognised JSON, and $form_data for both shapes. The fixture is built in memory, so it touches no database.

Full suite run against the branch: 1162 tests, 3602 assertions. PHPCS and phpcompat (PHP 7.3 floor) both clean.

Notes for review

• Changelog entries are filed under the existing 6.16.0 release, as a 🎉 Feature alongside the existing "Gravity Forms 3.0 compatibility" line.
• Behaviour is unchanged for US Standard and International (unformatted) phone fields.

🤖 Generated with Claude Code