Implement bypass rules for S3 uploads

[Luc-cpl]

This pull request introduces a robust file bypass system for the S3 Uploads plugin, allowing specific file paths to avoid S3 operations and instead use alternative behaviors (such as pretending files exist, ignoring them, or redirecting to local storage). The changes provide flexible configuration via PHP constants or filters, integrate bypass logic throughout the stream wrapper, and add comprehensive tests for all bypass scenarios.

Motivation

Some WordPress plugins incorrectly use the uploads directory to store operational files such as .php, .htaccess, index.php, or index.html. In many cases, these plugins also perform filesystem checks on every request to verify the presence of these files and recreate them if they are missing.

When the uploads directory is backed by S3 via the stream wrapper, these behaviors can trigger unnecessary remote operations or cause compatibility issues, since these files are not intended to be stored in object storage.

This feature introduces a bypass mechanism that allows these specific files or paths to avoid S3 interactions entirely, preventing excessive remote calls while maintaining compatibility with plugins that expect traditional filesystem semantics.

File bypass system implementation

• Added the new File_Bypass class in inc/class-file-bypass.php, which defines and manages file bypass rules, supporting three actions: void, exists, and local. Rules can be configured via PHP constants or the s3_uploads_bypass_rules filter.
• Integrated the bypass system into the S3 stream wrapper (inc/class-stream-wrapper.php), so file operations (open, write, unlink, stat) respect bypass rules and perform the appropriate action (ignore, pretend, or redirect to local filesystem). [1] [2] [3] [4] [5] [6]

Testing and validation

• Added a comprehensive test suite in tests/test-file-bypass.php to verify all bypass behaviors (void, exists, local) and ensure regular files are unaffected. Tests cover matching logic, file existence, read/write/unlink operations, and directory creation for local bypasses.