fix(form): add labels shortcode attribute

[faisalahammad]

Description

Add a labels attribute to the [pods-form] (and [pods form=1]) shortcode so per-field labels can be overridden from the shortcode itself. This is useful for built-in user fields like user_nicename, display_name, and user_email where labels are hardcoded in English and site translation tools do not pick them up.

Usage:

[pods-form name="user" fields="user_nicename,display_name,user_email" labels="user_nicename:Utilizador,display_name:Nome Completo,user_email:Correio Eletronico"]

The attribute uses : as field:label separator and , as pair separator. Label values are sanitized with sanitize_text_field().

Related GitHub issue(s)

Fixes #7243

Testing instructions

1. Create a WordPress page containing [pods-form name="user" fields="user_nicename,display_name" labels="user_nicename:Nickname,display_name:Full Name"]
2. View the page and confirm the form shows "Nickname" and "Full Name" instead of the default English labels
3. Create a second shortcode without labels on the same page and confirm default labels still show (no leak)
4. Insert a Pods Form block in Gutenberg editor and verify it still renders without error

Screenshots / screencast

N/A — no visible UI changes beyond shortcode output labels.

Changelog text for these changes

Feature: You can now override per-field labels in the [pods-form] shortcode using the labels attribute. #7243 (@faisalahammad)

PR checklist

• I have tested my own code to confirm it works as I intended.
• My code follows the WordPress Coding Standards.
• My code follows the WordPress Inline Documentation Standards.
• My code includes automated tests for PHP and/or JS (if applicable).

[what-the-diff]

PR Summary

• Introduction of static property $form_labels
  This property is introduced in PodsForm.php to store temporary modifications to form field labels.

• Creation of set_form_labels() and clear_form_labels() methods
  These are two new methods in PodsForm.php. set_form_labels() is used to sanitize and store label modifications, while clear_form_labels() is used to remove label modifications after a form has been displayed.

• Alteration to label() method
  This method in PodsForm.php now utilizes the $form_labels property to fetch customized labels based on field names.

• Modification to pods_shortcode() function
  Located in general.php, this function has been updated to parse a new labels attribute for shortcodes and clear form labels after displaying them.

• Improvement to pods_shortcode_parse_labels() function
  This function has been upgraded to convert a labels string from a shortcode attribute into a format that can be used to override form label text.

• Support for labels attribute in pods_shortcode_form()
  This upgrade extends the ability to use labels attribute for customization, located in the 'general.php' file.

• Addition of new properties for labels
  Additional properties for labels have been added in Form.php to support its use in WordPress shortcodes.

• Introduction of unit tests
  Added new unit tests in PodsFormLabelsTest.php to ensure that the label modification mechanism works correctly and that custom labels do not persist between different forms.

[faisalahammad]

AI disclosure: this PR was written with Claude Opus 5 assistance, reviewed and tested by me.

[faisalahammad]

Review: the override works, but the new entry point is untested

The mechanism is sound. ui/forms/list-row.php calls PodsForm::output_label( $field['name'], ... ) with the unprefixed field name — the name_prefix is applied later inside label() at classes/PodsForm.php:117 — so the array key matches and the override genuinely reaches the render path.

The existing tests are real too: PodsFormLabelsTest.php follows the convention (namespace Pods_Unit_Tests\..., extends Pods_UnitTestCase, no WPBrowser type hint) and would fatal on unpatched code.

Three things to tighten.

1. Nothing tests pods_shortcode_parse_labels()

That's the actual new user-facing surface — the field:Label,field2:Label2 parsing, the unset( $tags['labels'] ), and the finally cleanup — and it's the part most likely to regress. The tests only exercise the static directly. Worth covering:

• a labels string parses into the expected map
• malformed input (missing :, trailing ,, a label containing :) degrades safely
• labels is removed from $tags so it doesn't reach the query
• the static is cleared after pods_shortcode() returns, including when it throws

2. The block gains an attribute with no control

labels is added to the attributes maps in src/Pods/Blocks/Types/Form.php (both places) but not to Form::get_fields(), which holds the editor controls (e.g. 'name' => 'label' at :198). So the Gutenberg Pods Form block accepts the attribute but offers no way to set it.

3. Redundant double-parse

pods_shortcode_form() calls pods_shortcode_parse_labels( $tags ), then pods_shortcode() calls it again. Harmless only because the first call unset()s the key — worth dropping one.

Design note

apply_filters( 'pods_form_ui_label_text', $label, $name, $help, $options ) already exists at classes/PodsForm.php:132 and does this job without new global static state. If the shortcode attribute is the goal, routing it through that filter for the duration of the render would avoid adding a static that has to be cleaned up in a finally.

Disclosure: this review was produced with AI assistance and verified against the branch code before posting.