WordPress.org

Make WordPress Core

Opened 2 weeks ago

Last modified 9 days ago

#47466 new enhancement

Add a comment to .htaccess markers, labelling inserted strings as read-only/ dynamic

Reported by: bradleyt Owned by:
Milestone: 5.3 Priority: normal
Severity: minor Version:
Component: Rewrite Rules Keywords: has-patch needs-unit-tests
Focuses: docs Cc:

Description

When using WordPress on an Apache server, with pretty permalinks enabled, WordPress will write rewriteRule directives to the .htaccess file in order to allow the pretty permalink functionality. On an out-the-box WordPress installation this will look like so:

# BEGIN WordPress
<IfModule mod_rewrite.c>
RewriteEngine On
RewriteBase /
RewriteRule ^index\.php$ - [L]
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-d
RewriteRule . /index.php [L]
</IfModule>
# END WordPress

This inserted block is wrapped in BEGIN WordPress/ END WordPress comments, referred to as markers. WordPress then uses these markers in order to update the correct part of the .htaccess file if the htacess file needs to be rewritten.

I work for a development company, who host a number of WordPress and non-WordPress sites. We frequently need to make changes to the htaccess file, which we generally do outside of WordPress (i.e. by directly editing the file). For example, we often add HTTP redirects via the htaccess file. Often the sysadmins who make these changes are not familiar with WordPress, and insert their custom rules within the BEGIN WordPress/ END WordPress markers, assuming that any WordPress-related rules should go between these comments. These custom changes are then discarded by WordPress at a later date, when the rewrite rules are next flushed.

I propose that additional comments are added to the htaccess file, to make it clear the the contents of the markers should only be edited via the use of WordPress filters.

For example:

# BEGIN WordPress
# 
# The directives (lines) between `BEGIN WordPress` and `END WordPress` are dynamically generated,
# and should only be modified through the use of WordPress filters.
# Any changes to the directives between these markers will be overwritten.
<IfModule mod_rewrite.c>
RewriteEngine On
RewriteBase /
RewriteRule ^index\.php$ - [L]
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-d
RewriteRule . /index.php [L]
</IfModule>
# END WordPress

It's worth noting that some plugins also use insert_with_markers, and so this should be returned with the correct marker name for any use of insert_with_markers.

Attachments (1)

47466.diff (1.3 KB) - added by bradleyt 9 days ago.

Download all attachments as: .zip

Change History (5)

#1 in reply to: ↑ description ; follow-up: @SergeyBiryukov
13 days ago

  • Keywords needs-patch added
  • Milestone changed from Awaiting Review to Future Release

Hi @bradleyt, welcome to WordPres Trac! Thanks for the ticket.

Often the sysadmins who make these changes are not familiar with WordPress, and insert their custom rules within the BEGIN WordPress/ END WordPress markers, assuming that any WordPress-related rules should go between these comments. These custom changes are then discarded by WordPress at a later date, when the rewrite rules are next flushed.

I see the same situation on support forums from time to time. I agree it would be great to include some additional comments there along the lines you've proposed.

#2 in reply to: ↑ 1 @bradleyt
12 days ago

  • Focuses docs added

Replying to SergeyBiryukov:

Often the sysadmins who make these changes are not familiar with WordPress, and insert their custom rules within the BEGIN WordPress/ END WordPress markers, assuming that any WordPress-related rules should go between these comments. These custom changes are then discarded by WordPress at a later date, when the rewrite rules are next flushed.

I see the same situation on support forums from time to time. I agree it would be great to include some additional comments there along the lines you've proposed.

That's great. It feels like the success of this change depends on the actual comment being as clear as possible (whilst still remaining fairly succinct in order to get the point across quickly and easily). I'd be interested to know what you think of the suggested wording in the original description?

#3 @SergeyBiryukov
11 days ago

  • Milestone changed from Future Release to 5.3

The suggested wording looks good to me, moving for 5.3 consideration.

@bradleyt
9 days ago

#4 @bradleyt
9 days ago

  • Keywords has-patch needs-unit-tests added; needs-patch removed

In 47466.diff is an initial implementation of this feature. A few notes:

  • I could not find any tests relating to insert_with_markers - I assume some will need writing before this is merged, but I'm unclear in what file these should go in within the tests directory
  • I've introduced a filter insert_with_markers_inline_instructions, which will allow for any plugins using insert_with_markers to provide marker-specific instructions. This will also allow hosting companies to modify the WordPress text to match any environment-specific restrictions or help they want to provide
  • Given that the .htaccess file directives are server-side and specified in English I've intentionally not passed these instructions through __()
  • $instructions_markers is prepended to $insertion so that the $existing_lines === $insertion logic evaluates to true (therefore meaning that changes to the instructions are reflected in the .htaccess file next time the rewrite_rules are flushed)
Last edited 9 days ago by bradleyt (previous) (diff)
Note: See TracTickets for help on using tickets.