Setting the Requires at least header in your WordPress plugin is a critical step in the development lifecycle. This metadata tells the WordPress Plugin Directory—and the user's site—which version of WordPress is the bare minimum required to run your code safely. If you set this version too low, you risk causing fatal errors on older sites; if you set it too high, you unnecessarily limit your potential user base.

Manually checking every function call, hook, and class instantiation against the WordPress core documentation is a tedious and error-prone process. Fortunately, there are ways to automate this discovery process, ensuring your plugin remains stable across different environments. In this guide, we will explore how to identify the minimum version requirements for your WordPress plugin using automated tools and historical reference databases.

Why the "Requires at least" Header is Critical

Every time you use a core function like wp_body_open() (introduced in WP 5.2) or a class like WP_Post_Type (introduced in WP 4.6), you are effectively raising the minimum version requirement of your plugin. If a user runs your plugin on WordPress 4.5, the site will crash because those functions do not exist.

Automating the detection of these requirements prevents human error. Instead of guessing or relying on memory, you can use scripts to scan your codebase and compare your function calls against the @since tags found in the WordPress core source code.

Automated Tools for Version Detection

One of the most efficient ways to handle this is through automated services designed specifically for WordPress developers. A standout tool in this space is the WPSeek Plugin File Check.

This service allows you to upload your plugin files or input your code to receive a comprehensive report. It performs the following actions automatically:

  1. Scans all files: It looks through your PHP files for function calls and class usage.
  2. Cross-references WP Core: It compares your code against a database of WordPress functions and the versions in which they were introduced.
  3. Generates a Report: It provides a list of every core function used and the specific version it was added to the core.
  4. Suggests Headers: Based on the results, it suggests the appropriate Requires at least value for your plugin header.

Using a service like this saves hours of manual auditing and provides a high level of confidence before you push an update to the repository.

Using Historical Hook and Function Lists

If you prefer to perform a manual audit or are building your own internal scanner, historical databases are invaluable. While the official WordPress Developer Resources are the gold standard, some community-maintained lists provide a more bird's-eye view of versioning.

Adam Brown’s Hook List

Adam Brown’s Hook List is a legendary resource in the WordPress community. It tracks every hook (actions and filters) introduced throughout the history of WordPress, dating back to version 1.2.1. If your plugin relies heavily on specific hooks, this list is an excellent way to see exactly when those hooks were integrated into the core.

Ozh’s Function Reference

Similarly, Ozh’s list provides a clear breakdown of functions added or removed across various versions. While some historical lists may only cover up to specific versions (like 3.0 or 4.0), they serve as a baseline for developers who are trying to maintain backward compatibility with very old versions of WordPress.

Building a Custom Compatibility Scanner

For developers who want to integrate this check into a CI/CD pipeline, you can write a script to automate the detection logic. The logic follows a predictable pattern:

  1. Parse the Code: Use a library or regex to identify function calls and class instantiations. You are looking for patterns like:

    • new foo( [...] ) (Class instantiation)
    • foo::bar( [...] ) (Static method calls)
    • bar( [...] ) (Standard function calls)
    • call_user_func( 'bar', [...] ) (Dynamic calls)

  2. Extract @since Tags: Scan the WordPress core source code to extract the @since phpDoc tags for every function and class. This creates a map of function_name => version_added.

  3. Compare and Report: Compare the list of functions used in your plugin against the version map. The "minimum version" is the highest version number found in your list of functions.

Modern Alternatives: PHPCompatibilityWP

In the modern development era, many developers use PHP_CodeSniffer to maintain code quality. You can use the PHPCompatibilityWP standard to check for both PHP version compatibility and WordPress version compatibility.

To use this, you would typically install it via Composer:

composer require --dev phpcompatibility/phpcompatibility-wp

You can then run a scan that targets a specific minimum version of WordPress to see if your code uses any functions that were not yet available in that version. This is particularly useful for preventing the use of "too new" features while maintaining a specific support floor.

Frequently Asked Questions

What happens if I set the "Requires at least" version incorrectly?

If you set it too low, users on older versions of WordPress will be able to install the plugin, but they will likely encounter "Fatal Error: Call to undefined function" messages, which can take down their entire site. If you set it too high, you are essentially hiding your plugin from users who might otherwise be able to use it safely.

Should I always support the oldest possible version of WordPress?

Generally, no. Most developers follow the lead of WordPress core, which recommends supporting a few versions back. Currently, supporting the last 2-3 major releases is standard. However, if your plugin uses modern features like the Block Editor (Gutenberg), your minimum version will naturally be much higher (WP 5.0+).

Can I use polyfills to lower my required version?

Yes. If you want to use a function introduced in WP 5.5 but want to support WP 5.0, you can wrap your function call in a function_exists() check and provide a custom fallback (polyfill). However, this increases the complexity of your codebase.

Wrapping Up

Determining the minimum WordPress version for your plugin doesn't have to be a guessing game. By using automated tools like WPSeek, referencing Adam Brown’s Hook List, or implementing modern linting tools like PHPCompatibilityWP, you can ensure your plugin is both stable and accessible. Accurate versioning builds trust with your users and reduces the number of support tickets related to fatal errors on legacy systems.

Always remember to re-run these checks whenever you introduce a new core function or library into your plugin's architecture.