feat: Add phone format properties to resolve issue #441 #475

chetanupare · 2026-01-28T20:21:24Z

Create new PhoneFormatProperties object type with label, mask, regex, instruction, and type fields
Add phoneFormatProperties field to FieldWithPhoneFormat interface with resolver
Support custom phone formats via gform_phone_formats filter
Update tests to include new phoneFormatProperties field
Register PhoneFormatProperties type in TypeRegistry

Resolves: #441

What

Adds phoneFormatProperties field to phone fields returning label, mask, regex, instruction, and type.

Why

Addresses issue #441 - users need format details beyond just the format name for frontend implementation.

How

Created PhoneFormatProperties object type
Added field to FieldWithPhoneFormat interface with resolver
Supports custom formats via gform_phone_formats filter
Updated tests and registered new type

Testing Instructions

Create form with phone field
Query: phoneFormatProperties { label mask regex instruction type }
Verify returns format details for standard/international formats

Additional Info

Response Example:
{
  "data": {
    "gfForm": {
      "formFields": {
        "nodes": [
          {
            "phoneFormat": "standard",
            "phoneFormatProperties": {
              "label": "(###) ###-####",
              "mask": "(999) 999-9999",
              "regex": "/^\\D?(\\d{3})\\D?\\D?(\\d{3})\\D?(\\d{4})$/",
              "instruction": "(###) ###-####",
              "type": "standard"
            }
          }
        ]
      }
    }
  }
}

Checklist:

This PR is tested to the best of my abilities.
This PR follows the WordPress Coding Standards.
This PR has proper inline documentation.
This PR has unit tests to verify the code works as intended.
The changes in this PR have been noted in CHANGELOG.md

- Create new PhoneFormatProperties object type with label, mask, regex, instruction, and type fields - Add phoneFormatProperties field to FieldWithPhoneFormat interface with resolver - Support custom phone formats via gform_phone_formats filter - Update tests to include new phoneFormatProperties field - Register PhoneFormatProperties type in TypeRegistry Resolves: AxeWP#441

- Fix PHPCS violations in FieldWithPhoneFormat.php - Add proper inline comment punctuation - Add phpcs:ignore for third-party gform_phone_formats hook - Add changelog entry for phoneFormatProperties feature

justlevine · 2026-01-29T21:47:24Z

