New default directory structure

Love it!

More readable (in my opinion) ASCII art:

app
├── modules
│   ├── Web
│   │   ├── presenters
│   │   │   ├── Default
│   │   │   │   ├── templates
│   │   │   │   │   └── default.latte
│   │   │   │   └── DefaultPresenter.php
│   │   │   └── Product
│   │   │       ├── templates
│   │   │       │   ├── default.latte
│   │   │       │   └── edit.latte
│   │   │       └── ProductPresenter.php
│   │   └── templates
│   │       └── @layout.latte
│   └── Admin
│       ├── modules
│       │   └── (more modules)
│       ├── presenters
│       │   └── Default
│       │       ├── templates
│       │       │   └── default.latte
│       │       └── DefaultPresenter.php
│       └── templates
│           └── @layout.latte
├── presenters
│   └── Base
│       └── BasePresenter.php
└── templates
    └── @layout.latte

I allready use this structure for presenters and components and it is IMHO far more well-arranged. I wait just for TemplateFactory to use same code both for components and presenters.

In case components and simple presenters i try this structure without /template dir. (One .php and few .latte files in same directory).

I am not big fan of this:

1. more clicking through dirs
2. duplication of presenter's name in dir & filename

But if this becomes new default with keeping the old structure working, I have no problem with it. But the current one seems to me consisting of less steps.

But if you want to join presenter and its templates, why not this way?

app
├── modules
│   ├── Web
│   │   ├── presenters
│   │   │   ├── Default
│   │   │   │   └── Presenter.php
│   │   │   │   └── default.latte
│   │   │   │   └── view.latte
│   │   │   └── Product
│   │   │   |   └── Presenter.php
│   │   │   │   └── default.latte
│   │   │   │   └── edit.latte
│   │   └── templates
│   │       └── @layout.latte
│   └── Admin
│       ├── modules
│       │   └── (more modules)
│       ├── presenters
│       │   └── Default
│       │       ├── Presenter.php
│       │       └── default.latte
│       └── templates
│           └── @layout.latte
├── presenters
│   └── Base
│       └── BasePresenter.php
└── templates
    └── @layout.latte

Last edited by castamir (2014-02-13 20:18)

I don't like it:

• ‘templates’ folder, that NOT contains all template files.
• What happens, when I want to have more themes in my application? Directory structure becomes messy.

What about ability to configure this in config.neon?

nette:
	templatePathMask: %presenterDir%/<action>.latte
	layoutTemplatePathMask: %presenterDir%/../../layouts/@<layout='layout'>.latte

Old (actual) behaviour can be configure like this:

nette:
	templatePathMask: %presenterDir%/../../<presenter>/<action>.latte
	layoutTemplatePathMask: %presenterDir%/../../templates/@<layout='layout'>.latte

But I still don't like presenters and templates in one folder :-)

Last edited by nanuqcz (2014-02-14 07:38)

nanuqcz wrote:

• What happens, when I want to have more themes in my application? Directory structure becomes messy.

There is always ability to change the defaults.

Honza Marek +1

It's look like the most pure solution, for me.

The reason for having dedicated templates directory for each presenter is that it is expected that there will be other directories such as components or assets.

@Filip Procházka: Did you notice that @Honza Marek's suggestion is completely missing the modules directory?

nAS's solution has important benefit: there is no mess with modules names mixed with other directories, templates with presenter etc.

I tried yesterday to adapt some project to nAS's structure and discovered, that sometimes is very nice to omit direcories presenters and templates/layouts and put its content directly to module, as Honza Marek suggests.

app/
|-- presenters/ # application controllers
    |-- FrontModule/ # namespace
    |   |-- Homepage/ # namespace
    |   |   |-- HomepagePresenter.php # class
    |   |   |-- default.latte #related file
    |   |
    |   |-- Other/
    |   |   |-- OtherPresenter.php
    |   |   |-- templates/ # optional directory
    |   |   |   |-- default.latte
    |   |   |   |-- other.latte
    |   |
    |   |-- FrontPresenter.php # class i namespace
    |   |-- layout.latte
    |
    |-- AdminModule/
    |-- BasePresenter.php # class in namespace

This is quite reasonable default structure and I would go slightly further for my personal usage becase I like to use namespaces

