> On Jul 5, 2024, at 1:47 PM, Michael Morris <[email protected]> wrote:
> I went to sleep thinking about this post, on import maps in general and how
> Composer works, specifically when you use a class map instead of the PSR-0 or
> PSR-4 schemes. In that mode, Composer does pretty much what I've described.
> This got me to thinking, could setting an import map be an alternative to
> setting an autoload function? Would having the PHP runtime load the file be
> faster than mucking with some userland code to do the same? And would the
> engine be able to do anything that can't be done in userland? I think so.
I very much like this direction of thought.
For context, when I worked with WordPress for about a decade I only ever used
only Composer for websites but never for my own plugins, and I almost never
used namespaces nor PSR-4 autoloaders for anything except when a plugin used
them. I almost exclusively used naming convensions for "namespacing" and
classmaps for autoloading.
Why? Was it because I was a "bad" programmer? No, it was because when in Rome,
you do as the Romans do. And also because when I tried to use Composer and
PSR-4 I was always fighting when them to do things in the way that worked best
for WordPress.
Or to use a more modern analogy to PHP and WordPress, even though you may be
landlocked by the country of Italy, if you are within the borders of Vatican
City you follow the laws and conventions of Vatican City when they conflict
with those of Italy.
> So first, I agree that supporting two formats, while convenient, increases
> the maintenance burden, so let's just go with ini. As far as the installing
> function - a better name is this.
Obviously I agree with having only one format, but not sure I concur with the
use of .ini. However, me debating against `.ini` would be me bikeshedding and
thus I will demure here.
> spl_autoload_map( string $filepath );
Adding an `spl_autoload_map()` function and feature really resonates with me.
As I said, I (almost?) always used class maps with WordPress so if I were to
build another WordPress site with a future PHP that made an
`spl_autoload_map()` available, I would TOTALLY use it.
<epiphany>
Reading this however caused me to ponder things certain people has said
recently — and many people have said for years on this list — and I think I am
recognizing something that I have always known but never put the pieces
together before.
Many (most?) people on PHP Internals view WordPress coding standards as bad and
some even view addressing WordPress developers needs as bad for PHP. And in
general I concur that those people are reasonably justified in their belief
WordPress' coding standards are not the standards that PHP developer who want
to do professional level software engineering should aspire.
And since many (most?) PHP Internals members generally do not experience the
issues that WordPress developers have they do not recognize that they are
issues; IOW, "out of sight, out of mind."
I also think some list members tend to dismiss WordPress developers pains as
unimportant and/or think that addressing those pains have will harm PHP.
(BTW, I recently had a dialog off-list with someone who wrote in an email that
"Wordpress is an exception, but nobody these days treats WordPress as a valid
example to do anything. It is an ancient piece of legacy code that has no
bearing on modern situation and it's their problem to deal with." So I am not
just erecting a straw man here.)
But I think what most may not consciously recognize is that WordPress is a
different type of web app than an app build using Symfony or Laravel and
deployed by its developers, or by some other professional developer.
WordPress differs from the apps many (most?) developers on PHP Internals work
with in the following way:
WordPress = User-managed app
Most = Developer-managed apps
In a Developer-Managed app developers choose which 3rd party functionality will
be incorporated into their sites whereas with a User-managed app users choose
which 3rd party functionality will be incorporated into their site. And that is
the KEY difference.
So I am wondering if we can get people on this PHP Internals list who dismiss
the needs of WordPress developer BECAUSE it is WordPress to recognize that
User-Managed apps ARE a class of PHP applications have needs that deserve to be
addressed?
Two (2) unmet needs of User-Managed apps that "standard" PHP currently does not
address come to mind:
User-managed apps needs to be able to handle both:
1. User-added add-ons ("plugins" in WordPress, "modules" in Drupal) that have
conflicting dependencies, and
2. Add-on directory structures that do not follow a PSR-4 directory hierarchy.
As for #2, even if those apps could rearchitect their existing directory
structure they cannot realistically be expected to do with because of the huge
BC issues their users would experience.
And newly created User-managed apps may still find that a PSR-4 directory
structure is not in the best interest of their project or their users. To
elaborate, PSR-4 generally assumes that ALL code goes into ONE hierarchy and
that any and all code that will be autoload gets placed in that hierarchy.
But with add-ons it makes a lot more sense to have the entire add-on contained
in its own add-on directory. This is exactly where PSR-4 breaks down with
respect to User-managed apps.
Sure, you can have multiple PSR-4 autoloader root directories, but that does
not scale well to websites with a large number of add-ons as many WordPress
sites I worked on used. Some had over 100 plugins. With a hierarchy of
autoloader maps that Michael Morris is proposing WordPress could collect up all
the maps and create one map every time a plugin is added, updated or deleted.
</epiphany>
Based on my above labeled epiphany, I think MOST of what you recently proposed
could address those unmet needs of User-managed apps written in PHP, with a few
caveats and improvements. Read on.
> ; A path fragment can be used, in which case PSR-4 will be used to map the
> rest of the symbol to the filename.
> ; Pay attention to the direction of the slash at the tail - if the symbol
> key has this the value MUST also have this.
> B/ = './path/to/B/'
It is not clear to me what a trailing slash means, and especially why it is
needed on the left-hand side? And why slash here when namespaces use backslash?
Also, as someone raised on DOS and then Windows only "converting" in 2009, I
still get confused in *nix when to use a trailing slash and when to not, so
this trailing slash worries me, if only for that reason alone.
> ; A package is declared with a @ and maps the package namespace to its
> autoload file.
> ; If the package name here doesn't match what the package calls itself then
> the symbol
> ; given here takes precedence, acting as an alias.
> @C = './path/to/C/autoload.ini'
Using the `@` here feels cryptic, and hard to discover and remember.
I think this would be infinitely easier to follow if packages were just
included in a `[packages]` section.
Your comments also confuse me a bit.
Is this saying that your hypothetical app — which you stated this `.ini` file
is for — needs to use a package named `C` use "definition" is located at
'./path/to/C/autoload.ini' then it would use this syntax, and that in the app
its components would be accessed at namespace `\C`?
And I were to have:
@Foo\Bar\Baz = './path/to/Foo/Bar/Baz/autoload.ini'
Then in the app its components would be accessed at namespace `\Foo\Bar\Baz`?
I think if your examples used hypothetical "real-world" symbols it would be
easier to follow than A, B, C, D, etc.
> ; An import into a package can be done like so
> ; Twig will load into \C\Twig and that use will need to be used by any code
> outside the C package.
> @C\Twig/ = './path/to/Twig/'
>
> ; The same library can be loaded into a different package, but a symbolic
> link is used internally in the engine to optimize
> @D\Twig/ = './path/to/Twig/'
>
> ; Nothing stops a different package from loading a different version now.
> @E\Twig/ = './path/to/Twig/Version4/'
Okay, this makes sense. OTOH, this is the part that of your proposal that is
incomplete for the needs of User-managed apps IMO.
I think you are implying a necessary "best practice" that whenever any PHP
library, or package would include code they would need to prefix the namespace
of package when importing it and then when using it. Given an org named ACME
that released a library called Widgets then if it were to use Twig it should
import and use Twig like this (did I understand your intent correctly?):
@ACME\Widgets\Twig/ = './path/to/Twig/'
And in PHP code?:
use \ACME\Widgets\Twig;
I think that would work well for newer libraries and packages authored and used
by developers of Developer-managed apps. OTOH I do not think it would be
sufficient for any existing libraries or frameworks, nor for non-professional
developers scratching their own itch on a User-managed apps and then deciding
to publish it for others to use (which happens a lot with User-managed apps.)
The problem would be that most (all?) of those would not be namespace-prefixing
Twig but instead using it directly. I believe you need an ADDITIONAL `replace`
sectionS that allowed an app/website developer to indicate that namespace A
should instead be replaced in `use` statements and direct references with `B\A`
for code that exists in directory(s) `C` but not in directories `C\D` where `C`
and `D` can be globs.
To illustrate I created a completely hypothetical `.ini` that the WordPress
plugin admin page could create any time a user would install WordPress and any
time the user would add/edit/delete plugins or themes (I did try to modifying
your A/B/C example but couldn't come up with anything that could illustrate the
use-case):
[default]
root = '/wp-content/'
[includes]
UpdraftPlus = './plugins/updraft-plus/index.php' # Uses Twig v4
Automattic\JetPack = './plugins/jetpack/jetpack.php' # Uses Twig
Elementor = './plugins/elementor/elementor.php' # Uses Twig v4
[packages]
Yoast\SEO = './plugins/yoast-seo/autoload.ini' # Uses Twig v4 as Yoast\Twig
WPForms = './plugins/wp-forms/autoload.ini' # Uses Twig as WPForms\Twig
[replace]
Twig[UpdraftPlus] = 'Twig_edaf27eb'
Twig[Elementor] = 'Twig_edaf27eb'
In the above example `[packages]` are ones that have gotten religion and have
delivered a best-practices package where they have namespaced Twig. We can
ignore them for now as they follow your best-practices.
The `[includes]` are ones that have paid no attention to newer best practice
and/or simply have not been updated by their authors. They were implemented to
load and use Twig as simply `\Twig`.
The `[replace]` section tells PHP that when `\Twig` is found included or used
within the `[includes]` files denoted by those namespaces referenced such as
`UpdraftPlus` it should instead use the namespace of `\Twig_edaf27eb`
(dynamically generated by WordPress), and the same goes for any includes and
uses by `Elementor`.
My hypothetical design may not survive a fully-working implementation, but I
hope it illustrates that we need to:
1.) Handle those who are NOT following best practices, AND
2.) Alias namespaces when used IN ADDITION TO when imported.
Of course if the code in any of the three plugins included expect the
namespaces to be exact via reflection then they would break, but I think it
would be a reasonable breakage as most plugins won't do this and most plugins
that break could either be updated by their authors or disabled for installs on
newer PHP by the WordPress plugin repo.
BTW, Go uses `replace` in `go.mod` albeit as a compiled language its use is not
a one-to-one analogue to the example above. If you are interested in seeing
them in the wild here is what the use of `replace` looks like for Kubernetes:
https://github.com/kubernetes/kubernetes/blob/master/go.mod#L227-L258
As an "optimization", WordPress could recognize that Twig and Twig4 are being
used not only by the includes but also by the packages and could generate this
optimization instead:
[default]
root = '/wp-content/'
[includes]
UpdraftPlus = './plugins/updraft-plus/index.php' # Uses Twig v4
Automattic\JetPack = './plugins/jetpack/jetpack.php' # Uses Twig
Elementor = './plugins/elementor/elementor.php' # Uses Twig v4
[packages]
Yoast\SEO = './plugins/yoast-seo/autoload.ini' # Uses Twig v4 as Yoast\Twig
WPForms = './plugins/wp-forms/autoload.ini' # Uses Twig as WPForms\Twig
[replace]
Twig[UpdraftPlus] = 'Twig_edaf27eb'
Twig[Elementor] = 'Twig_edaf27eb'
Twig[Yoast\SEO] = 'Twig_edaf27eb'
Twig[Automattic\JetPack] = 'Twig_2ba3f91f'
Twig[WPForms] = 'Twig_2ba3f91f'
As a further optimization, WordPress could reach into all the `.ini` files
recursively and create a SINGLE autoload map, but to do that we would need an
additional section: `[ignore]`:
[ignore]
Yoast\SEO = './plugins/yoast-seo/autoload.ini'
WPForms = './plugins/wp-forms/autoload.ini'
The above assumes that WordPress already generated everything that was needed
to no longer need to load the autoload.ini files for either the `Yoast\SEO` or
`WPForms` namespaces and thus the ignore tells `spl_autoload_map()` to ignore
any calls to these `autoload.ini` files if called later. (I would have created
a complete example but at this point I am too tired for that.)
And lastly, because WordPress would need to generate this and having a web app
write to a file is a modern security no-no, then `spl_autoload_map()` should
accept multiple different valid values:
spl_autoload_map( string|array|\PHP\AutoloadMap $map);
1. String would be the `.ini` file path
2. Array would be the format returned by parse_ini_file() for parsing an
applicable `.ini` file
3. \PHP\AutoloadMap could be a new class containing the required values in
object format. (Hopefully adding such a class as a third option would not be
controversial to the list members who criticize those developers still wanting
to use arrays as hash maps?)
And that is about it for my feedback today.
-Mike
