Nice

We could add ?:

I would put layout/ under application/

Hi Wil, I have a few feedbacks:

1. I would move /config from /application folder to root.
It seems more appropriate because there are some project wide configuration that not necessary could find a logic place under /application.

2. What about using /task instead of /jobs?

3. What is the meaning/purpose of /extras and /application/apis?

I like the idea, however some things are missing:

• vendor folder, used for abstractions of the Zf; Eg ProjectName_Controller_Action (i suggest to put it in /vendor)
• folder for build scripts (i suggest /<project-root>/build-tools)
• i'd personally rename the "config" folder to "etc"
• the <module name> section should also have an extra folder "locale" for locales per module

Hi Wil,

My own comments!

1. The proposal suggests a default directory structure, but doesn't offer any justification for the decision on a case by case basis. From a feedback point of view - how can commentors debate the unjustified?

2. What are extras, apis?

3. config should be present in root if we're allowing for other top level directories besides public.

4. bootstrap.php I suggest would be better as Bootstrap.php reflecting the PEAR convention to a degree since it likely contains a class.

5. The proposal doesn't note the default content for bootstrap.php, index.php, and .htaccess. No doubt out of this proposal's context but I think the goal should be to generate an initial structure which responds almost immediately to requests (afterall who cares where it's put on a devel server). Over to Zend_Build then...

6. My favourite question: What can be removed as unnecessary? My thoughts are with apis, extras, data, jobs

7. I think either more should be moved to application, or move more to the root. Leave me less navigation clicks through PDT

8. Where is my tmp directory for sessions and other temporary data ops?

Best,
Paddy

Wil,

I 2 pretty imporant ones: tests, *tmp. I suggest to put this one in <project-root>/tests, <project-root>/tmp.

I also wrote a short description once on folder names (not all of them are covered yet), but its a start:

The controllers/ directory
The controllers/ directory contains all the controllers for the application.

The etc/ directory
Configuration and database schema files will go here.

The jobs/ directory
Cron jobs, database schema migration scripts or import scripts to be written. These are run using the PHP CLI executable and are stored here.

The models/ directory
Holds model classes, some of which are derived from database abstraction layer

The scripts/ directory
This contains a sub-folder for each controller (named after the controller) and also some layout template files. Within each sub-directory there is a template file named after the action and possibly some additional helper templates which I prefix with 2 underscores.

The application.php/bootstrap.php file
This file will contain all the different stages of the application, such as loading configuration data, setting up a database connection, etc.

The library/ Directory
Any third party library is stored in here. Most of the time, this directory is maintained by svn:externals.

The public_html/ Directory
This one is pretty obvious I think ...

The tests/ directory
Unit tests (mostly for models) will go here.

The tmp/ directory
This is the base folder for all sort of files that can be deleted! Anything transient is stored here.

I'd rename "data/" to "var/".

"config/" should be in the project root, and also renamed to "etc/".

For the "document_root", I'm also voting for "public_html/", or "htdocs/".

Reason for renaming - all of them are (more) well known, and since most people will run on Linux/Unix and most likely have Apache it fits a scheme they are used to.

What I am personally missing in this proposal is support for different instances of an application.

Let's say the application is a content management system that serves several sites. Each site is administered by a different person. So there have to be at least several "public"-directories. But what if I want to separate the cache, the data directory etc. per site?

Imagine having to give the site admins ftp-access to their site-directories, where they can upload images, templates, data etc, but preventing them from breaking the application or accessing some other peoples' site.

Maybe this is too advanced a request for this proposal, but I am already working on two projects with multiple instances so this might be worthwile to consider. It makes things a heck more complicated though - i.e. if some sites have access to certain modules that others don't have or you support custom modules that clients develop themselves and plug into my application.

Haha, I was in the middle of building a Python app that would do the same thing.

I think this is an excellent idea and please stick with XML for building the project profile, primarily because my apps use a very different structure than the default one proposed and I would like it to be non-troublesome for me to edit the profile accordingly.

Just reiterating - having a directory for jobs/tasks/build. Does it meet the 80/20 needs level only? I seriously doubt it. I really think the default should be minimal with most of the application level directories moved to root (or vice versa is application specific). If we're putting in everything plus the kitchen sink we're far more likely to thread on toes where people end up with a billion directories they either never ever use, or whose naming they inevitably disagree on. If it's not essential to a new application, or is not inevitable of a new application, it probably isn't needed...

• On layout directory:
  • I too think ./layouts/ should be under application. The reason is that Zend_Layout could not only support global site layouts (which i think is what you are referring to here), but also module specific layouts.
  • Think in terms of a situation where you have dropped in a blog MODULE that has a blog layout (think buttons for creating new posts, editing, controls, etc) and it in turn needs to be part of a much larger global layout. Zend_Layout supports this notion, which is why it probably would fit better in ./application/.
• On public:
  • Do other names make more sense here? httpdocs seems pretty common across the board.
• On bootstrap.php
  • I am on the fence for the necessity for a bootstrap.php file. Do we have a standard interface for this? What does it look like.
  • In previous projects httpdocs/index.php has sufficed as the bootstrap file, with the reasoning that your main(..) executable code is essentially boostrapping code.
  • With the addition of a bootstrap.php file, our index.php file essentially looks like this

On the whole I think it's pretty good. Like everyone here I have a slightly diverged structure - I'm not precious about it and I'm open to changing it, but here's a few differences/notes:-

• Is there going to be a template specific to hosted environments that don't give write access to any other folder than httpdocs (yeah, Plesk, I'm talking about YOU!). Could thought be given to creationg a 'framework' or 'zf' folder with a ready-made .htaccess file (containing 'deny' directives)?
• My experience is that the application folder works quite well with:-
  /application/default - contains 'default' module (controllers, views, config, layout, models)
  /application/module1 - same as above but developer-designed module
  /application/module2... etc
  Any reason why the 'default' module folders aren't similarly organised?
