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

[bradleyt]

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.

[SergeyBiryukov]

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.

[bradleyt]

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?

[SergeyBiryukov]

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

[bradleyt]

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)

[SergeyBiryukov]

Thanks for the patch @bradleyt, it's a great start.

Given that the .htaccess file directives are server-side and specified in English I've intentionally not passed these instructions through __()

With over 50% of WordPress installations using a non-English locale, I think these instructions should be translatable, otherwise they don't provide any benefit to the user who does not understand them.

While testing the patch, I realized that ​extract_from_markers() needs to skip these instructions. Otherwise, if .htaccess is not writable, options-permalink.php​ would always have a mismatch between the generated rewrite rules and the ones read from the file, and display the "You should update your .htaccess now" message.

47466.2.diff​ is an updated patch, with the above considerations in mind.

Before:

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

# END WordPress

After:

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

# END WordPress

[bradleyt]

@SergeyBiryukov Thanks for the feedback, your update looks good.

One thing to consider is that locales are now set on a per-user basis, with a site-wide locale acting as the default. I do wonder if it is better for the .htaccess to be written in the site-wide locale, as opposed to the locale of the user who last triggered a hard flush-permalinks. What do you think?

[SergeyBiryukov]

Replying to bradleyt:

One thing to consider is that locales are now set on a per-user basis, with a site-wide locale acting as the default. I do wonder if it is better for the .htaccess to be written in the site-wide locale, as opposed to the locale of the user who last triggered a hard flush-permalinks. What do you think?

Good catch, thanks! 47466.3.diff​ addresses that.

[SergeyBiryukov]

In 45694:

Rewrite Rules: Add a comment to # BEGIN/END .htaccess markers to clarify that the directives are dynamically generated, and should only be modified via WordPress filters.

Introduce insert_with_markers_inline_instructions filter to modify the default instructions text.

Props bradleyt, SergeyBiryukov.
Fixes #47466.

[SergeyBiryukov]

In 45696:

Coding Standards: Fix WPCS violations in [45694].

See #47466.