Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/johnbillion/wp-compat
PHPStan extension to help verify that your plugin or theme remains compatible with its minimum supported version of WordPress
https://github.com/johnbillion/wp-compat
phpstan phpstan-extension wordpress
Last synced: 19 days ago
JSON representation
PHPStan extension to help verify that your plugin or theme remains compatible with its minimum supported version of WordPress
- Host: GitHub
- URL: https://github.com/johnbillion/wp-compat
- Owner: johnbillion
- License: mit
- Created: 2024-09-03T20:31:38.000Z (4 months ago)
- Default Branch: trunk
- Last Pushed: 2024-11-30T19:34:05.000Z (about 1 month ago)
- Last Synced: 2024-12-16T11:13:27.493Z (23 days ago)
- Topics: phpstan, phpstan-extension, wordpress
- Language: PHP
- Homepage:
- Size: 549 KB
- Stars: 20
- Watchers: 3
- Forks: 1
- Open Issues: 2
-
Metadata Files:
- Readme: readme.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
# WPCompat
WPCompat is a PHPStan extension which helps verify that your PHP code is compatible with a given version of WordPress. You can use it to help ensure that your plugin or theme remains compatible with its "Requires at least" version.
It works by checking that the declared `@since` version of any WordPress functions or class methods that are in use is lower than or equal to the minimum version of WordPress that your code supports. For example, if your plugin or theme supports WordPress 6.0 or higher but the `get_template_hierarchy()` function is used unconditionally, the extension will trigger an error because that function was only introduced in WordPress 6.1.
If your code is correctly guarded with a valid `function_exists()` or `method_exists()` check then an error won't be triggered.
## Status
WPCompat is a relatively new extension and may not yet be exhaustive in its checks.
Version information for functions and methods was last updated for WordPress 6.7.
## Requirements
* PHPStan 2.0 or higher
* PHP 7.4 or higher (tested up to PHP 8.4)
## Installation
```shell
composer require --dev johnbillion/wp-compat
```
If you also install [phpstan/extension-installer](https://github.com/phpstan/extension-installer) then you're all set!
Manual installation
If you don't want to use `phpstan/extension-installer`, include extension.neon in your project's PHPStan config:
```neon
includes:
- vendor/johnbillion/wp-compat/extension.neon
```
## Configuration
### Themes
If your style.css file contains a "Requires at least" header then wp-compat will read this header and use its value as the minimum supported WordPress version. There is no need for any additional config.
### Plugins
If the name of your main plugin file matches its parent directory -- for example `my-plugin/my-plugin.php` -- then wp-compat will read the "Requires at least" header from this file and use its value as the minimum supported WordPress version. There is no need for any additional config.
If your main plugin file is named otherwise or located elsewhere, you can specify its name in your PHPStan config file:
```neon
parameters:
WPCompat:
pluginFile: my-plugin.php
```
### Manual config
Alternatively you can specify the minimum supported WordPress version number of your plugin or theme directly in your PHPStan config file. Note that this must be a string so it must be wrapped in quote marks.
```neon
parameters:
WPCompat:
requiresAtLeast: '6.0'
```
Any version number in `major.minor` or `major.minor.patch` format is accepted.
## Ignoring errors
You can ignore an error from this extension by using its error identifiers. For full information, see [the PHPStan guide to ignoring errors](https://phpstan.org/user-guide/ignoring-errors).
```php
// @phpstan-ignore WPCompat.functionNotAvailable
wp_foo();
// @phpstan-ignore WPCompat.methodNotAvailable
WP::foo();
```
## Technical details
This extension does not scan your project in order to detect the `@since` versions of WordPress functions and methods. This information is included in the [symbols.json](symbols.json) file that's included in the extension. This approach ensures that your code is always tested against the most up to date and most accurate `@since` documentation, regardless of the version of WordPress that your tests are using.
The [symbols.json](symbols.json) file contains a dictionary of all functions and methods in WordPress along with the version of WordPress in which they were introduced.
The file can be regenerated by running:
```shell
composer generate
```
The JSON schema for the file can be found in [schemas/symbols.json](schemas/symbols.json).
## License
MIT