• I'm all for a 'default' bootstrap that we can overwrite. To me it would look pretty similar in structure to an '.ini' file (in terms of having pre-defined examples for developers to uncomment and use as-is). This would be called from 'index.php' similarly to how Ralph describes it above.
• I'm happy with 'httpdocs', 'public_html', 'document_root' or 'www' for placing all public files
• Contrary to 'var' and 'etc' I'd prefer to stick with plain-english folder descriptions - simply because they require less explanation to non-Linux types.
• I also agree that 'apis' should be optional (first time I read it I was a little confused)
• I like 'tasks' better than 'jobs' (only because I'm a snob )

Will look forward to giving this a try-out!

Reading back I realise my minimalise comment was unnecessary since some of these directories are only created if required. Presumably than a default project, wouldn't have them. Any chance we can clarify the required from the optional in the directory snapshot?

Why not put all directorys under the application directory - since they are ALL application related! I do not see the benefit to put some directorys IN the application dir and others don't.

Either public/ directory outside the application directory or inside the application directory - in this example it is outside the application dir.
(For this example i copied Wils proposal directory structure and modified it - so do not care about the names)

Tiny comment to note that /views/layouts is not a current Zend_Layout default (defaults to having a layout.phtml in views/scripts). Might be worth leaving out a layout directory to avoid confusion. I've noticed the documentation for Zend_Layout appears to not mention this anywhere - something I'll report as a documentation improvement.

After read all the post, i can't figure out what is the prefered directory structure, for my point of view all dirs are application specific, and i use for long years a structure that i changed to make it as standard as posible. I think that familiar common names will help the people to identify easy the mean of a directory.

I think that some dirs can have mode deep structure, for example images under public can have a locale directory structure if images for diferent locales are required, some times certain modules need specific configuration this can go in their module directory, so it's decision of developer to create them.

Other directory that comes in place is build, that of cource will be a directory for development stage that will be left in final product.

I think that the best aproach is make the application always modular if the developer don't wnat modules or it's a simple application only one module will be created. 

Will be great that where any place to see the proposal structure updates based on the feedback so people can see the form that the structure are take. 

Though Thomas Fritz nearly breaks the subject, I didn't see anyone else ask the following directly:

How will this work with shared hosting, where the web server root is the only directory into which customers can upload files?

With the recent addition of forms they too will need a place in the structure. I posted a question about where on Nabble (http://www.nabble.com/Zend_Form%3A-Directory-for-subclass%27d-forms--tc15812272s16154.html) and Matthew Weier O'Phinney said:

"We haven't decided on a location for forms in the directory hierarchy yet. My prediction would be in application/forms/, and prefix them with 'Form_'; in modules, they'd then be prefixed with '<Module>Form'."

Proposal has been updated to take into account all of the above comments as well as Wil's responses and further clarificaitons.

-ralph

I like the structure and i am looking forwards when the whole Zend_Build thing is ready!! Great work so far!!

I'm always a bit confused with 'scripts' directories. I've come to terms with them in application/views, although they could contain template files that do not contain any scripting. The confusion comes in again with
{root}/scripts. How do these relate?
Maybe 'maint' or 'maintenance' is a better, more descriptive name?

With the default module not in the modules directory, addModuleDirectory() isn't going to work as a one-liner. Is it expected that each module will have to be added manually in the Bootstrap class?

Rob...

I have always a problem with seperating models into the single modules, because most of the time you have, for instance, a frontend and an admin module, and both modules share the same models. Also there may be a forums module, which may share the users model with the other modules.

So in general there should always be a models directory directly within the application directory.

While I understand the concept of a 'bootstrap.php' file, I personally would rather see these tasks captured in an 'Initialization' plugin. This would provide a standard location to create routes, load additional plugins, and perform other startup-related tasks. Additionally, by being a plugin, you then have access to the class via Zend_Controller_Front::getPlugin() – allowing your application to have some introspection into the configuration environment.

My view on the subject...

• Modules inside the application folder increases clutter, nesting and denies special use of permissions on OS level. I say drop the simple app aproach and do everything modularized. It is a better practice anyway.

     application -> default -> ...  
     application -> module1 -> ...
     application -> module2 -> ...

• What's the data/indexes/ for?
• The data and temp folder look a little redundant, most of the stuff in data is always volatile and some even rarely saved besides the web server. Merge them?
• Large apps/sites don't use global locale/language files unless they are trying to kill the server. I for exemple use tmx files and i place them inside a content folder under each module. Thus my sugestion:

        application -> module -> content  
        (to place tmx, sqlite, other files with content usable by each module, default->content beeing usable by all)

• I vote on Bootstrap.php too.
• public/ should either be www/ or public_html/ to allow for instant integration with automatic usage of svn/rsync with running websites.
• Forms (beeing the beast of web development) really need a place for themselves and their viewscript decorators.
• Never having used the filters/ and helpers/ folders i have to ask... do we really needed those extra nesting inside a modular structure?
  

The only thing I don't like about the proposed structure is that there are two folders called 'scripts' that have slightly different uses. One is the Zend_View default for templates, the other for cron/build scripts. 'scripts' seems appropriate for cron jobs and such, but it would be easier to rename this folder than the view/scripts/ once since the latter needs to use the Zend_View default.

Two other things to consider:

Where would be the logical place for partial-style templates used by layouts? E.g. a site might have several different layouts that each included a standard 'footer.phtml'. Is it logical for this file to also live in the 'layouts' folder, or should this sit somewhere in views/scripts/ (or somewhere else)?

Applications sometimes include non-PHP files that need to be accessible through the web root, e.g. a Javascript library. Should such files always go inside public/, or live in the libraries folder and be accessible either via. symlink or through ZF routing?

/public needs to be modular enough to allow for the separation of "public files" per module. I regularly use sub domains and modules together to identify customer gateways.

admin.customer.com
phpmyadmin.customer.com
www.customer.com
blog.customer.com

In most cases each gateway has its own set of css, js, images and bootstrap. Some gateways might not even make use of ZF components.

I would have an apache entry for each directory/symlink in /public.

I think, best is store all classes to one folder.

Name of classe will be containt package prefix like model_User, api_StatusInformation.
Maybe controller should be separately, but this is also class.

The same model use Java in web application. It's easy for class loader to find any class, easier for user to find class, etc.

I, and others I've talked with, would really like to see a folder called 'library' inside 'application. The reason for this is that at some point you're likely to add an application-level library, and this would fit better inside the 'application' folder than in the root 'library' folder.

Example of application-level library classes:

• MyApp_Validate_UsernameAndPassword
• SomeApp_Controller_Action_Helper_Jokelist

Another reason for putting 'library' in 'application' is this: "dir layout here can be duplicated under modules/", quoted from this proposal. Having a library folder in module folders makes the module self-contained, meaining it would be a lot easier to plug in modules in your application, either by manually dropping a module in your 'modules' folder, or by using svn:externals.

This is the directory structure we have been using for zym. Its mainly a symfony/rails type of structure.

What I see here is that the name "web" is more natural and explains exactly what the public folder would contain. Generally we do not have anything else inside the public folder besides web related files.

We have an application level library folder because with most application there will be non-reusable application classes.

While we can have configs at the module level, configs/ should be located outside of the application folder because we can then move that folder elsewhere or have multiple instances of an application running different sets of configs.

The naming of images, styles, scripts is very clear and consistent compared to js, css and images/

"Batch" was chosen because ZF already has multiple scripts folders and adding another one would lead to confusion.

Overall the naming of the folders also has a nice feel to their location when sorted. "app" and "web" are clearly at the top and bottom of the list.

I'm writing a module which uses the following structure:

I stick the module-specific library inside the module. Integrating into your app is done simply by adding a couple of lines to your bootstrap, which does all of the module's setup and adding it's library/models to your include path. This allows the module to use the library as well as for you to do so in your app outside of the module.

This is necessary for a few reasons:

1) Packaging. A single external that can be easily updated without being fragmented throughout your app.

2) Installation. On top of packaging, it's much simpler to install into your app when there's just a single point of entry.

3) Dependency. You can code your own libraries all you want to, do all kinds of crazy weird stuff, but the module wont depend on or even care about it; it all operates all on it's own and only cares that ZF is in your include path. This allows it to reliably do what it's supposed to do.

As this structure stands now, re-usable modules can't be readily made available. Modules need to be viewed from a different angle, more "a project inside a project" rather than the current "set of related controllers". This is something ZF needs in my opinion, and is one of the major things which the competition has over it. What better way to spread ZF than to have a base library of user contributed, re-usable, ready to use modules you can drop right in to your app?

Of course, this directory structure isn't the only issue keeping such a thing from happening, more needs to happen, like maybe a "plugin framework", a streamlined bootstrap, etc., but currently this is what is affecting my module. I don't like that it's currently breaking best practice, but I see no other correct way to do it from my perspective.

Could you provide an example implementation of the index.php and bootstrap.php?

The way I understand it after reading the text, it would look something like this:

index.php

bootstrap.php

I am not sure if I understood correctly how to set up the modules. So please think of a project with the two modules user and shop besides the default module. Will this be the prefered setup?

If this is the prefered way I am a little afraid that this is quite confusing for beginners. Why not suggest two directory layouts? One with modules and one without modules? The one will modules could look like this (the modules/ directory could even removed to keep things simpler):

What do you think?

This is a great discussion. I would hope though that this decision, whatever that may be, be carried over to the Zend Studio team. Currently, the docs in ZF suggest a structure and code style, and when using the ZF wizard in Studio, it is completely different. For those who can access Zend Support Tickets, its #180119.

Thank you.

So a module has its own controllers, config, layouts, views and models.

I see no reason it shouldn't also have it's own library.

It would be easy if Zend_Controller_Front added the modules library path to set_include_path().

This way a module could be an extension to another module and share the library.

I don't think you need a layouts directory. I haven't used more than 2 or 3 layout files in any module and they work nicely when you place them in the root of views/scripts.

I really would like to see public modular. This way we could point apache to public/module_name.

Great discussion.
However I'm not sure that's a good idea put volatile data like 'caches' and 'sessions' with less volatile data like 'logs' or 'uploads'.
Maybe 'caches' and 'sessions' inside a /temp folder will be a best practice.

What about module bootstrap?
I have one bootstrap.php on each module to start module specific resources, like another db connection, chenge the layout, etc.

file: application/bootstrap.php

(..)

$frontController->addModuleDirectory(APPLICATION_PATH . '/modules/');

defined('MODULE_PATH')
or define('MODULE_PATH', $frontController->getModuleDirectory());

(..)

//Perform module bootstraping
if (is_readable(MODULE_PATH . '/bootstrap.php'))
include(MODULE_PATH . '/bootstrap.php');

What do you think?

There is one problem not mentioned before:

• the fact that language files (let's suppose .csv for translated texts) are stored into data folder. From a developer point this is not "volatile" data...

So i think this should go into application folder as well...

One more comment.

Config should be rather configs, if we are going to keep the same format for all folders.

1. You say: "Since Zend_Layout is capable of MVC- and non-MVC-based layouts ..." -- could you give an example of non-MVC-based layouts?

2. As others have said, cache and sessions should fall under the tmp/temp directory.

3. .htaccess is specific to Apache -- you could allow the developer to pass the name of his/her web server to the CLI and use that to generate the appropriate file(s)? For example:

zf create project -webserver apache     <- Generates .htaccess file(s)
zf create project -webserver iis7          <- Generates web.config file(s)

4. I think /etc is a crappy name for a folder, and far too generic, it could contain anything.

5. I also prefer /tasks to /jobs.

6. WRT /application/[MVC] + /modules vs /application/modules/default/[MVC], even though the latter may look a little neater, I agree with the way it is at the moment, for two reasons:

1) Modules are supposed to be re-useable -- how would someone re-use your 'default' module (with application-specific MVC)?

2) Think about nested modules:

/application
    /modules
        /default
            /controllers
            /models
            /modules    <- The default module couldn't have nested modules, because its modules are siblings (see /forums).
            /views
        /forums
            /controllers
            /models
            /modules
                /users
                    [MVC]
            /views

• -webserver can also be used to decide which folder name to use for public files (htdocs, public_html, www, etc.)
• I think I prefer /config to /configs

Hi,

Quite some discussion over here, so I decided to have a look at all your comments, think about it and think of a structure that complies with most arguments. A perfect structure is the structure that fits your application the best, but of it as something 'default'. Below is way to complex, but i tried to be complete.

Problems and solutions (completely my thoughts and I like comments!):
(1) Config should be on root level:
No, config is part of the application, system spex do belong as input to the application to function correctly, but this does not require the config to be at top level at all. I can think of it when required at CLI. But that is an other application, so CLI application requires an own folder.
(2) Naming of folders:
Naming of folders should not be OS/Server specific, as ZF is an independent application. Public seems still ok to me as 'public'. No need for 'etc' or 'var' either. Global names are clear.
(3) Locale data:
Locale data is site-wide. As modules are dependent on each other (as a Admin module is in a CMS system), there is no need to seperate locale data. So keep it global.
(4) Bootstrapping:
Since Zend_Application is introduced I think bootstrap file might become a class by default. Uppercase because its a class. No need for Initializers or such, since this is all/or should be all covered by Zend_Application.
(5) Defaulting the structure:
Empty folders (so, when you dont use builds for example) shoudld be removed. This all should just be a blueprint. When you need something, you know where to place it.
(6) Placement of layout folders:
Since every module can have more than one completely different look it makes much sense to not have all layouts centralized. Lets have them in their own module folders.
(7) Hosting without write access outside the public folder:
Pretty poor hosting then, suggest you place everything in a special folder in your public. Make sure APPLICATION_PATH and such is set. Have a .htaccess to manage access.
(8) Having the default module in a own folder:
Seems very logical, and I'm not sure about that. Maybe.. ? More comments on that? Maybe for the sake of clearity that the default is more important that its not placed in its own folder.
(9) Forms:
I do not really see why one would like to have them in the application folder, and not module specific. A form belongs to a certain part of logic and mostly cannot be generalized.
(10) Models:
It's a good idea to have shared models in application/models/. Modules may not depend to much on each other.
(11) Nesting modules:
Complex, but should be possible this way, right?
(12) Independent installation of modules:
Thinking about this for a while, it would be nice to 'install' some new logic (on large projects/websites - see post Georg van der Howen). For example, you might want to give your customer the possibility to buy and install a forum on his website. Important is that such 'installations', or better 'extensions' of your framework, may not share logic which each other (thats what modules can do - f.e. a CMS can read from other modules). A 'forum' extension may not take logic from a 'blog'. It is dependent though on the working of the application and its modules. This all is why I named it different and put it not in the application folder. There is need for a own public folder, which can 'add' public stuff. That means if something is not found in the top level 'public' folder, it might be found in its extension folder. It something which came in my mind, and I like some suggestions and critic on it.

There we go..

<project name>/
    application/
        configs/
        controllers/
            helpers/
        layouts/
            filters/
            helpers/
            scripts/
        models/
        modules/
            <module_name>
                controllers/
                    helpers/
                views/
                    filters/
                    helpers/
                    scripts/
                layouts/
                    filters/
                    helpers/
                    scripts/
        Bootstrap.php            
    data/
        indexes/
        locales/
        logs/
        uploads/
    docs/
    library/

;;;;extensions?;;;;
;   extensions/
;       <extension_name>
;           application/
;               configs/
;                   ownroute.ini
;                   extension.ini
;               controllers/
;                   helpers/
;               views/
;                   filters/
;                   helpers/
;                   scripts/
;               layouts/
;                   filters/
;                   helpers/
;                   scripts/
;               models/
;           docs/
;           data/
;               indexes/
;               locales/
;               logs/
;               uploads/
;           library/
;           override_public/
;               scripts/
;               styles/
;               images/
;;;;extensions?;;;;

    public/
        styles/
        scripts/
        images/
        .htaccess
        index.php
    scripts/
        tasks/
        build/
    temp/
        sessions/
        cache/

Let's consider some changes on public folder:

css/
js/
images/

Rather should be:
styles - more generic name
scripts - more generic name
media - here would be also other things: video, swf, aso...

What would you consider acceptable for a released ZF application (open-source or sold to client), which distributes a version of ZF?

<project name>/
    application/
    ...
    library/
        Zend/
        MyApp/
    LICENSE_ZEND.txt

or bundling the ZF in the same structure as the minimal zip:

<project name>/
    application/
    ...
    library/
        vendor/
            ZendFramework/
                bin/
                library/
                    Zend/
                LICENSE.txt
        MyApp/

I think, data/ folder should be splitted eventually also into modules. Let's assume we have indexes/ for every module (every module has some data to be indexed). What do you think?

Also, I agree that in the data/ folder should be stored also permanent (100% non-volatile) data (as files that generated some documents, original archives containing some data, images representing previews for some documents, and others )...

data/ like

data/production/session
data/production/upload
data/production/...

data/developement/session
data/developement/upload
data/developement/...

data/testing/session
data/testing/upload
data/testing/...

One of need of web application is client's side version control. It's really need because when you update the sources client use old js, css and image file and may your web app have many problem with those.

When use JavaScript files and CSS files in project in.

     public/
        .htaccess
        index.php
        0.6/
           styles/
           scripts/
           images/

When you change the new version of your software the folder must be renamed and cache of client for any .js, .css, .jpg, .png, .gif and etc will not found in new address.

For this one we need a resource plug-in for using in client.
Or maybe version resource will be used in any component and classes.