app/
|-- presenters/ # application controllers
    |-- FilipBlog/ # namespace
    |   |-- FrontModule/ # namespace
    |   |   |-- Homepage/ # namespace
    |   |   |   |-- HomepagePresenter.php # class
    |   |   |   |-- default.latte #related file

and why not just drop the clutter right away?

app/
|-- FilipBlog/ # namespace
|   |-- FrontModule/ # namespace
|   |   |-- Homepage/ # namespace
|   |   |   |-- HomepagePresenter.php # class
|   |   |   |-- default.latte #related file

Neverless honza's proposal is the best for default structure (least overhead).

Hi everybody,

I might be called a purist (occasionally even fascist) when it comes to nomenclature, but I'd venture to disagree with most suggestions presented here. Let's start with naming the requirements:

• Presenters and their associated templates should be as close to each other as possible, while maintaining readability and orientation in directory structure.
• Modules should be nestable.
• A reasonable amount of namespacing won't hurt.
• We also don't want to add any clutter; to the contrary, where possible we'd like to do away with unnecessary directories and/or naming repetition.

So the first question is: what is the “app” directory for? From my point of view it contains the application. I'm stating the obvious on purpose: it contains the whole application, which may consist of modules and/or presenters. Additionally we could think “module-specific components”. But there is another way of looking at the “app” folder: it may also be seen as the highest module in application hierarchy – it has all the signs of a module (can contain presenters and/or other modules).

Second: what does a presenter consist of? As I see it (and as is undoubtedly the point of this whole RFC) a presenter consists of its defining class and its associated templates. The presenter doesn't make any sense without them, nor do they without it.

So bearing all this in mind, I'd propose a structure along the following lines:

/App
   /Web
      /Home
         /presenter.php
         /templates
            /default.latte
      /About
         /presenter.php
         /templates
            /default.latte
      /templates
         /@layout.latte
      /Base.php
   /Admin
      /Dashboard
         /presenter.php
         /templates
            /default.latte
      /Settings
         /presenter.php
         /templates
            /default.latte
      /templates
         /@layout.latte
      /Base.php
   /User
      /presenter.php
      /templates
         /login.latte
         /registration.latte
   /Base.php

Now before you all start throwing stones ;-) my point is: how different a module really is from a namespace? How different is a module from an actual presenter? A module is basically just a named container for a section of the application which forms a logical unit and fulfills a specific purpose. A presenter might be seen as basically a named container for functionality (either provided by the presenter itself or by a component) which, again, forms a logical unit fulfilling a given purpose.

A presenter and its associated templates form an inseparable package. Now, if folders in the filesystem could somehow “be” scripts and at the same time still act as folders (containing other files) the presenter's folder wouldn't need to contain a “presenter.php” file; but since this is not possible on any filesystem that I'm aware of there is no other way to keep the presenter and its templates next to each other and still avoid repeating the presenter's name in file names. An abstract presenter, on the other hand, has no associated templates and therefore can be defined directly by a file bearing it's name (as is the case with Base.php throughout the example).

If we take the leap and proclaim the root level a namespace, then getting from the root to the home page presenter is the shortest possible path we can think of: App\Web\Home. Wait, no WebModule? No HomePresenter? But why, really? From the application's point of view only one thing is vital: that whatever it finds at the end of the chain is a non-abstract class implementing the IPresenter interface. If that is indeed the case, it is already a presenter, even without us stating it in it's name and again in it's defining file's name and again in the containing folder's name. A module's folder can contain templates, same as a presenter's folder: these could be any templates applicable to the whole module which would mostly mean layout templates, but not necessarily only them.

But how do I know what is a module and what is a presenter? I hear you ask. Well from the outside you don't, and that's precisely the point: from the outside, you don't care, it's just a logical block of functionality and unless I care about it's innards I simply don't care. As soon as I need to look into it, it is immediately clear from the presence (or absence) of the “presenter.php” file whether I'm looking at a module or a presenter.

It has the added bonus of beauty, when you imagine a very nested structure, like App\WebModule\ForumModule\CategoryModule\ManagementPresenter, shortened all the way down to App\Web\Forum\Category\Management. And that was just the namespace we cut down. I shudder to think how the original file path to the presenter would look.

Last edited by danik (2014-02-22 04:51)

I like danik's suggestion, since I don't like the “Module” word in namespace or path. But the presenter file name should not be “presenter.php”, cause I can imagine how long I would search for the right “presenter.php” while having 3 presenter files opened. :)

I don't really think that structure suggested by Honza Marek is good (just my opinion) for 2 reasons:

1. I wouldn't expect the directory of a module under “presenters” folder, IMHO that is confusing (we are trying to call a directory by it's content, aren't we?).
2. I don't like the templates directly near the presenter files, it should be separated at least by subfolder (“templates”).

Anyone discovered any problems while covering the presenter class name by a namespace? I'm talking about this:

namespace App\Web;
class Articles { ... }

...

namespace App\Web\Articles;
class Comments { ... }

Last edited by hacafrakus (2014-02-22 19:39)

nanuqcz: no, not really. That's why the “presenter.php” file's name starts with a lowercase “p” – to indicate that the class it defines isn't called the same as the file, as is the convention. The actual presenter class would be what you took to be a namespace – App\Web\Forum\Category\Management. The file that defines this class should then obviously be app/Web/Forum/Category/Management.php – but since it then could not contain a subfolder like “templates”, you would need to create a folder of the same name next to it to hold such subfolders (as in app/Web/Forum/Category/Management/templates), which would mean the need to repeat the name of your presenter – and I'd like to avoid that. That's why the presenter class itself is defined in the (arguably artificial) “presenter.php” file. “Base” presenters (or any abstract presenters, for that matter) usually don't need other files than the one which defines them, so in their case the containing folder is redundant and the presenter can be defined in a file of the same name, such as app/Web/Forum/Category/Base.php.

I'm thinking of a presenter as a “package”, of sorts; not unlike apps on Mac OS – the apps in the /Applications folder are actually just more folders, only they happen to have the *.app extension and they have a standardized, “artificial” entry point (might be an executable with a specific name, or some kind of a manifest file, I'm not sure right now and I don't have an actual mac to check this on) – in the case of my proposed “presenter packages” that's “presenter.php”.

hacafrakus: that's a valid point… although some IDEs might solve this for us. I'm a huge fan and an ardent user of PhpStorm and if I have multiple files with the same name open at any point, PhpStorm will actually show the names of their containing folders in the tabs along with the file names, so I can differentiate between them quite easily (for instance Category/Base.php, Management/Base.php etc.). I don't know if that is the case with other IDEs (it must be years now since I last uninstalled Eclipse and NetBeans and finally switched over to PhpStorm). Anyone..?

I second both of the other two points you made – having a “modules” directory under a “presenters” directory is totally confusing and templates should definitely be in a subfolder imho.

ujovlado: I'm a big fan of modular directory structure too, I just don't like repeating myself ;-) and creating a module's directory structure following the pattern you propose means repeatedly creating a “presenters” and/or “modules” folder which imho is not necessary..

Last edited by danik (2014-02-23 04:17)

@David Grudl: Its good for me, but i think many users can PSR-0/PSR-4 compatible structure.

Last edited by Šaman (2014-02-23 20:56)

Šaman: I'm no expert on either PSR-0 or PSR-4, but from a quick glance at some articles I'd say that using either of these would necessarily lead to name duplication as both of these standards use the last part of the class name for the filename which defines the class. Therefore any additional data the class needs (templates, …) would need an additional subdirectory named after the class – and there you go, name duplication.

David Grudl: Flatten-nested modules the way you proposed them would be a direct contradiction to most of the requirements I personally have for the directory structure :-) They include the redundant “modules” directory and they require name repetition on quite a grand scale.. imagine one day needing to rename the “Admin” module to something else…

Just for an inspiration… my current directory structure is as follows:

app/
├── config/
└── AppName/									← serves as an application root namespace
    ├── Application/							← only presenters and templates are inside
	|	├── Admin/
	|	|	├── Homepage/						← templates for :Admin:Homepage:*
	|	|	|	├── @layout.latte
	|	|	|	└── default.latte
	|	|	├── Users/						← submodule - in the same level as templates dirs
	|	|	├── @layout.latte
	|	|	├── BasePresenter.php
	|	|	└── HomepagePresenter.php
	|	├── Front/
	|	├── @layout.latte						← layout for whole application
	|	└── BasePresenter.php					← base presenter for whole application
    ├── Auth/									← components and services are completelly separated
	├── Routing/								  including namespaces
	├── Storage/
	...