Struggling with config/execution on WordPress project

[EliW]

I've used Rector before without issue, but working on another project now and running into an issue (well multiple). Basically been down a circular path of "why this not working". So would love if there's something stupid I'm doing or a good workaround. Here's the story in short:

So being WordPress we have a number of plugins that we use that are ours and we want processed by Rector. But also there's a lot of libraries and other-other plugins that provide methods used by ours, etc.

So basically I started off with config that looked similar to this:

return RectorConfig::configure()
    ->withPaths([
        __DIR__ . '/wp-content/mu-plugins', // 👈 We will exclude 'vendor' below 👇
        __DIR__ . '/wp-content/plugins/COMPANY*', // 👈 Only care about 'our' plugins
        __DIR__ . '/wp-content/sites',
        __DIR__ . '/wp-content/themes/COMPANY*', // 👈 Only care about 'our' themes
    ])
    ->withSkip([
	// Separate one-off composer vendor folder that exists (not main one) that needs skipped
        __DIR__ . '/wp-content/mu-plugins/vendor',
	])
    ->withAutoloadPaths([
		// Pull in all libraries that aren't composer-installed & autoloaded already
		__DIR__ . '/wp-content/lib/Linkify',
		__DIR__ . '/wp-content/lib/mandrill',
		__DIR__ . '/wp-content/lib/Stripe',
		__DIR__ . '/wp-content/*.php',
                __DIR__ . '/wp-content/plugins',
		__DIR__ . '/wp', // 👈 Make sure it understands 'wp itself' which is installed in a sub-folder
    ])
    ....

So the initial problem(s) were that it was complaining about constants it couldn't find and was expecting. Right. So I had to end up adding in a bootstrap of wp-config.php ... but then It started to error out because it was actually attempting to make database connections. huh? Well turns out that our wp-config ends up doing a lot more than it should ... so I refactored out just the ENV vars to end up with something like this:

return RectorConfig::configure()
    ->withPaths([
        __DIR__ . '/wp-content/mu-plugins', // 👈 We will exclude 'vendor' below 👇
        __DIR__ . '/wp-content/plugins/COMPANY*', // 👈 Only care about 'our' plugins
        __DIR__ . '/wp-content/sites',
        __DIR__ . '/wp-content/themes/COMPANY*', // 👈 Only care about 'our' themes
    ])
    ->withSkip([
	// Separate one-off composer vendor folder that exists (not main one) that needs skipped
        __DIR__ . '/wp-content/mu-plugins/vendor',
	])
    ->withAutoloadPaths([
		// Pull in all libraries that aren't composer-installed & autoloaded already
		__DIR__ . '/wp-content/lib/Linkify',
		__DIR__ . '/wp-content/lib/mandrill',
		__DIR__ . '/wp-content/lib/Stripe',
		__DIR__ . '/wp-content/*.php',
                __DIR__ . '/wp-content/plugins',
		__DIR__ . '/wp', // 👈 Make sure it understands 'wp itself' which is installed in a sub-folder
    ])
    ->withBootstrapFiles([
	__DIR__ . '/wp-config-env.php',
    ])
    ....

OK that solved that problem, but then it was complaining that __() wasn't defined as it was looking at wp/wp-admin/includes/file.php ... odd because that's defined in the l10n.php file also under /wp/ which it should know about now, right? But decided that the best way to fix that was to do what I've done in the past with PHPstan and instead just use the php-stubs/wordpress-stubs package and then use that as a bootstrap, and not tell it to process stuff from wordpress itself ... so I ended up with this:

