UserFrosting
UserFrosting 5.0 Planning #1154
Replies: 10 comments 13 replies
-
|
One more thing... I'm not sure how to handle the current This brings to another idea that could be implemented. Instead of dropping everything in the framework repo, some feature could also be handled by a new sprinkle. However, this could bring another level of difficulties, in the UI side of things for instance. For example, a Maybe inside the list of classes / features I listed as potentially be inside the framework, some could be moved to a custom sprinkle, just like |
Beta Was this translation helpful? Give feedback.
-
|
Ok I think I have an answer to my own question : 1. Where do we draw the line between having classes in the core sprinkle vs. a vendor package?With time. While with time the "framework" repo will probably get bigger and bigger as we move stuff from core to it, for the initial release it should contain the existing support repos plus This will allow the skeleton repo to exist, while allowing it to evolve with time. As for the existing support repos, we already know having the many repos makes it difficult to develop, tests and release as they are dependent on each other and some needs to be synced to work (eg. set support to I think for 5.0, we can probably leave out sprinkle vendor "for now" and add it in 6.0 for instance. All while replacing So to resume :
|
Beta Was this translation helpful? Give feedback.
-
|
Ok guys, @alexweissman @Silic0nS0ldier : Can we at least get the support repo merged in a single Framework one now, and release this for 4.5 ? Problem is the support packages are currently cross dependent :
I can't fix an issue in i18n without making a fix in New "Framework" repo would be structure like this : Only issue, we'll lose the git history in the new repo for each independent repo, unless you know a way to conserve it somehow ? |
Beta Was this translation helpful? Give feedback.
-
|
The current dependency graph is a little crazy. 100% it needs attention in UF 5 (or UF 6 if the scope is overloaded), with my thoughts being that However this goes, switching to a project based structure (where 90% or more UF code is brought in by composer) should help quite a bit. Oh, and this comment only relates to #1095 (comment), I haven't read the rest of this thread. |
Beta Was this translation helpful? Give feedback.
-
|
(Looks like preserving the git history could be done : https://medium.com/@checko/merging-two-git-repositories-into-one-preserving-the-git-history-4e20d3fafa4e) |
Beta Was this translation helpful? Give feedback.
-
|
Moved this issue to discussion as it's look like a more appropriate place to discuss this We're now a year later from the original post, and after a quick detour working with Laravel, I have a clear view of how UF should be structured. Funny thing is, 90% of what I wrote here a year ago still reflect my current plan. What changed are :
I think the answer is between option 2 and no options at all. As long as the sprinkles services and assets are registered, it doesn't matter what namespace they use. I don't think it will matter anymore where the sprinkle are loaded. It makes 100% sense to me to have then in vendor and have the "project" code in So the current short term plan to get this started would be : UF 4.6
UF 5
Meanwhile, I started working on the framework repo yesterday : https://github.com/userfrosting/framework |
Beta Was this translation helpful? Give feedback.
-
|
One thing for sure, it need a lots more of those Interface 😅. I've also been reading about PSR-14, might be helpful too. |
Beta Was this translation helpful? Give feedback.
-
|
As discussed in Chat, I edited the previous post. The first part will be as 4.6 and 5.0 (instead of 5 and 6)
|
Beta Was this translation helpful? Give feedback.
-
|
(also, "Move UserFrosting/System namespace to a new repo" is moved to UF5) |
Beta Was this translation helpful? Give feedback.
-
|
Note, since UF 4.6 is a thing now, I think it would be best for UF 5 to be PHP 8 and up only. By the time we ship it, PHP 7.4 might be out of support. 4.6 could be out LTS version. |
Beta Was this translation helpful? Give feedback.
-
|
Making PHP 8 the minimum also lets us leverage a lot of the new PHP 8 features (notably attributes, union types and null safe operators). |
Beta Was this translation helpful? Give feedback.
-
|
Splitting the UI out in UF5 means we'll want to make some common UI components to help developers build out their sites more quickly. (which I think I previously mentioned). There is a tool that will help a lot on this front, StorybookJS. It helps a lot with building UI components by providing an environment where they can be iterated on in isolation. It's also handy for implementing visual regression tests, and documenting component usage. It's something to look into including in whatever UI starter project we land on as well. |
Beta Was this translation helpful? Give feedback.
-
|
Had a go of adding Storybook to some web components. Didn't go so well... Build wise its quite opinionated by default which made integrating hard (not helped by it being behind on upgrading webpack). That said, I work a workable solution. Turns out it plugged in quite nicely with the React package, so its living there for now. Long term I'll probably split it into its own isolated folder. Should separate the build processes, making for less pain and easy updates. |
Beta Was this translation helpful? Give feedback.
-
|
To support custom frontends (server composed HTML, Vue, React, Angular, Svelte, etc), we need a way to provide components that are compatible across most ecosystems. Web components seem the best choice (individual frontend types may need adapters, however they will be minimal), provided we have a library helping with construction. A few libraries of note are;
Questions that need answers;
|
Beta Was this translation helpful? Give feedback.
-
|
I'll leave frontend question to you as your look more experienced than me on that point (I've only used vuejs for less than a year now, and don't know any of the link you shared). I'll only point that our user base probably only ever care about the theming (what it looks like) : Should we use Bootstrap, AdminLTE, CoreUI...? FYI, I'm open minded to rework the whole UI for V5 from start if it need to (so drop AdminLTE if necessary). This is one of Laravel shortcoming IMO, especially Laravel Jetstream : You're not only tied to either Vue/Blade, but also Tailwind CSS. But since V5 is meant to be modular, I see |
Beta Was this translation helpful? Give feedback.
-
I do think so. On my site, I'm 100% on cue right now. But it makes sense to have both. |
Beta Was this translation helpful? Give feedback.
-
|
(I'm gonna need to read more about Web Components...) |
Beta Was this translation helpful? Give feedback.
-
If everything goes to plan, the final implementation should be quite flexible. Business logic and the UI will be decoupled, which should make it easy for users to theme to their hearts delight. (be it changing colours or completely changing how something is laid out) |
Beta Was this translation helpful? Give feedback.
-
|
I've started trying out StencilJS, so far things are looking good. https://github.com/Silic0nS0ldier/uf5-prototype/tree/master/lib-gui/ui-base React A dedicated package will be required. Preact Vue HTML |
Beta Was this translation helpful? Give feedback.
-
|
Something to think about with the splitting of the frontend in v5 is that in a system with authentication, there is often a need to serve static assets/content that is not available to all. This isn't necessarily an area to be addressed in the initial v5 release but is something worth keeping in mind. #1161 |
Beta Was this translation helpful? Give feedback.
-
|
I've been pushing code to different part of V5 for some time now and wanted to take a moment share current status of what I'm doing. I also need to poke @Silic0nS0ldier thought on Assets. Parts that have been worked on for now : See also my todo (might not be public) : https://github.com/orgs/userfrosting/projects/5 Overall StructureThe current overall structure of V5 works around the skeleton (main) repo. This one is tasked with handling composer dependencies which now includes all sprinkles except the base app. Dependencies and requirementsAs decided early on, UF5 requires PHP 8 or (eventually) earlier. I'm already using some new PHP 8 features like named arguments, constructor property promotion and union type. It's great ! UF5 also runs on Slim4 and uses PHP-DI 6 as the new dependency injection container. PHP-DI is TOTALLY AWESOME and while the very nature of services providers will change from V4 to adapt to PHP-DI features, this will be for the best. Classmapper won't be necessary anymore as this duty can be handled by PHP-DI directly. Autowiring and Annotation injection makes it easy to inject services and other dependencies into pretty much anything, including Symfony Console command (Bakery commands). And I've been able to optimized most of the PHPUnit tests so far, and more optimization will comes from better use of dependencies injections. Main UserFrosting RepoThis repo is the skeleton every UF5 app will start from. It will (eventually) host the default (working) website end users will modify. Goal here is for this skeleton to be pushed back to end users own repo and requires minimal maintenance when it's time for updates. I plan on making sure all files included in this skeleton are clearly identify as to what can be edited and deleted as necessary (unlike Laravel...). For example, if I want to create "MyApp" using UF5, I would clone the main UF repo and put everything related to "MyApp" in there. Here's the default Skeleton Sprinkle Recipe as an example: https://github.com/userfrosting/UserFrosting/blob/96f95f60b86935e048f6798ecb43ffbba86b692c/app/src/MyApp.php. As of today, maybe 20% of this repo is done. FrameworkThe Framework repo holds the legacy support packages (Asssets, config, i18n, etc.) for now, plus the backbone requires to launch a modular Slim (web) app and Symfony Console (Bakery) app. I've made it so each Sprinkle now has a For example, here's the Core Sprinkle recipe : https://github.com/userfrosting/sprinkle-core/blob/dce40cc0c7de09983e74ad2bcbe89988152c4039/src/Core.php This means all sprinkles (from UF or 3rd party) are now handles exclusively by Composer and every feature is now registered instead of magically added based on namespace convention or path locations. A higher priority sprinkle could also extend another Sprinkle. Only want parts of Note that while a "dependent sprinkle" (that doesn't run on it's own and doesn't contain a It also means a sprinkle could be located anywhere now. It can be in the It's important to note I made it so the Framework has very minimal code, as the rest is still located in the Core Sprinkle. There's couple reason for this:
At this point, parts of framework could still be moved to Core or vice versa, and things could probably be renamed as well. We could completely go nuclear on this and makes a lot of things their own repo/sprinkle (Don't need db for your app? Don't install the sprinkle !) but I think for now, for the amount of market share UF has and the dev team it has (me), it not worth it. But it still been design to ! Anyhow, I consider the Framework to be 90% complete. Core SprinkleMost has been said in the Framework part, but one key difference with the new Core Sprinkle aside from being it's own repo, the "Default" pages won't be included in it anymore. Those are moved to the Skeleton. In fact, Core will only include the assets and alerts routes so far. Core sprinkle should also include the necessary services and whatnot to enable Twig 3, i18n, database, config, migrations, etc. support. I'm still working on integrating all the parts of the Core sprinkle with PHP-DI and the new structure. Current task is upgrading all existing Unit tests so everything gets green and gets to a minimal working state before going further. Admin & Account sprinklesNo work as been done on that part yet. But the key point here is AssetsThat's the moment I ping @Silic0nS0ldier again, and the whole reason for this post. With the new structure, Assets management should also be moved to Core or Framework. Minimal maintenance should be required from the files included in the skeleton. This means much of the the Node/NPM files in the main repo needs to move. I've made some attempts to get assets working (the Bakery side is fine), but the node/npm side will require much work. Thing is, it's been initially design with I see two solutions to this problem, but there could be other.
For #1, I think it might be overkill to have PHP run some tasks currently done by Node, but at the same time while the frontend command can be run on their own, they've typically been called using the Bakery command (PHP) as a middleman. So it's not too farfetched to think Bakery could first compile a json file containing the required info for Node to do it's thing. Solution #2 might be simpler, but It think it will create major overlaps. Since Composer/PSR-4 manage the location of file on the PHP side, an equivalent would be needed on the JS side, but also an equivalent of the Sprinkle Manager. I also think if you include a sprinkle in composer/Sprinkle Recipe, it's assets should be included. So I see this solution more of a temporary solution while we work on something else. I've yet to investigate how Symfony/Laravel/Slim handle this for their own "packages" or "plugins", but I know we won't find the ultimate solution on the Laravel side... |
Beta Was this translation helpful? Give feedback.
-
|
Re the frontend, not much progress has been made (competing priorities). That is not however to say no progress has been made. Web ComponentsAs previously mentioned, web components will be utilised to avoid framework lock-in. An early exploration has commenced, using Stencil to permit generation of adapters for popular frameworks including;
Other frameworks (e.g. Preact) and "native web" (e.g. UF v4 and earlier) have no specific requirements, web components can be used provided they have been registered. Design System with Atomic DesignAtomic Design details an approach for creating and maintaining robust design systems. A key takeaway for me is the "Atomic Design Methodology" where UI components are decomposed into the following;
My goal is to take this approach to UI decomposition, and apply it to the in-box UserFrosting UI. Before that however I'm applying it to a smaller scoped project that I hope will mature into a useful tool. Monolog ExplorerMonolog Explorer is an effort to create a small-scale monolog log file processor suited to young websites and local development. It will consist of 2 parts;
Relating back to the design system, this project will act as a testbed for the following;
|
Beta Was this translation helpful? Give feedback.
-
Following my first attempt at moving into the UF 5.0 structure, I think we need to define a formal plan regarding the repo and class structure for the future version of UserFrosting.
We already know the main goals for v5 are :
Creating a skeleton repo means all base code not in the core Sprinkle needs to be moved somewhere else, especially the
sprinklemanager.To better illustrate the current situation, here is the current UF repo structure :
Compared to the proposed structure :
I also generated the current class structure of UF 4 : https://gist.github.com/lcharette/0d6db88d300690468436ed7555cf5ef2#file-1-currentstructure-md
Big questions that needs answers
1. Where do we draw the line between having classes in the core sprinkle vs. a vendor package?
First, it's important to note we do need a higher lever dependency. For a bare minimum, we need the
SprinkleManagerto be out of core, and ideally out of the skeleton repo too.This question is valid for both UF core code and user code. Is there really a requirement for a user or UF extension to create a sprinkle (repo), load the code as a vendor package ?
I think the answer relies on one thing : Is the code UserFrosting specific, or can it be reused in another project ?
If the answer is yes, then I think a vendor package would make sense. But we have to keep in mind all other resources (locale, assets, routes, templates, etc.) still need to be accessible in a specific path (see point 4 about this).
In a functional standpoint, running phpunit on the skeleton repo should run all integration tests related to the content (controller, model, etc.). While all the "unit testing" of the individual component should be done independently.
I did a quick mockup of what the class/repo structure would be :
The full mockup can be found here :
https://gist.github.com/lcharette/0d6db88d300690468436ed7555cf5ef2#file-3-proposedstructure-md
Some notes about this structure :
The difference between the core sprinkle and the framework repo can be seen as :
Some of the
UserFrosting/Frameworkcontent could be split into their own read-only repo, just like Laravel Illuminate packages… But that wouldn’t be required, as the skeleton repo would probably load the whole framework repo.The “framework” namespace wouldn’t be used for simplicity. So it would still be
UserFrosting/Assets/…,UserFrosting/i18n/…, notUserFrosting/Framework/i18n. Only sprinkles would be differentiated with theUserFrosting/Sprinkles/Namespace.At this point, I’m not sure how the bakery commands should be handled. Of course, bakery commands should be registered instead of discovered, which means we could put them wherever we want. They could be in the Framework (would make it easier to test) or a sprinkle. Assuming the Bakery class is in the Framework, then I guess it makes sense for command to be found there too. A good example would be the
localecommands. They don't technically requires UF to run. One could clone thei18nrepo and want execute those commands. Note Laravel works that way.Same goes for services provider. One thing important about service, currently my IDE doesn’t recognize
$this->ci->translatoras an instance ofTranslatorsince it’s actually loaded as a callback inside the provider class. We should implement a custom way to implement something that could take this into account, plus one which is testable.In the end, I think the key is everything in the
Frameworkrepo needs to be self contained. They can't have dependencies on the content of the sprinkle (including Models), but it can have dependency on other framework component.In other word, if a component form UF 4 can be moved to a distinct repo right now, it should be moved to the framework repo.
On the other hand, we also need to take into account dependencies on the locale strings, which would stay inside the sprinkle...
I see the Framework as the bare minimum UF needs to run, but also the one that dictate how it should run. That's why I think this should also apply for Interfaces, which should ideally be in the Framework.
2. How do we structure the Sprinkle namespace and directory structure if we add sprinkle vendor name ?
The directory structure would ideally be :
Current namespace for sprinkle is :
UserFrosting/Sprinkles/CoreUserFrosting/Sprinkles/AdminUserFrosting/Sprinkles/FormGeneratorUserFrosting/Sprinkles/MySiteI see 3 options for the new sprinkle namespaces :
Option 1 :
UserFrosting/Sprinkles/UserFrosting/CoreUserFrosting/Sprinkles/UserFrosting/AdminUserFrosting/Sprinkles/Lcharette/FormGeneratorUserFrosting/Sprinkles/Lcharette/MySiteOption 2 :
UserFrosting/Sprinkles/CoreUserFrosting/Sprinkles/AdminLcharette/Sprinkles/FormGeneratorLcharette/Sprinkles/MySiteOption 3:
Sprinkles/UserFrosting/CoreSprinkles/UserFrosting/AdminSprinkles/Lcharette/FormGeneratorSprinkles/Lcharette/MySiteI suggest we stick to the first option, as it’s more “psr-esque”
3. Should vendor dir be in
app/vendor/orvendor/?I think we should move
vendor/to the root repo to be consistent with 99% of the PHP world, especially when running command (ie.vendor/bin/phpunitvsapp/vendor/bin/phpunit)4. Should dependent sprinkles be loaded in vendor, and custom user code be left in
app/sprinkles/?For this one, I think we need some sort of control. I've talked about classes so far, but we still need to think about the other resources not in
src/: assets, locale, routes, config, etc.See also
UF 5.0 Related issue / ideas / wishlist :
bake#1021Beta Was this translation helpful? Give feedback.
All reactions