search

AxeWP / wp-graphql-stubs

Provides stub declarations for WPGraphQL core functions, classes and interfaces.
MIT License
7 stars 1 forks source link

What stubs are for #2

Closed szepeviktor closed 1 year ago

szepeviktor commented 1 year ago

WordPress core stubs exist because its source code is an undecipherable mess.

Does WPGraphQL have any side-effects beside clean classes and functions? AFAIK: no.

justlevine commented 1 year ago

Hey @szepeviktor , the main use case I've experienced with stubs in general is being able to develop plugin extensions in isolated environments. I find it a lot more rebust to have my ide/php intelephense/local phpstan/ci linters to statically analyze a composer-installed stubfile, then to have to include the actual source plugin in a composer dep and/or mock an actual WordPress install. It's also significantly faster to bootstrap/scanFiles the stubfile than an entire project folder.

I'm assuming similar logic is why stub projects exist for other ecosystem-type WP Plugins, like wc, acf, polylang, (soon to be) GF, etc. 😇

szepeviktor commented 1 year ago

statically analyze a composer-installed stubfile,

WPGraphQL is also available as a package 🚀 you can add it as a devdep!

https://github.com/wp-graphql/wp-graphql/blob/34f9c76fb2617798510462779b8eda7080c8d777/composer.json#L2

szepeviktor commented 1 year ago

I'm assuming similar logic is why stub projects exist for other ecosystem-type WP Plugins, like wc, acf, polylang, (soon to be) GF, etc. 😇

Noooooooooooooo! A normal package needs no stubs.

justlevine commented 1 year ago

Noooooooooooooo! A normal package needs no stubs.

There's no denying that between the two of us, you're the expert on using stubs, but can you please elaborate a bit, or point me to a good resource on when to use stubs vs when to not?

WPGraphQL is also available as a package 🚀 you can add it as a devdep!

If I was working alone, or on only one WPGraphQL extension, I could possibly make that work, but IRL I run into major problems for my current workflows

Here's two real-world workflows where I depend on php stubs (and this particular package):

  1. Isolated development E.g. you've got your plugins in a separate \projects dir, and then ln them into your WP plugins directory. In this case installing the plugin as a composer dev-dep could work, but that assumes that no other plugins you're actively developing are also using ( a possible different version of) WPGraphQL in their own dev-deps, causing conflicts.

  2. Developing in the plugins directory. This is bad for the same reason as (1), but also is problematic if you also have WPGraphQL installed directly as a plugin (e.g. if you're a contributor).

  3. Projects with a lot of 3rd party plugin integrations. E.g. my custom site plugin add WPGraphQL data from over a dozen 3rd-party plugins. Every single one of those plugins (including WPGraphQL) that I can load into PHPStan as a single-file php stub, instead of including in the scanDirectories, shaves the lint time exponentially!

If you have a better recommendation than autogenerating a php-stub for the above use cases, I'd love to hear it 🙏

szepeviktor commented 1 year ago

good resource on when to use stubs vs when to not?

There are two situations when you need stubs.

  1. https://phpstan.org/user-guide/stub-files for overriding messy code - we do this with WP core stubs
  2. enable autocomplete functionality in your IDE - I do not use an IDE :(

Once I've met a guy who told me he prefers stubs of normal OOP code because it is smaller in size. I do not know what to do with that. (even a smartphone has gigabytes)

szepeviktor commented 1 year ago

1. 2.

You can have the WPGraphQL package in vendor/ as dead code. Not running. Not being a WP plugin. Just for static analysis and IDE autocomplete. Composer can be configured to do that.

3.

PHPStan has cache! :) From the second run it is very fast. 🛩ī¸

justlevine commented 1 year ago

You can have the WPGraphQL package in vendor/ as dead code. Not running. Not being a WP plugin. Just for static analysis and IDE autocomplete. Composer can be configured to do that.

Thanks for the suggestion, I wasnt aware of this. 👀

PHPStan has cache! :) From the second run it is very fast. 🛩ī¸

Sure, but that first run is still problematic. Especially for the precious pay-per-use on some of my CIs 😏

enable autocomplete functionality in your IDE - I do not use an IDE :(

This is a major use case for me too. Especially when onboarding new developers. But if it can be just be some dead vendor code, we can solve that.

szepeviktor commented 1 year ago

for the precious pay-per-use on some of my CIs 😏

CIs also have cache 😉

justlevine commented 1 year ago

Hey @szepeviktor After a lot of thought (almost a year!) I'm closing this issue and keeping the repo active.

I'm continuing to find that including a stubfile (vs requiring and scanning the entire wp-graphql codebase) is a significant DX improvement for myself and those I collab with on WPGraphQL work (smaller dep install, reduced memory usage with IDEs/intellesense, faster -first and even subsequent- phpstan runs, easier min-version bumping, and fewer potential PHP conflicts in weird autoloading/composer setups). Ultimately it's just a lot easier to add a stubfile than to ensure various repo configs / local dev envs / CIs are setup correctly without being super opinionated.

End of the day, no one is being forced to include this dep in their own projects, and if it helps someone else avoid the issues I've come across collaborating with other devs in the WPGraphQL ecosystem, even better :-)