Every important project must have a well structured directory layout in order to allow continued maintenance. A good directory layout enables a team to communicate and work together easily and enables newcomers to familiarise themselves with the project in minimal time.
project/ app/ Project-specific files. cli/ The command-line interface tools for this application. conf/ Configuration files of the application. form/ The form definitions of the application. locale/ The gettext objects for localization. php/ The php code of the project, such as code for the frames and model. sql/ The database schema, upgrade scripts and other SQL files. tmp/ Temporary files generated by the application, including the various cache files. tpl/ The templates for the application. pub/ A directory for storing any resources directly accessible to the user, like stylesheets and images. res/ Public resources distributed with the framework. share/ tools/ wee/ The Web:Extend framework. vendor/ The third party libraries embedded in the framework. index.php The frontend of the application.
Directory names should be lowercase and as short as possible.
Project-specific files should only be located in app and pub.
The only folders accessible via the World Wide Web should be pub
and res. The bootstrap file index.php can be
modified to suit the needs of the application.
As you can see, the framework does not enforce any layout for your PHP and template files. There are several decisions that can be made depending on your application, a few of which we will highlight here. Note that if you use the form module, you can use the same layout for the forms as you would for the template files.
If you are writing a small application you'll probably want to keep it as simple as possible. For this we recommend the following:
Store all template and form files at the root of their folders
Store the domain model in app/php/model, the frames in app/php/frames and the other PHP files directly in app/php
If your application is modular, you need a more advanced layout. For example, you may be constructing a blog application, featuring a separate interface for public and administrative users. These two interfaces are two different parts of your application that do not rely on each other to function correctly. They are only related due to the fact that they operate on the same data, accessed using the domain model classes.
As there are two distinct modules within this example, you could store all the related files into their own module folders. This could be achieved with a layout similar to the following:
app/form/ admin/ public/ app/php/ model/ admin/ public/ app/tpl/ admin/ public/
If you use other external libraries in your project, these can be stored in a folder
specific to these libraries within the app/php/vendor directory. If for example the
Zend Framework library is to be used in a project,
this could be stored in a app/php/vendor/zendframework directory.
It is highly recommended to keep your database schema under version control.
You are also advised to keep upgrade scripts from one version to another when you make
changes to the database schema. This will mean that applying updates to the project is a
much easier process when working within a team, or when applying any changes to the
production environment.
You can use the folder app/sql for this purpose.
Numerous software packages exist to provide version control over database schemas, and it is advisable to utilise one of these where available. We cannot advise on any particular package however, as their advantages can depend on the database system used in your application. If this not a desireable option for whatever reason, we recommend the following considerations be made:
Always record a version with any changes to your database changes. It doesn't have to be the same as the repository version, simply start from version 1 and increment with each change. Then when creating any upgrade scripts, include the applicable start version that the script will function upon in the filename of the script itself.
We recommend using the following naming convention for your SQL files:
Choose a simple name for the schema file, such as schema.sql
Any upgrade files can then be named upgrade.1.sql,
upgrade.2.sql and so on
When you need to use more than one database, for example with a backend and frontend database, the naming convention can be amended in this way:
The schema files could be named schema.backend.sql
and schema.frontend.sql instead of schema.sql
for each schema
Subsequently, upgrade.backend.1.sql and
upgrade.backend.2.sql can be used for your upgrade scripts for the
first schema, along with upgrade.frontend.x.sql
for the second.