Thanks so much for submitting this @chetanupare 🙇 I should hopefully have time over the weekend to review. (Feel free to ignore the copilot comments I just triggered - 80% of the time they're slop, but every once in a while they catch something helpful)

codecov · 2026-01-29T21:50:11Z

Welcome to Codecov 🎉

Once you merge this PR into your default branch, you're all set! Codecov will compare coverage reports and display results in all future pull requests.

ℹ️ You can also turn on project coverage checks and project coverage reporting on Pull Request comment

Thanks for integrating Codecov - We've got you covered ☂️

Copilot

Pull request overview

This PR adds a phoneFormatProperties field to phone fields in the GraphQL schema to expose detailed phone format configuration (label, mask, regex, instruction, and type) from Gravity Forms. This addresses issue #441 where users needed access to format properties beyond just the format name for frontend implementation.

Changes:

Added new PhoneFormatProperties GraphQL object type to represent phone format configuration details
Extended FieldWithPhoneFormat interface with phoneFormatProperties field including resolver that uses the gform_phone_formats filter
Updated tests to query the new field and added test expectations

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
src/Type/WPObject/PhoneFormatProperties.php	New GraphQL object type defining the structure for phone format properties
src/Type/WPInterface/FieldSetting/FieldWithPhoneFormat.php	Added phoneFormatProperties field with resolver that applies gform_phone_formats filter
src/Registry/TypeRegistry.php	Registered the new PhoneFormatProperties type in the type registry
tests/wpunit/PhoneFieldTest.php	Updated test query to include phoneFormatProperties field
tests/_support/Helper/GFHelpers/ExpectedFormFields.php	Added test expectations for phoneFormatProperties field
CHANGELOG.md	Documented the new feature

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-01-29T21:52:59Z

src/Type/WPInterface/FieldSetting/FieldWithPhoneFormat.php

+							'international' => [
+								'label'       => 'International',
+								'mask'        => false,
+								'regex'       => false,
+								'instruction' => __( 'International phone numbers must start with a + followed by the country code and phone number.', 'wp-graphql-gravity-forms' ),
+								'type'        => 'international',
+							],


The 'international' format has 'mask' and 'regex' set to boolean false, but the PhoneFormatProperties type defines these fields as String (non-nullable). This creates a type mismatch that will cause GraphQL validation errors when international format is used. Consider converting false values to null in the resolver or updating the PhoneFormatProperties type to make these fields nullable (String instead of String!).

Copilot · 2026-01-29T21:52:59Z

tests/_support/Helper/GFHelpers/ExpectedFormFields.php

+
+		// Add phoneFormatProperties field
+		if ( ! empty( $field->phoneFormat ) ) {
+			$properties[] = $this->expectedField( 'phoneFormatProperties.label', self::NOT_NULL );
+			$properties[] = $this->expectedField( 'phoneFormatProperties.mask', self::NOT_NULL );
+			$properties[] = $this->expectedField( 'phoneFormatProperties.regex', self::NOT_NULL );


The test expectations assume all fields (mask, regex, label, instruction, type) will be NOT_NULL when phoneFormat is set. However, for the 'international' format, mask and regex are false (boolean). This test will fail when testing with international phone format. The test expectations should handle the case where mask and regex can be null/false, or the resolver should be fixed to convert false to null.

Suggested change

// Add phoneFormatProperties field

if ( ! empty( $field->phoneFormat ) ) {

$properties[] = $this->expectedField( 'phoneFormatProperties.label', self::NOT_NULL );

$properties[] = $this->expectedField( 'phoneFormatProperties.mask', self::NOT_NULL );

$properties[] = $this->expectedField( 'phoneFormatProperties.regex', self::NOT_NULL );

// Add phoneFormatProperties field

if ( ! empty( $field->phoneFormat ) ) {

$properties[] = $this->expectedField( 'phoneFormatProperties.label', self::NOT_NULL );

// For the 'international' phone format, mask and regex can be null/false.

if ( 'international' === $field->phoneFormat ) {

$properties[] = $this->expectedField( 'phoneFormatProperties.mask', self::IS_NULL );

$properties[] = $this->expectedField( 'phoneFormatProperties.regex', self::IS_NULL );

} else {

$properties[] = $this->expectedField( 'phoneFormatProperties.mask', self::NOT_NULL );

$properties[] = $this->expectedField( 'phoneFormatProperties.regex', self::NOT_NULL );

}

src/Type/WPObject/PhoneFormatProperties.php

Copilot · 2026-01-29T21:53:00Z

src/Type/WPInterface/FieldSetting/FieldWithPhoneFormat.php

+					// Return the properties for the selected format.
+					return $phone_formats[ $field->phoneFormat ] ?? null;


The resolver returns the raw array from the gform_phone_formats filter without validation. Custom phone formats added via this filter may not include all required fields (label, mask, regex, instruction, type) or may use inconsistent types (e.g., false instead of null). Consider adding validation to ensure the returned data structure is consistent and compatible with the PhoneFormatProperties type, or add resolvers for individual fields to handle type conversion.

Suggested change

// Return the properties for the selected format.

return $phone_formats[ $field->phoneFormat ] ?? null;

// Get the properties for the selected format.

$format = $phone_formats[ $field->phoneFormat ] ?? null;

if ( ! is_array( $format ) ) {

return null;

}

// Normalize the format to ensure all required keys exist and values are of compatible types.

$required_keys = [

'label' => null,

'mask' => null,

'regex' => null,

'instruction' => null,

'type' => null,

];

$normalized = [];

foreach ( $required_keys as $key => $default ) {

$value = $format[ $key ] ?? $default;

// Convert explicit false values to null to align with nullable GraphQL fields.

if ( $value === false ) {

$value = null;

}

// Ensure the value is a scalar; otherwise, fall back to the default (null).

if ( ! is_scalar( $value ) && null !== $value ) {

$value = $default;

}

$normalized[ $key ] = $value;

}

return $normalized;

Copilot · 2026-01-29T21:53:00Z

tests/wpunit/PhoneFieldTest.php

+				phoneFormatProperties {
+					label
+					mask
+					regex
+					instruction
+					type
+				}


The tests only use the 'standard' phone format by default (see PropertyHelper.php line 360). There is no test coverage for the 'international' format case where mask and regex are false. Consider adding a test case that specifically tests the international phone format to ensure the phoneFormatProperties field works correctly with null/false values.

- Add dedicated PhoneFieldInternationalFormatTest - Normalize phone format properties for null/false values - Adjust phone format expectations for international mask/regex

chetanupare

test: Added international phone format coverage

Added dedicated PhoneFieldInternationalFormatTest
Normalized phone format properties for null/false values
Adjusted phone format expectations for international mask/regex

chetanupare

fix: Used callable descriptions for phone format properties

Chetan Upare added 2 commits January 29, 2026 01:41

fix: Address coding standards and add changelog entry

c3b1066

- Fix PHPCS violations in FieldWithPhoneFormat.php - Add proper inline comment punctuation - Add phpcs:ignore for third-party gform_phone_formats hook - Add changelog entry for phoneFormatProperties feature

justlevine requested review from Copilot and justlevine January 29, 2026 21:45

justlevine added status: needs review 🧐 Needs to be reviewed by a codeowner type: enhancement ⚡ Improves on an existing feature labels Jan 29, 2026

Copilot started reviewing on behalf of justlevine January 29, 2026 21:48 View session

Copilot AI reviewed Jan 29, 2026

View reviewed changes

test: Add international phone format coverage

da3d808

- Add dedicated PhoneFieldInternationalFormatTest - Normalize phone format properties for null/false values - Adjust phone format expectations for international mask/regex

chetanupare commented Jan 29, 2026

View reviewed changes

fix: Use callable descriptions for phone format properties

a810704

chetanupare commented Jan 29, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

feat: Add phone format properties to resolve issue #441 #475

feat: Add phone format properties to resolve issue #441 #475

Uh oh!

chetanupare commented Jan 28, 2026

Uh oh!

justlevine commented Jan 29, 2026

Uh oh!

codecov bot commented Jan 29, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Jan 29, 2026

Uh oh!

Copilot AI Jan 29, 2026

Uh oh!

Uh oh!

Copilot AI Jan 29, 2026

Uh oh!

Copilot AI Jan 29, 2026

Uh oh!

chetanupare left a comment •

edited

Loading

Uh oh!

chetanupare left a comment •

edited

Loading

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

		// Return the properties for the selected format.
		return $phone_formats[ $field->phoneFormat ] ?? null;

-					// Return the properties for the selected format.
-					return $phone_formats[ $field->phoneFormat ] ?? null;
+					// Get the properties for the selected format.
+					$format = $phone_formats[ $field->phoneFormat ] ?? null;
+					if ( ! is_array( $format ) ) {
+						return null;
+					}
+					// Normalize the format to ensure all required keys exist and values are of compatible types.
+					$required_keys = [
+						'label'       => null,
+						'mask'        => null,
+						'regex'       => null,
+						'instruction' => null,
+						'type'        => null,
+					];
+					$normalized = [];
+					foreach ( $required_keys as $key => $default ) {
+						$value = $format[ $key ] ?? $default;
+						// Convert explicit false values to null to align with nullable GraphQL fields.
+						if ( $value === false ) {
+							$value = null;
+						}
+						// Ensure the value is a scalar; otherwise, fall back to the default (null).
+						if ( ! is_scalar( $value ) && null !== $value ) {
+							$value = $default;
+						}
+						$normalized[ $key ] = $value;
+					}
+					return $normalized;

Uh oh!

feat: Add phone format properties to resolve issue #441 #475

Are you sure you want to change the base?

feat: Add phone format properties to resolve issue #441 #475

Uh oh!

Conversation

chetanupare commented Jan 28, 2026

What

Why

How

Testing Instructions

Additional Info

Checklist:

Uh oh!

justlevine commented Jan 29, 2026

Uh oh!

codecov bot commented Jan 29, 2026

Welcome to Codecov 🎉

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Jan 29, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 29, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Copilot AI Jan 29, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 29, 2026

Choose a reason for hiding this comment

Uh oh!

chetanupare left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

chetanupare left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

chetanupare left a comment •

edited

Loading

chetanupare left a comment •

edited

Loading