WordPress.org

Make WordPress Core

Opened 6 months ago

Closed 5 months ago

Last modified 5 months ago

#47466 closed enhancement (fixed)

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

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

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 (3)

47466.diff (1.3 KB) - added by bradleyt 6 months ago.
47466.2.diff (1.4 KB) - added by SergeyBiryukov 6 months ago.
47466.3.diff (1.6 KB) - added by SergeyBiryukov 5 months ago.

Download all attachments as: .zip

Change History (14)

#1 in reply to: ↑ description ; follow-up: @SergeyBiryukov
6 months 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
6 months 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
6 months ago

  • Milestone changed from Future Release to 5.3

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

@bradleyt
6 months ago

#4 follow-up: @bradleyt
6 months 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 6 months ago by bradleyt (previous) (diff)

This ticket was mentioned in Slack in #core by bradleyt. View the logs.


6 months ago

#6 @SergeyBiryukov
6 months ago

  • Owner set to SergeyBiryukov
  • Status changed from new to reviewing

#7 in reply to: ↑ 4 @SergeyBiryukov
6 months ago

  • Keywords commit added

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

#8 follow-up: @bradleyt
6 months ago

@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?

#9 in reply to: ↑ 8 @SergeyBiryukov
5 months ago

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.

#10 @SergeyBiryukov
5 months ago

  • Resolution set to fixed
  • Status changed from reviewing to closed

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.

#11 @SergeyBiryukov
5 months ago

In 45696:

Coding Standards: Fix WPCS violations in [45694].

See #47466.

Note: See TracTickets for help on using tickets.