Questions, and thoughts... #852
Replies: 10 comments 14 replies
-
P.P.S#526 Might be a great step towards folks like me having a place to step in, learn about what's going on, and improve overall project communication. |
Beta Was this translation helpful? Give feedback.
-
|
Strongly agreed! I'd like to kickoff these meetings next year. |
Beta Was this translation helpful? Give feedback.
-
|
Thank you so much for starting this discussion, @moonmeister! Let me answer in separate comments as best as I can.
Could you elaborate on what do you mean by "that's not part of the core"? I consider |
Beta Was this translation helpful? Give feedback.
-
|
Core being everything in this repo. My interface isn't part of that. |
Beta Was this translation helpful? Give feedback.
-
This is an excellent question! And there isn't a simple answer to that. I think of most APIs that exists today as unstable. While some APIs have proved to be useful in a few projects already and I don't anticipate large changes, I am intentionally not marking them as stable yet. One reason is that major API-related opportunities still come up every month. Just last week I started exploring Stream-based file handling that will speed up the loading time of plugins and enable partial downloads (e.g. just the relevant 5MB from a 300MB zip file). As a result, the That being said, I would like to explore a road to stability at one point in 2024. Since Blueprints are the way to setup Playground sites, I started the Blueprints Maturity issue to track that. I also wonder what will |
Beta Was this translation helpful? Give feedback.
-
|
Thanks for the good info. I think the |
Beta Was this translation helpful? Give feedback.
-
As a baseline, I'd like Playground to do reasonably well in these areas:
In addition, I want to have some confidence that Playground implements the right APIs. One way to know that is to ship Playground-based tools like:
These projects are not meant as feature creep, but as ways to test the practical usefulness of the Playground API, identify any roadblocks, push the limits, and gain confidence. Ideally, the public API would be well–tested and well–documented by the time a 1.0 release is announced. I want the Note how nothing here is super specific. It will likely take some months to get there, and that's okay. I'd rather move slowly here and get the API reasonably right. I'm worried that expediting a stable 1.0 release would almost certainly mean missing important use-cases and having difficulties supporting them later. It's all quite similar to the |
Beta Was this translation helpful? Give feedback.
-
That would be a great client feature, would you like to open an issue to track it or perhaps even explore an implementation?
This is indeed challenging. Do you have any ideas on how this could be addressed better than it is now? One idea that comes to my mind is self-hosting, but perhaps there is something that the "official" build could do.
That's a good note and I'd like the documentation to draw the distinction line more clearly. Separating |
Beta Was this translation helpful? Give feedback.
-
|
Yeah, this gets into the previous questions concerning versioning of the re: two separate projects. As a practical step, I wonder if it'd be beneficial to move the deployment of the playground UI to a repo apart from the core tech as you've done with the other playground tools. Potentially having this on a separate domain would make this even clearer. e.g. you have an issue about making |
Beta Was this translation helpful? Give feedback.
-
A-ha! Just to confirm I understand your thinking here – the client would know its own version, the endpoint would know its own version, and if the endpoint version >= client version, the endpoint would degrade the protocol version to make the client happy? |
Beta Was this translation helpful? Give feedback.
-
The larger issue is the strong coupling between the protocol, the PHP build, and the WordPress build within remote.html. A specific "version" consists not just of remote.html, but also of a bunch of static files. Technically they could all be shipped on the same domain, though, using paths to distinguish between the different versions. This opens other though, like how many past versions should be kept? Should they be maintained and patched, or just hosted for convenience? Edit: Actually I might have misunderstood. I think you meant splitting the |
Beta Was this translation helpful? Give feedback.
-
This would be possible...but a JSON file that lists all the versions would work too. |
Beta Was this translation helpful? Give feedback.
-
php-wasm is distinct and separate from WordPress Playground. The Node.js version can be used by just importing the package and the entire state lives in the process memory. The browser version, however, needs to deal with page reloads – otherwise clicking a link will reload the page and wipe out any in-memory state you might have had there. This is why the docs recommend rendering the PHP output in an iframe – so that you can both use links and keep the same browser tab open with all its state. Is that helpful? I'm happy to discuss more – I know it can be confusing.
Let me flip this question around – why is the presence of an iframe challenging in your case?
These are the same – the package with the name |
Beta Was this translation helpful? Give feedback.
-
My issue is currently related to the browser state inside the
It's very strange that I have access to all the same functions from the package that I do from the object |
Beta Was this translation helpful? Give feedback.
-
The iframe is what makes Playground possible. You could load all the Playground libraries on your domain and run in in a "headless" mode, but that would be convenient only until the first time you need to display the WordPress HTTP response. Without an iframe, you'll have issues with:
And these are just the most prominent ones. Perhaps a conditional
As in the intermittent UI state, input values in forms, and expanded panels? That isn't Playground–specific, you'd just have to somehow serialize the application state and restore it later. Or as in the Playground database and files, including installed plugins and created pages? You could use the ZIP export API, e.g. using the import { zipWpContent } from '@wp-playground/client';
const bytes = await zipWpContent(playground, {
selfContained: true,
});
const file = new File([bytes], 'wordpress-playground.zip');
// Save in local storage or anywhere else
// Restore later on as follows:
import { importWordPressFiles } from '@wp-playground/client';
await importWordPressFiles(playground, { wordPressFilesZip: file });
Correct, although you could bind it to browser's OPFS and it would store each "file write" and "database write" live. There isn't much documentation about that yet, but you could dive into how the "browser" storage mode works as a reference.
Which specific parts are you referring to?
There are two reasons for not using a constructor:
The client isn't, but the API endpoint is – as in it acts on the WASM state.
You can run multiple Playground instances. This demo does that. |
Beta Was this translation helpful? Give feedback.
-
I'd love to hear more about this. The documentation may be blurrying the line, but the UI is clearly separated from the |
Beta Was this translation helpful? Give feedback.
-
|
I think it goes back to things like the supported WP/PHP versions. Because it's in the same repo you just do this all at once and it's not a big deal. Anyone in an outside repo/org is left to manually check when you update support and then manually update their version switchers. This extends to feature support for the client. I'm starting to think the NPM package needs to be more like a wrapper that chats with a The other aspect of this is what features should be part of the API client vs Playground UI? I don't have an answer but, as an example, I wonder if the client could handle version switching (e.g. getVersions/getCurrentVersion/setVersion)? Right now all clients have to implement this state management and logic themselves. Having this implemented in the client couple make things easier. This may also extend to browser storage and other things. Maybe is there room for a storage hook in the client? and core provides some defaults like none, session, and permanent. but then I could write my own to save the state to a cloud service. All just ideas but this goes back to the theme of these two halves possibly being too tightly coupled. As an example of where this is done fairly well is the URL. You have a simple way to set what the default URL is, get an updated URL when it changes, and load a new UR. It's really easy to use these to implement my own UI around a URL bar or some other nav thingy. It seems like this ease could be extended to PHP version, WP version, plugins, themes, and more. |
Beta Was this translation helpful? Give feedback.
-
Website is a separate package. Sure, it's versioned in this repo, but that doesn't mean it has access to more information than a package that would be versioned externally. The WordPress and PHP versions are not hardcoded. There are APIs you can use to populate your version switchers in the same way as the Playground website does: playground.getSupportedWordPressVersions().then(({ all, latest }) => {
console.log({ all, latest });
});
import {
LatestSupportedPHPVersion,
SupportedPHPVersionsList,
} from '@php-wasm/universal';Eventually, the PHP versions will also be exposed from the client and not as a package export.
The Playground client is exactly this kind of wrapper. It's a Comlink proxy object that uses a specific
Good point! This is likely to happen, it's just not there yet. When it comes to developer time spent on Playground maintenance, there's much more demand than supply :-)
That would indeed be cool. I intentionally started developing some of these features in the website to let them mature before exposing them as a public API. With things like setting a PHP version, we're quite close. With things like OPFS, we're not quite there yet. |
Beta Was this translation helpful? Give feedback.
-
This discussion, any issues you can create, and anything you can share on the meta-playground channels are all great ways to inform the development here. Thank you so much for taking the time to do that! The Playground team isn't large, but it's slowly growing and this should generate additional momentum in the medium term. Unfortunately, crucial core features like PHP.wasm stability aren't straightforward to start contributing to. What would be extremely useful, though, is improving the documentation and the test coverage – both unit and E2E. Both would have large impact on Playground's success. Other than that, any issue or friction point you identify in Playground when you're working with it is a great opportunity to contribute and help improve Playground for others. |
Beta Was this translation helpful? Give feedback.
-
|
I think I'm understanding some things after this chat and some more code exploration and why this has all been confusing. I've even got some ideas for simplification if I'm remotely accurate. But also this might be just revealing how little I understand what's happening. So currently Next, remember my comment above about confusion around the client returning itself? I think this is why. I expect my JS client to be doing all the work that the
ConclusionRemember when I said the lines were blurred between Thanks again for reading and responding @adamziel! |
Beta Was this translation helpful? Give feedback.
-
|
Additional note: After diving in more. Looks like some work would need to be done with the php-wasm-web package so it's not directly importing the wasm/js bundles for the various versions of PHP from the file system. |
Beta Was this translation helpful? Give feedback.
-
All of that sounds accurate 👍
Where would the service worker be registered if remote.html didn't exist? The consumer's site could do that on its own by hosting
Initially it did, but then I got a ton of feedback on how inconvenient that was to set up. You can still use those (underdocumented) hooks, e.g. via
Loading static assets from another domain opens an entire rabbit hole of CORS issues, the largest being Privacy Sandbox. It would be nice to support that one day, but today improving stability is much more important.
Versioning those artifacts was the fastest way to tie them to specific versions of the source code for debugging and rolling back, while also having them instantly available after cloning the repo. I only see three drawbacks:
I'd still move them to GitHub releases if I knew an easy way to do that while maintaining the benefits
I'm not sure I follow. The client npm package provides you with a client library. What do you mean by "exposes another client"?
That's an interesting idea! How would you use those hooks and filters? |
Beta Was this translation helpful? Give feedback.
-
|
The cool thing about hosting all those static assets separately is we could create a static json file that gets deployed on build with all versions of assets. The client loads that JSON and immediately knows which PHP and WP binaries are available to it and if those are compatible with its consumed API version.
|
Beta Was this translation helpful? Give feedback.
-
What would be an advantage of a static JSON file over calling
They're one and the same in the final output. PHP can only be used via SAPI. On the server that's
Which means that, for full versioning, the |
Beta Was this translation helpful? Give feedback.
-
Okay, I have lots of questions and thoughts. The thoughts might be misguided due to the number of questions I have, but my goal here is to understand better the state of the project, where it is going, and how I can contribute best. Thanks to @adamziel and all the other folks doing great work on this project so far.
Questions
I think I'm in a little bit of a unique situation. ?Most? everything that is built on top of WP Playground is being done by the same folks who are building WP Playground. I'm in the position of trying to build an interface and experience on top of
remote.htmlthat's not part of the core and running into some issues. I expected this given the experimental and early nature of this project.I tried to answer this by looking at the Roadmap. This roadmap is broad and it does include "stability" type issues, but it seems to lean towards external features(pull requests, .org plugin/theme demos, etc) built on top of the core WP Playground tech.
Let's get more concrete with our discussion. Because of what I'm building, I needed to build my own UI and tailor it to the needs of our WPGraphQL Community.
Note
For those unfamiliar, I work on https://repl.wpgrpahql.com and the code can be found over at https://github.com/wpdecoupled/wpgraphql-repl. I'll note that much of what requires me to have my own UI is not yet built.
What I've seen from this experience is I can use
remote.htmland the JavaScript Client to control everything. But I'm starting from scratch. If I wanted to enable browser storage or a PHP version switcher I have to implement lots of state and control mechanisms. I have no way to even pull the currently supported PHP or WP versions from the client. I can get TS types but these are dependent on my version of the client from NPM, not what's supported by the Playground as hosted onplayground.wordpress.net. This leaves me to maintain my own lists of these and to release changes every time a new minor version is released. Not hard, but very fixable. This leads me to the major thought I have right now.Thoughts...
To be clear here, much of the docs seem to treat them separately. But in practice, it seems like these things are tied at the hip and make 3rd party API consumption difficult. I will acknowledge the Coding Standards note on a minimal public API might mean some of my more specific ideas are not in line with this idea. I'm okay with that, but just trying to communicate my current experience and better understand where we want to go and how I can help start that conversation.
Why this matters
Let's step back to the architecture of the Playground, as I understand it at least. As we know
PHP-WASMis the fundamental technology that enables everything we're doing here. This has its own set of issues, APIs, and problems to be solved. Notably, it has abrowserandnoderuntime.The next step of the layer for our stack is WordPress. We package this up and ship it off to various instances of the
PHP-WASMruntime across CLIs, browsers, desktop and mobile apps, etc. As noted in the architecture docs this uses SQLite by default.Next, according to the architecture overview, we have bindings for the browser and node. I'm struggling a bit here, maybe y'all can help. It seems this is the JS API (bindings) to command and control the PHP-WASM implementation. The best I can tell other than
runorrequestfunctions this package has little to no association with the fact that we mount WP to an iframe in Playground. Yet, the docs say these bindings assume and require an iframe. I think this iframe comment might apply to the next level of the stack and not these bindings.Finally, we get to the "Public APIs". So this is where we combined everything. We load the WP bundles into PHP-WASM using the JS bindings for browser/node/etc. This is where
remote.htmlseems to assume you have to have an iframe for rendering the site and we can use the Query or JS API to implement the whole stack in various places. In my case specifically, the iframe assumption is not ideal, I could make basic requests to GraphQL (or REST) APIs in WP without ever loading WP in an Iframe but it seems the only way to "start" the playground. Is there a way to get the client and directly send requests without doing this step?I'm trying to stay out of the weeds in this post but to not some....Are there two definitions of client here? I can import the
@wp-playground/clientbut then when I executestartPlaygroundWebthat returns a client....are these the same client or different?Okay, Back to my point. We all see there are a lot of possibilities with this technology for both the immediate WP community and beyond. But as long as the WP Playground UI is tightly coupled to the Public API it feels like everyone else trying to use the API will be second class. If we truly want anyone to build on this technology we need really clear boundaries between the Public APIs and ALL consumers, including the default WP Playground UI.
Conclusion
Okay, this isn't meant as a criticism. The best I can tell y'all have been busy building cool things and making !@#$ work. Nice work and thanks for the hard work. The current state of the project is a needed and expected phase in my estimation. But how do we move forward? This phase is really important for learning the problems and defining the value. But at what point does the project take those learnings, slow down the feature building, and define a really strong public API layer that enables everyone to build on top of it?
This is the question I started with: What's the road map to stability? What does that public API look like? How can we work towards defining a 1.0? Importantly, are we ready to move forward?
There's a reasonable possibility I'm just here too early to this project and y'all haven't finished learning what you need to look towards a 1.0. My question then would shift to, what can I (and others) do to best share our struggles and provide some learnings to inform that future stability phase?
Thanks for reading this far and engaging with me in this conversation. Looking forward to finding ways to help.
P.S.
I do have some specific ideas but have tried to stay out of those weeds here, I wanted to understand where the project is and where it is going instead of injecting my uninformed ideas in without context. I'll share these when apropriate.
@adamziel I did mention this related to testing. Maybe it does less than I originally thought, but a clearer public API definition would make testing boundaries cleaner...in fact, this testing issue might be a good example of the tight coupling I think I'm seeing. Very possible the testing is just a matter of implementing API-specific tests too.
Beta Was this translation helpful? Give feedback.
All reactions