inpsyde/wp-stubs

WordPress Stubs

dev-main 2024-10-31 12:58 UTC

Requires (Dev)

• php: ^8
• php-stubs/generator: ^v0.8.1
• symfony/process: ^5

MIT

• Syde GmbH

README

This repo contains auto-generated WordPress stubs to be used with static analysis tools.

FAQ

• Why this instead of "< insert exiting project here >"?

This project's purpose is:

• having multiple versions of WP in the same branch/version
• not having stubs for globals, but having stubs for constants
• having a super-simple "override" method. By declaring stubs in the fixtures.php file, it is possible to override the WordPress declaration for functions, classes, and interfaces. That way, it is easy to fix incorrect DocBlocks in WordPress and use "advanced" doc block supported by static analyzers (think of array shape, type aliases, conditional return types …)

How this works

Every day, a GitHub Actions workflow calls the wp.org API to find new WordPress versions.

If it finds new versions, it generates and saves stubs for them (using https://github.com/php-stubs/generator) while also updating the "latest" stub.

How to use

The primary usage is for static analysis tools, for example, Psalm:

Method 1: Get all WordPress versions

Steps:

1. Require this project (inpsyde/wp-stubs) in your Composer's "require-dev" property
2. Create a psalm.xml config file (see docs)
3. In the Psalm configuration, add these lines:

   <stubs>
       <file name="vendor/inpsyde/wp-stubs/stubs/latest.php"/>
   </stubs>

You can replace latest.php with a specific WP version. See the available versions in the /stubs directory.

Note: In that folder, a two-digit version number like 5.9 does not necessarily mean WordPress version 5.9, but the latest in the 5.9.* series. So if you use Composer to require WordPress and have a requirement like 5.9.*, using the stubs/5.9.php stubs file will match the currently installed version.

The "stubs" folder contains stubs of many versions so that you can choose, but it would also be possible to have a CI script that loads different versions to test against different stubs.

However, the package size might get huge, and if not excluded from IDE's analysis, it might affect the IDE performance.

Method 2: Get a specific version

Pre-requisite:

In your composer.json, declare a repository like this:

{
  "repositories": [
    {
      "type": "composer",
      "url": "https://raw.githubusercontent.com/inpsyde/wp-stubs/main",
      "only": [
        "inpsyde/wp-stubs-versions"
      ]
    }
  ]
}

Note for Inpsyde developers: The Inpsyde organization in Private Packagist mirrors the above repository, so for Inpsyde's private repositories, this is likely not needed considering Private Packagist will probably be already added to the repo's composer.json.

Steps:

1. Require the "versioned" project in your Composer's "require-dev" property e.g. { "require": { "inpsyde/wp-stubs-versions": "dev-latest" } }. (Note how the package name has -versions appended)
2. Create a psalm.xml config file ( see docs)
3. In the Psalm configuration, add these lines:

   <stubs>
       <file name="vendor/inpsyde/wp-stubs-versions/latest.php"/>
   </stubs>

Using this approach, the latest version will be the only version Composer downloads.

Minimum requirements

The code that generates the stubs requires PHP 8.0+. However, when consuming the package, there are no minimum requirements besides being able to run WordPress.

License

This repository is a free software, and is released under the terms of the MIT license. See LICENSE for complete license.