Open RalfEggert opened 8 years ago
This is a great skeleton app for Expressive that provides a good base structure with a couple of small examples.
Yep, you are right. It is the perfect start into Zend\Expressive and all its cool features.
But the examples are a little too small for a real world application.
@RalfEggert — Since you asked for it, I'm going to take that as you volunteering to write it. :smile: I'll certainly proofread and provide feedback, if you want to create a WIP pull request for it.
@dannym87 — The skeleton gives structure, but doesn't really go into a full-fledged application; I think @RalfEggert is wanting something that shows off the various features and concerns when creating more than just the home page and a single API endpoint.
@RalfEggert If you're looking for inspiration check out proophessor-do. Since the early days of zend-expressive this demo app is available and shows how expressive can be used to serve an event sourced domain model.
@codeliner I really like your approach with an event sourced domain model, but (yes there must be one), I was thinking about a beginners tutorial for Zend\Expressive
. Event sourcing would be too much for starters. But your structure is a way to start.
@weierophinney Kudos to you! Just turn the demander into the executor! ;-)
I would really love to spend all my free time on this. But currently I am writing on my new ZF3 book so my time is very limited. But I will try to spend as much time as possible on this. Furthermore this tutorial shouldn't be a one man show. I think a good approach would be something like this:
I will start to provide a structure to start the discussion soon. And then we will see how it goes.
This is the first prototype of a structure to implement the "Getting Started" tutorial (http://framework.zend.com/manual/current/en/user-guide/overview.html) from the manual with Zend\Expressive
. It is based on the Skeleton https://github.com/zendframework/zend-expressive-skeleton.
This is basically the structure of a Zend\Expressive
project after the installation. The biggest problem would be that a tutorial will never be able to consider all combinations of routers, containers and template engines. So we should choice a set of components for the tutorial. I have chosen all the possible Zend Framework components for this structure. With other components like FastRoute or Twig it will look different.
+--- config/
| +--- autoload/
| | +--- .gitignore
| | +--- dependencies.global.php
| | +--- errorhandler.local.php
| | +--- local.php.dist
| | +--- middleware-pipeline.global.php
| | +--- routes.global.php
| | +--- templates.global.php
| | +--- zend-expressive.global.php
| +--- config.php
| +--- container.php
+--- data/
+--- public/
| +--- assets/
| +--- .htaccess
| +--- index.php
+--- src/
| +--- Action/
| +--- HomePageAction.php
| +--- HomePageFactory.php
| +--- PingAction.php
+--- templates/
| +--- app/
| | +--- home-page.phtml
| +--- error/
| | +--- 404.phtml
| | +--- error.phtml
| +--- layout/
| +--- default.phtml
+--- test/
| +--- Action/
| +--- HomePageActionTest.php
| +--- HomePageFactoryTest.php
| +--- PingActionTest.php
+--- vendor/
+--- composer.json
And this is my suggestion for a new more complex structure to implement the album tutorial. I marked all new files and directories.
+--- config/
| +--- autoload/
| | +--- .gitignore
| | +--- album.routes.global.php <-- new
| | +--- album.dependencies.global.php <-- new
| | +--- album.templates.global.php <-- new
| | +--- database.global.php <-- new
| | +--- dependencies.global.php
| | +--- errorhandler.local.php
| | +--- local.php.dist
| | +--- middleware-pipeline.global.php
| | +--- routes.global.php
| | +--- templates.global.php
| | +--- zend-expressive.global.php
| +--- config.php
| +--- container.php
+--- data/
+--- public/
| +--- assets/
| +--- .htaccess
| +--- index.php
+--- src/
| +--- Action/
| | +--- HomePageAction.php
| | +--- HomePageFactory.php
| | +--- PingAction.php
| +--- Album/ <-- new
| +--- Action/ <-- new
| | +--- CreateAction.php <-- new
| | +--- CreateActionFactory.php <-- new
| | +--- DeleteAction.php <-- new
| | +--- DeleteActionFactory.php <-- new
| | +--- EditAction.php <-- new
| | +--- EditActionFactory.php <-- new
| | +--- ListAction.php <-- new
| | +--- ListActionFactory.php <-- new
| | +--- ShowAction.php <-- new
| | +--- ShowActionFactory.php <-- new
| +--- Entity/ <-- new
| | +--- AlbumEntity.php <-- new
| +--- Form/ <-- new
| | +--- AlbumForm.php <-- new
| +--- InputFilter/ <-- new
| | +--- AlbumInputFilter.php <-- new
| +--- Table/ <-- new
| +--- AlbumTable.php <-- new
+--- templates/
| +--- album/ <-- new
| | +--- create.phtml <-- new
| | +--- edit.phtml <-- new
| | +--- delete.phtml <-- new
| | +--- list.phtml <-- new
| | +--- show.phtml <-- new
| +--- app/
| | +--- home-page.phtml
| +--- error/
| | +--- 404.phtml
| | +--- error.phtml
| +--- layout/
| +--- default.phtml
+--- test/
| +--- Action/
| +--- HomePageActionTest.php
| +--- HomePageFactoryTest.php
| +--- PingActionTest.php
+--- vendor/
+--- composer.json
Any comments?
@RalfEggert This looks very similar to the structure I've been working on. I started putting together an application yesterday evening using the default FastRoute router, twig, and Doctrine DBAL.
Check it out and let me know what you think
@RalfEggert The only suggestion I could make is to not have the single action per class pattern, but to use a single class whose _invoke
switch
es the method to private functions to handle the CRUD. This would make bring the files from 10 to 2 for the Album entity Action/
directory. Maybe I'm just too old school. I think that Apigility still does multiple methods per class, but that might change.
@moderndeveloperllc For RPC, we do a single method; however, how you break that up based on request method is up to you. We typically end up delegating to other methods. For REST, it's a bit different; the end-user doesn't interact with the controller, but rather the resource listener, which has methods for each possible action type. This is more of a service layer, though.
I'm generally of the mind 1 route/HTTP method combination per middleware It makes it far simpler to map, and keeps things nicely compartmentalized. It also removes the possibility of having required dependencies that might never be called — something quite common when you lump handlers for all request methods (not to mention routed paths) into a single class.
@weierophinney Thanks for taking the time to comment on this. You are correct in that I was thinking of the listener layer in Apigility. I guess my brain is trying to make the pattern middleware-as-controller instead of middleware-as-service. @RalfEggert I retract my suggestion :-) I do hope that #171 will help alleviate the need for some of those factory classes when using the zf service manager.
Any comments to the suggested structure at the bottom of https://github.com/zendframework/zend-expressive/issues/176#issuecomment-152104012
I think it is not optimal yet, since the files for the album are spread in three directories /config/
, /src/
and /templates/
.
What do others think? What is the best practice to write more complex Zend\Expressive
applications?
@RalfEggert I would add a config/autoload/database.local.php
as well with the database username and password.
Why add these: album.routes.global.php, album.dependencies.global.php, album.templates.global.php
? You can just use the files that are already there: routes.global.php, dependencies.global.php, templates.global.php
. Or if you like place all the album config in config/autoload/album.global.php
.
Also you place all Album source files in an Album folder. You can just place them in src/, so in stead of src/Album/Action/CreateAction.php
you could use src/Action/CreateAlbumAction.php
or src/Action/Album/CreateAction.php
. This is how I would do it:
+--- src/
| +--- Action/
| | +--- HomePageAction.php
| | +--- HomePageFactory.php
| | +--- Album/
| | | +--- CreateAction.php
| | | +--- CreateFactory.php
| | | +--- DeleteAction.php
| | | +--- DeleteFactory.php
| +--- Entity/
| | +--- AlbumEntity.php
| +--- Form/
| | +--- AlbumForm.php
| +--- InputFilter/
| | +--- AlbumInputFilter.php
| +--- Table/
| +--- AlbumTable.php
The beauty of expressive is that you choose your own structure.
EDIT: Or you can figure out a module structure like in ZF2. It only requires that you need to make sure the config files are loaded in config/config.php
. I'm not sure if this works:
// Load config from src/Album/config/autoload/
foreach (Glob::glob('src/*/config/autoload/{{,*.}global,{,*.}local}.php', Glob::GLOB_BRACE) as $file) {
$config = ArrayUtils::merge($config, include $file);
}
@RalfEggert I see pros and cons to both the structure you propose, as well as the one @xtreamwayz proposes. My feedback:
config/autoload/album.global.php
. This makes it easy for the developer to see the dependencies, routes, etc. specific to that "unit" in one place.src/
directory to the Application
namespace, which means that you end up with Application\Album
as the namespace for the album-specific code. This would be an argument for a "module"-like system (e.g., modules/Album/
); I'm not sure if I'm ready to consider such a feature for the skeleton for the initial stable version, however. Alternately, you can map the Album
namespace to src/Album/
, and be done with it.My main feedback: choose something, and start writing!
Maybe You can advise how ACL should look like in middleware app? Standard application has modules, controllers and actions which are natural resources. What is resource and privilege (in term of Zend ACL) in Expressive and ZF3? URI? (I see some disadvantages)
I agree about a single config/autoload/album.global.php
too.
The basic choice of organisation comes down:
src
, templates
and test
are top-level directories with App
and Application
separated within each top-level directoryApp
and Application
are at the top level (within a modules
directory) with src
, templates
and test
segregated within.The structures would then look like:
1. src, templates & test at top-level * 2. Application and Album at top-level
===================================== * =====================================
. * .
├── config * ├── config
│ ├── autoload * │ ├── autoload
│ │ ├── album.global.php * │ │ ├── album.global.php
│ │ ├── ... * │ │ ├── ...
│ │ └── zend-expressive.global.php * │ │ └── zend-expressive.global.php
│ ├── config.php * │ ├── config.php
│ └── container.php * │ └── container.php
├── data * ├── data
├── src * ├── modules
│ ├── Album * │ ├── Album
│ │ ├── Action * │ │ ├── src
│ │ │ ├── CreateAction.php * │ │ │ ├── Action
│ │ │ └── CreateFactory.php * │ │ │ │ ├── CreateAction.php
│ │ ├── AlbumEntity.php * │ │ │ │ └── CreateFactory.php
│ │ ├── AlbumForm.php * │ │ │ ├── AlbumEntity.php
│ │ └── AlbumTable.php * │ │ │ ├── AlbumForm.php
│ └── App * │ │ │ └── AlbumTable.php
│ └── Action * │ │ ├── templates
│ ├── HomePageAction.php * │ │ │ └── album
│ ├── HomePageFactory.php * │ │ │ ├── create.phtml
│ └── PingAction.php * │ │ │ └── list.phtml
├── templates * │ │ └── test
│ ├── album * │ │ └── Action
│ │ ├── create.phtml * │ │ ├── CreateActionTest.php
│ │ └── list.phtml * │ │ └── CreateFactoryTest.php
│ ├── app * │ └── App
│ │ └── home-page.phtml * │ ├── src
│ ├── error * │ │ └── Action
│ │ ├── 404.phtml * │ │ ├── HomePageAction.php
│ │ └── error.phtml * │ │ ├── HomePageFactory.php
│ └── layout * │ ├── templates
│ └── default.phtml * │ │ ├── app
├── test * │ │ │ └── home-page.phtml
│ ├── Album * │ │ ├── error
│ │ └── Action * │ │ │ ├── 404.phtml
│ │ ├── CreateActionTest.php * │ │ │ └── error.phtml
│ │ └── CreateFactoryTest.php * │ │ └── layout
│ └── App * │ │ └── default.phtml
│ └── Action * │ └── test
│ ├── HomePageActionTest.php * │ └── Action
│ └── HomePageFactoryTest.php * │ ├── HomePageActionTest.php
├── public * │ └── HomePageFactoryTest.php
│ ├── ... * ├── public
│ └── index.php * │ ├── ...
└── vendor * │ └── index.php
* └── vendor
Either works for me.
Whatever you do, don't make the src/
directory map to the \Application
namespace and src/Album/
map to the \Album
namespace.
@akrabat I guess on the tree structure, it's going to depend on the scale of application you're working on. Advantages of having modules
is that they can easily be separated into re-usable, standalone components.
If you're expecting to scale up with this being a potential future requirement, then having separate modules makes a lot of sense IMO, and they can be tested individually to. If you know you're never going to grow with that kind of requirement, then just having namespaces in the src
structure should be fine.
For directly relating to this Album tutorial, I'd be slightly inclined to go with the "scalable" approach of having module\Application
and module\Album
as it demonstrates a more scalable approach.
@akrabat
I really like your second approach. It gives a lot of structure which is very important for beginners when they start to learn Zend\Expressive
. I really tend to use that structure in the tutorial.
But wouldn't it make sense to start with a similar structure with the Zend\Expressive
skeleton? Otherwise the beginning of the tutorial would look like this:
Zend\Expressive
skeleton/modules/Application/
path follow proper structure/modules/Album/
to implement albumIf the tutorial leaves the Application where they have been installed beginners will be confused. The same applies for one config/autoload/album.global.php
file for the Album
and for a couple of files for the Application
.
Thoughts?
@RalfEggert I would say start with the skeleton anyway. It has an option for beginners with some examples or a bare bone option for pros.
Personally for me the structure is less important. Especially as a beginner I couldn't care less. Yes it would be helpful to mention something about expanding it and I need to start thinking about a modular structure in the future. But as a beginner I would be more interested in how to get a database connection started (doctrine, zend, pdo), forms, users, authentication (sessions, oauth, Ocramius/PSR7Session), authorization, how to separate the backend and the frontend. In a framework most of these are included already, in expressive not. And even though those modules are available in frameworks, people still struggle with them according to the questions on the web. I think that is where a tutorial can be really helpful.
Besides that, why a tutorial for an album? Who actually needs an album? Why not about building your own blog or a basic company website with a contact form etc.
@xtreamwayz
I have done a lot of ZF2 consulting in the last two years and in almost every project I identified the same pattern. Due to bad knowledge of how to structure and modularize a ZF2 MVC application the project is a real mess in most cases. People start with basic tutorials and put files almost anywhere. The Application
module turns into a God
module with dozens and hundreds of classes. To know how to structure an application is essential for beginners.
But you are right. Starting with the skeleton might be a still a good idea. Within such a 2. part explaining HOW to move files around it is the best place to explain WHY to move these files around. That will help beginners how to structure their applications. If the tutorial stuffs database, forms, users, auth, etc. anywhere without really caring of a good base structure will teach beginners how to build applications with a bad structure.
Why an album tutorial? Because the MVC part has it as well and it will be good start for beginners when they compare both tutorials...
@RalfEggert Thanx for the explanation. Makes perfect sense.
Tricky, isn't it?! It all depends on how you "think" about application structure.
I think that the "layout 1" option that I presented works well for a lot of even relatively complex applications. Of course, as @asgrim points out, layout 1 doesn't allow for easily reusing a code between applications, though I wonder how common that actually is. Personally, I'd have src/App
and test/App
directories in the skeleton to make it clear the additional namespaces are encouraged. This would then make it easy to extend it for an album tutorial that fits the current structure.
If you do want to go down then "modules layout" route, then I would start the tutorial by deleting the src
, test
and templates/app
directories completely along with both App
autoload lines in composer.json
& the relevant sections from the config files in from the config/autoload
directory. This would leave you with an "empty" application structure and you can then start with "Now lets create a modules
directory..." I probably wouldn't bother with an Application
namespace at all and route /
to \Album\Action\ListAction
. This leaves the top level templates
directory holding the layouts and error view scripts, which is probably fine as it saves having to reconfigure them.
Dealing with the configuration is the most complex in some ways as the organisation of the skeleton's set of config/autoload
files really doesn't lend itself to easily reorganising, which is why the skeleton lends itself to apps that look more like layout 1 than layout 2.
I'm not sure how useful it is, but I could add an option to the skeleton to create layout 1 for small projects and layout 2 for big modular applications. The namespaces are still the same, only the files are saved in a different structure.
@xtreamwayz
An option would be nice.
@akrabat
Clearing the application to start with an empty application structure sounds interesting.
@RalfEggert On reflection, and then consultation with @akrabat, I submitted zendframework/zend-expressive-skeleton#37, which does the following:
src/App/
, and pushes the Action/
and Composer/
subdirectories under it.test/AppTest/
, and pushes the Action/
subdirectory under it.composer.json
autoload
and autoload-dev
definitions for the App
and AppTest
namespaces to reference the new directories.This will allow you to add additional namespaces under the src/
directory within your composer.json
file, and thus allow modular directory structures. It should remain compatible with zendframework/zend-expressive-skeleton#31 as well.
I'll be merging those changes for RC4, and thus they'll be in the stable product. Hopefully those changes should allow you to proceed!
Yes, this will make it much easier to follow @akrabat first suggested structure in https://github.com/zendframework/zend-expressive/issues/176#issuecomment-160106303
Personally, I still prefer the second suggested structure. The first structure would mean to spread the files for the Album in several directories while the second combines them in one (except the config part).
I already started coding and will present my structure here soon. We can discuss it then and if the code is finalized, the writing can begin...
I finished the first prototype of the code for the tutorial. You can look at it here:
https://github.com/RalfEggert/zend-expressive-tutorial/
The code is splitted in six branches called part1 to part6. Each branch includes the code for one part of the tutorial. Here is an overview of the 6 parts:
Zend\Expressive
skeletonAlbumListAction
with template and the config file album.global.php
AlbumEntity
and AlbumTable
and using it within AlbumListAction
AlbumDataForm
and AlbumInputFilter
with their factories and adding a new AlbumCreateAction
with template and config; also added HelperPluginManagerFactory
to make form view helper available in the viewAlbumUpdateAction
and AlbumDeleteAction
and AlbumDeleteForm
for updating and deleting albumsHomePageAction
and PingAction
with templates and configuration and making AlbumListAction
to deliver the homepageSo, finally I included forms, input filters, table gateways, entities, redirecting, and some other useful stuff. Maybe I will add some refactoring in a optional part 7 to show the modular structure that @akrabat mentioned above. By leaving the structure as it was in the beginning, people can start right away. By helping to restructure the application at the end, people only need to adapt the modular structure when they really want to.
Feedback for the code is heavily welcome. If anything needs to be changed I would rather want this to be done before the writing starts. Otherwise the writing process might be much longer than necessary.
Good work!
What's your plan on unit tests? I would suggest adding them on every step, so that "Album" module will be fully covered after each part. This would show best practices. I know that it will take some effort, so I can submit some PRs to help. What do you think?
@mtymek Yes, any feedback and contribs will be very much appreciated. Just add some unit test to each part branch and I will handle the merging.
Personally, I still prefer the second suggested structure. The first structure would mean to spread the files for the Album in several directories while the second combines them in one (except the config part).
There's nothing saying you can't put templates, tests, and configuration under those folders; the src/
tree can look just like the modules/
tree of the second example if desired. The changes we made to the default structure allow either approach, though the default classes provided follow the first example.
@RalfEggert — at first blush, this all looks great. I'll try and do a more thorough review in the coming week.
Thanks for all the effort you're putting in!
@weierophinney
There's nothing saying you can't put templates, tests, and configuration under those folders; the src/ tree can look just like the modules/ tree of the second example if desired. The changes we made to the default structure allow either approach, though the default classes provided follow the first example.
Well, while doing the coding I thought it is a better idea to leave the structure as it after installation and just add an additional tutorial part to talk about structure. So we will have both. An easy structure and some ideas for a more modular structure.
Looking forward for further feedback.
Just to inform, we have a discussion about repositories and table gateways and how to implement them the "right way".
https://github.com/RalfEggert/zend-expressive-tutorial/issues/6
Here is another idea I came up with.
https://github.com/RalfEggert/zend-expressive-tutorial/issues/8
Quick status update. The code for the tutorial in the repo is settled so far. It is separated into six parts while each part has its own branch in the repo.
https://github.com/RalfEggert/zend-expressive-tutorial
Due to the holidays in the last weeks I didn't had the time to work on the text part of the tutorial. Hopefully, I will start in the next days.
@weierophinney @mtymek @xtreamwayz and others
Started the writing of the tutorial. Part 1 and 2 are almost finished.
https://github.com/RalfEggert/zend-expressive-tutorial/tree/part2/doc/book
When I am finished with it I will add it to the official repository.
I think it needs to be polished up a little by a native speaker and maybe with more background information and links. But it is a start.
Comments are welcome.
@codeliner @mtymek @xtreamwayz
Feedback for part3 the model layer is really welcome
https://github.com/RalfEggert/zend-expressive-tutorial/blob/part3/doc/book/part3.md
Just another update. With the kind help of @froschdesign I polished the first three parts of the tutorial.
https://github.com/RalfEggert/zend-expressive-tutorial/tree/part3
Among other things, I added the doc blocks to each class and a link to the example code in the example repository: https://github.com/RalfEggert/zend-expressive-tutorial/
Starting the fourth part of the tutorial now.
Just finished part4.
https://github.com/RalfEggert/zend-expressive-tutorial/tree/part4/doc/book
Feedback is welcome! :smile:
Nice progress Ralf! Unfortunately I was not able review it this weekend - just briefly scanned it. Quick note on composer: instead of pasting parts of composer.json
file you can simply tell user to run composer require zendframework/zend-db
- its easier to do it this way, less typing for both user and you as tutorial writer :)
I'll look at what you prepared in details in coming days.
Changed to composer require. Thanks for the hint!
https://github.com/RalfEggert/zend-expressive-tutorial/blob/part4/doc/book/part2.md AlbumListAction - constructor shouldn't allow to null for template renderer
Good catch, fixed it.
Ok, I finally finished all 6 parts of the tutorial:
https://github.com/RalfEggert/zend-expressive-tutorial/tree/part6/doc/book
Please review and send suggestions and PRs for any typo or other stuff that needs to be improved.
@weierophinney
Please review as well. If everything is ok I will be happy to add the tutorial to the Zend\Expressive
docs then.
Oh, just one thing. I will update the code and the text whenever RC6 is out. Maybe we should wait for the addition to Zend\Expressive
then.
@weierophinney
Forgot to write here, that I updated the tutorial to the newest RCs. Ready to review!
@RalfEggert Thanks!
We're planning on releasing the stable version today. Once that's done, I'll start doing a thorough review of the tutorial as well as the tutorial code, and we can hopefully then add it very soon; I'm sure many folks will be wanting to see this!
@RalfEggert Is your tutorial ready or any updates needed for version 2 of zend-expressive?
Hello @froschdesign, I have tried to make the tutorial v2 ready. You can have a look at gitlab.io. https://lowtower.gitlab.io/zend-expressive2-tutorial/book/part1.
I really love
Zend\Expressive
so far. To really get in rolling for beginners, I would love to see a tutorial like the Album tutorial for aZend\Mvc
project. It is really nice to see the examples, but beginners will also look for help how to structure their applications based onZend\Expressive
properly.Any ideas and thoughts about this?