-
Notifications
You must be signed in to change notification settings - Fork 196
Add Album tutorial to docs #176
Comments
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. 😄 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 @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 This is basically the structure of a
And this is my suggestion for a new more complex structure to implement the album tutorial. I marked all new files and directories.
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 |
@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 #176 (comment) I think it is not optimal yet, since the files for the album are spread in three directories What do others think? What is the best practice to write more complex |
@RalfEggert I would add a Why add these: Also you place all Album source files in an Album folder. You can just place them in src/, so in stead of
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 // 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:
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 The basic choice of organisation comes down:
The structures would then look like:
Either works for me. Whatever you do, don't make the |
@akrabat I guess on the tree structure, it's going to depend on the scale of application you're working on. Advantages of having 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 For directly relating to this Album tutorial, I'd be slightly inclined to go with the "scalable" approach of having |
|
I really like your second approach. It gives a lot of structure which is very important for beginners when they start to learn But wouldn't it make sense to start with a similar structure with the
If the tutorial leaves the Application where they have been installed beginners will be confused. The same applies for one 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. |
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 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 If you do want to go down then "modules layout" route, then I would start the tutorial by deleting the Dealing with the configuration is the most complex in some ways as the organisation of the skeleton's set of |
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. |
An option would be nice. Clearing the application to start with an empty application structure sounds interesting. |
Per zendframework/zend-expressive#176 (comment), this patch does the following: - Creates a `src/App/` subdirectory, and moves `src/Action/` and `src/Composer` beneath them. - Creates a `test/AppTest/` subdirectory, and moves `test/Action/` beneath it. - Updates the `autoload` and `autoload-dev` entries for `App` and `AppTest`, respectively, to reference the new paths. - Updates the `App\Composer\OptionalPackages` class to reference `src/App/Action` instead of `src/Action/` when specifying the directory to remove during a minimal installation. It also ensures that the default tests are removed during minimal installation (which wasn't handled previously, and spotted when making the directory changes).
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. Please review as well. If everything is ok I will be happy to add the tutorial to the |
Oh, just one thing. I will update the code and the text whenever RC6 is out. Maybe we should wait for the addition to |
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 |
Hello @froschdesign, |
Unfortunately, I never found the time to make the tutorial ready for Zend\Expressive 2. So, maybe the version of @lowtower is a better start. It even looks as if it has more parts added. |
@lowtower @RalfEggert |
Not in the next weeks or even months. I have not enough spare time at present. Too much work and a family, if you know what I mean... What are the problems with the version of @lowtower then? |
@froschdesign if you mean, where to find the code, it's to find at gitlab as well. I have to say that I am not a professional programmer and created/amended the tutorial to learn myself and have it as a reminder. |
@RalfEggert
I know this, but we are here at GitHub. 😉 Some problems I found:
Btw. Thanks for your work! 👍 |
Hello @froschdesign, I have just created a repository at github for my tutorial changes/additions (see I propose to keep the repository similar to the one of Ralf regarding the parts 1-5. I started with part1 from scratch using the latest skeleton and would like to get Your feedback regarding coding style (e.g. where to get a valid Cheers, |
Hello @froschdesign, I have finished and uploaded part3 to github. Cheers, |
Thanks! 👍
I think tomorrow I'll have time for it. @weierophinney |
I have added some issues/questions that arose while writing the first chapters, e.g. php version, ... |
parts 1 - 5 are ready to review! |
Hello @froschdesign, I have removed the Cheers, |
You can use zend-db without zend-hydrator. It's only a soft dependency. In the $resultSetPrototype = new Zend\Db\ResultSet\ResultSet();
$resultSetPrototype->setArrayObjectPrototype(new AlbumEntity());
return new AlbumTableGateway(
$container->get(AdapterInterface::class),
$resultSetPrototype
); Maybe this is easier to explain, because the first parameter ( |
@lowtower |
the first parameter wasn't
That's what it was before: $resultSetPrototype = new HydratingResultSet(
new ArraySerializable(),
new AlbumEntity()
);
return new AlbumTableGateway(
$container->get(AdapterInterface::class),
$resultSetPrototype
); |
I put my effort on hold until the Cheers, |
This repository has been closed and moved to mezzio/mezzio; a new issue has been opened at mezzio/mezzio#19. |
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?
The text was updated successfully, but these errors were encountered: