Add ID to Section titles generated by Settings API

[wetah]

I see that there's a lot of debate around improvements to the Forms generated by ​do_settings_sections.

• https://core.trac.wordpress.org/ticket/51086
• https://core.trac.wordpress.org/ticket/43303
• https://core.trac.wordpress.org/ticket/39441

I know more radical changes won't move up easily so I would like to suggest a simple one: having the section ID in the section title. For instance this:

<?php
     if ( $section['title'] ) {
        echo "<h2>{$section['title']}</h2>\n";
     }

To become something like this:

<?php
     if ( $section['title'] ) {
        echo '<h2 id="' . $section['id'] . '">' . $section['title'] . '</h2>\n';
     }

For consistency, I would add the IDs also to the Core forms that have sections not generated by do_settings_sections, such as options-media.php, options-reading.php, etc. They already do something different which is to add a 'title' class to all their section titles. This makes me think that maybe we should have a filter to change that title markup in the end... but that can be for another topic.

The main motivation for doing that is to allow hash navigation via URL. We could easily in the documentation have links such as wp-admin/options-discussion.php#avatars, which I think it is a huge benefit if we're talking long forms. I know it wouldn't solve more complex issues but can be beneficial even for Accessibility and for those who want to customize their forms via CSS, as discussed in the other linked tickets.

Trac ticket:

## Use of AI Tools

---
Ticket Details: https://core.trac.wordpress.org/ticket/65027

This Pull Request is for code review only. Please keep all other discussion in the Trac ticket. Do not merge this Pull Request. See ​GitHub Pull Requests for Code Review in the Core Handbook for more details.

[joedolson]

An additional benefit this could add is having a hook that can be used for aria-describedby or aria-labelledby if a user needed those to reference the existing section heading. Seems useful to me.

I pushed two commits:

1. Uses wp_unique_id with a prefix that is made of a string wp-settings-section- + the section ID.
2. For the core settings H@ headings, I just prepended wp-settings-section- to the IDs added in this PR.

To quickly test the Settings API you can temporarily add this snippet in the options-reading.php file:

add_settings_section( 'awesome-avatars', 'My avatars section title', '__return_false', 'andreatest' );
add_settings_field(
	'color_scheme',
	__( 'Color Scheme' ),
	'__return_false',
	'reading',
	'andreatest'
);
do_settings_sections( 'andreatest' );

add_settings_section( 'nice-icons', 'My icons section title', '__return_false', 'andreatest2' );
add_settings_field(
	'color_scheme',
	__( 'Color Scheme' ),
	'__return_false',
	'reading',
	'andreatest2'
);
do_settings_sections( 'andreatest2' );

It will add two section headings. The IDs on the headings will be:

• wp-settings-section-awesome-avatars-1
• wp-settings-section-nice-icons-2

[reneyap]

Tested PR ​#11472 (commit 5144d56) against trunk in a local Docker environment (npm run env:start).

Manual test — used the snippet from comment:8 in options-reading.php:

add_settings_section( 'awesome-avatars', 'My avatars section title', '__return_false', 'andreatest' );
...
do_settings_sections( 'andreatest' );

Resulting markup:

<h2 id="wp-settings-section-awesome-avatars-1">My avatars section title</h2>
<h2 id="wp-settings-section-nice-icons-2">My icons section title</h2>

The wp-settings-section- prefix + wp_unique_id() incrementing suffix works as described, and resolves the ID-collision concern raised in the PR review.

Core forms with static section headings — verified all 5 files touched by the patch render the expected id attributes and enable hash navigation:

• options-media.php: #wp-settings-section-image-sizes, #wp-settings-section-uploading-files
• options-writing.php: #wp-settings-section-post-via-email, #wp-settings-section-update-services
• options-discussion.php: #wp-settings-section-avatars
• options-permalink.php: #wp-settings-section-common-settings, #wp-settings-section-optional

Automated checks:

• Tests_Admin_IncludesTemplate (PHPUnit): 34 tests, 115 assertions, all passing — no regressions.
• PHPCS lint on the 5 changed files: clean.

No issues found.
Patch tested successfully. I found no regressions, and the proposed fix behaves as expected.

[afercia]

On top of the linked PR, 65027.diff​ adds similar IDs to the headings of the Network Settings sections.

[afercia]

In 62710:

Administration: Add IDs to the headings of the settings sections.

Add IDs to the headings of the settings sections generated by the Settings API. Additionally, adds IDs to the headings of the settings sections in the Core admin settings pages that are not generated by the Settings API.

This allows to reference specific sections by the means of links with a page fragment identifier, useful for documentation and support purposes.

Props wetah, rakeshfalke, reneyap, joedolson, afercia.
Fixes #65027.