return RectorConfig::configure()
    ->withPaths([
        __DIR__ . '/wp-content/mu-plugins', // 👈 We will exclude 'vendor' below 👇
        __DIR__ . '/wp-content/plugins/COMPANY*', // 👈 Only care about 'our' plugins
        __DIR__ . '/wp-content/sites',
        __DIR__ . '/wp-content/themes/COMPANY*', // 👈 Only care about 'our' themes
    ])
    ->withSkip([
	// Separate one-off composer vendor folder that exists (not main one) that needs skipped
        __DIR__ . '/wp-content/mu-plugins/vendor',
    ])
    ->withAutoloadPaths([
		// Pull in all libraries that aren't composer-installed & autoloaded already
		__DIR__ . '/wp-content/lib/Linkify',
		__DIR__ . '/wp-content/lib/mandrill',
		__DIR__ . '/wp-content/lib/Stripe',
		__DIR__ . '/wp-content/*.php',
                __DIR__ . '/wp-content/plugins',
    ])
    ->withBootstrapFiles([
	__DIR__ . '/wp-config-env.php',
        __DIR__ . '/wp-content/lib/vendor/php-stubs/wordpress-stubs/wordpress-stubs.php',
    ])
    ....

And here is where things get extra frustrating. So that works, but then I get errors about methods from media.php being included again and functions from it defined that were already defined in the stubs file.... But I'm not telling it to process nor autoload anything from /wp/

But it turns out that a number of WP plugins end up hard-re-including core WP files, such as media.php. And when that happens obviously the stubs are a problem now because, redefined

So the solution is the just add a withSkip statement of /wp ... that goes great (as it were) ... and solves the problem. Except then for some reason it only actually processes 36 files in my repo.... instead of the ~1800 that it should be processing.

So long story long. I'm stuck trying to figure out how to get it to work ... wherein it either 'scans the WP files to understand any functions being declared in them' ... OR ... 'uses a bootstrap for that effect but then doesn't explode when those files are hard-included again'.

[samsonasik]

I suggest to only run on root project or when composer.json exists in the root rector.php located to avoid autoload juggling :)

Once you found a path that have its own composer.json, add rector.php there, and run from that path

[EliW]

Thanks for the answer @samsonasik ... unfortunately it doesn't quite address the direct issue here. The direct issue has nothing to do with 'lower folders' having their own composer or not.

But it had to do with a circular problem semi-unique to WordPress and a 'common practice' in WordPress. Let me attempt to explain since I've (mostly) figured this out now.

It all hinges on the fact that WordPress itself has 'some' autoloading, but a significant number of it's files are just hard-included during it's own bootstrapping instead.

Because of this, there are some files (such as media.php) that are typically hard-required when needed ... and often plugin authors for example will therefore end up doing just that with that file. But that's where the circular dependancies kinda happen here ... when you take into account that PHP Rector (unlike phpstan) actually executes (well, 'lets PHP create the inner executable format' via the engine) ... versus just 'scanning the file' ... and therefore, things like 'requires' end up executing.

Which means:

1. If you just use 'withAutoloadPaths' on the wordpress folders, it doesn't end up picking up on global function defines/calls. As WP is full of for backwards compatibility. And therefore when the code tries to call one of those, Rector complains "called undefined function"
2. If to solve that, you use the php-stubs/wordpress-stubs package which exists for that reason and is used just fine in PHPstan for example to declare all the functions as stubs.... Now when a later plugin goes to include media.php directly itself, with a require_once ... well PHP/Rector actually tries to do this. Because even though the functions created inside of the stubs file have already created the functions needed ... the actual media.php file hasn't been included yet. And so those functions will attempt to be redefined. Causing a PHP execution error.

Now, 'a' solution to (2) would just be to make sure that in your code if you are going to include a file that is declaring global functions. That you always check for one of those functions, and only include the file if it's NOT already defined. That works for your 'own' code, but when plugins/libraries you are using might be doing that ... well you can't guarantee that.

So the 'simpler' solution is just to fully bootstrap WordPress. While that sucks. It solves the problem.

[EliW]

Solution: The proper solution here is to not use any stubs files, but instead to fully bootstap WordPress. While that's a lot of overhead it's the only way to fully solve this issue ... via:

	->withBootstrapFiles([
		__DIR__ . '/wp/wp-load.php',
	])