Add Write File Check to detect plugin directory writes

[davidperezgar]

Fixes #665

Implements a new check to detect when plugins save data in the plugin folder.

Plugin folders are deleted when upgraded, so using them to store any data is problematic. This check helps developers identify these issues and directs them to use the uploads directory or database instead.

Changes Made

1. WriteFileSniff (PHPCS Sniff)

Created phpcs-sniffs/PluginCheck/Sniffs/CodeAnalysis/WriteFileSniff.php:

• Extends AbstractFunctionParameterSniff to detect file write functions
• Monitors functions: fwrite, fputs, file_put_contents, touch, copy, rename, copy_dir, move_dir, unzip_file
• Detects plugin directory indicators:
  • Constants: WP_PLUGIN_DIR, WP_PLUGIN_URL, PLUGINDIR, WPINC, WP_CONTENT_DIR, WP_CONTENT_URL
  • Functions: plugins_url(), plugin_dir_path(), plugin_dir_url()
  • Magic constants: __FILE__, __DIR__
• Allows safe paths using wp_upload_dir(), wp_tempnam(), get_temp_dir()
• Provides clear error messages with remediation guidance

2. Write_File_Check Class

Updated includes/Checker/Checks/Plugin_Repo/Write_File_Check.php:

• Added proper description
• Added documentation URL
• Integrates the sniff into Plugin Check

3. Test Coverage

Test Plugins:

• test-plugin-write-file-with-errors/: Contains 7 examples of incorrect usage
• test-plugin-write-file-without-errors/: Contains examples of correct usage

PHPUnit Tests:

• Write_File_Check_Tests.php: Tests the check class
• WriteFileUnitTest.php and WriteFileUnitTest.inc: Tests the sniff directly

4. Configuration

• Added PluginCheck.CodeAnalysis.WriteFile rule to phpcs-sniffs/PluginCheck/ruleset.xml

Limitations

The sniff uses static analysis and can only detect file write operations where the path is directly specified in the function call. It cannot detect:

• Paths stored in variables before the function call
• Dynamically constructed paths using complex logic
• File writes through wrapper functions or classes

This limitation is acceptable as it catches the most common cases.

Related Resources

• Original guideline text in reviews: https://developer.wordpress.org/plugins/wordpress-org/detailed-plugin-guidelines/
• Settings API: https://developer.wordpress.org/plugins/settings/
• wp_upload_dir(): https://developer.wordpress.org/reference/functions/wp_upload_dir/
• wp_handle_upload(): https://developer.wordpress.org/reference/functions/wp_handle_upload/

Acknowledgments

This check is based on the calls_write_file_warning detection logic from the internal plugin review scanner developed by @frantorres, which has been successfully identifying these issues during manual reviews. This implementation makes that same detection available to plugin developers as an automated check.

[github-actions]

The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the props-bot label.

If you're merging code through a pull request on GitHub, copy and paste the following into the bottom of the merge commit message.

Co-authored-by: davidperezgar <davidperez@git.wordpress.org>
Co-authored-by: ernilambar <nilambar@git.wordpress.org>

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.

[ernilambar]

Suggested change

	* @since n.e.x.t.
	* @since 2.0.0

[ernilambar]

Suggested change

	* @since 1.0.0
	* @since 2.0.0