Project Structure

Now let us look on the project structure listed before. If you do not want to, or it looks obvious to you, you can skip the rest of this section. Anyway, you can always jump back here to find detailed information on any directory in the project structure.

/modules

The first folder is the '/modules'. This is the core folder of Pragwork library files. Modules are scripts containing all the necessary code needed to provide their functionality. Though they are self-contained as the ones known in the Python world, they can be split into multiple files stored in the folders reflecting their namespaces. For example, the ActiveRecord module has all its classes stored in files in the '/modules/ActiveRecord' directory. If necessary, the module should register its own class loader with the spl_autoload_register() function.

The most important module is the Application module loaded at application startup. It holds the application entry point. More on that you will learn in the next chapter.

/app

The second substantial directory is called '/app'. The '/app' means the user's application code. It sets the limits of relatively safe modifications of the application code from the framework point of view. In other words, you can delete all files in the '/app' structure and nothing essentially wrong will happen to the framework itself. For example, if you remove a template file, you will get the error from the action corresponding to that template. You can easily fix the controller to not use that template anymore and everything will work like before. But if you try the same on an error template, it will result in serious fatal errors and you will have to restore that file again.

The '/app' directory is also a root of the user class loader. All undefined classes are searched there directly (its structure reminds the traditional Java one). The namespaces are directories started with uppercase and classes are files with names after the classes they contain. This will help you to distinguish namespaces folders from the other. Usually, like in Java, a one class per file scheme is preferred. By default the '/app' directory has two namespaces: Controllers and Models.

Subdirectories started with lowercase indicates that there are no classes there. For example, '/app/helpers' contains helper files corresponding to controllers. The structure of '/app/helpers' folder is exactly the same as the Controllers namespace. You may put any methods and classes you want inside helper files. They will be included inside the proper controller (preserving the inheritance hierarchy - starting from ancestors). In that way the mixin-like behavior, well known from the Ruby and Ruby on Rails land, is simulated in Pragwork. Of course, it is a somewhat limited because of different abilities of PHP, but it is surprisingly effective. The helpers are a bit like modules, but in the local scale and range.

Similarly, '/app/views' contains templates. And templates are not classes, as it has been said before. Also, they are not plain PHP files but they have the PHP code mixed with other texts (e.g. with HTML code, XML code, plain text, etc). Therefore, the special braceless PHP syntax (designed for template files) is strongly advised! The '/app/views' directory contains structure reflecting the Controllers namespace. And again, special files and directories beside that scheme, starts with a lowercase letter, like '/app/views/layouts' - containing layout files indicated by layout references in the controller.

/config

The '/config' directory holds all important configuration files. Modules may put their configuration files there. The most important files in the '/config' directory are: '/config/routes.php' - keeping all routing definitions, and '/config/application.php' - with the whole application configuration.

/sql

Contains SQL files generated by the Prag generator as well as user modified ones.

/errors

Custom error templates.

/locales

Locale files. The list of those files determines the set of the available locales.

/public

The '/public' directory may be placed anywhere. It is completely independent from the project directory, because it is just a bootstrap loading the Application module and triggers off the start() function.

/temp

Temporary files for e.g cache files or error logs. The web server should have the rights to write files (+w) in this directory!

/test

Test cases for model and controllers (and other aspects of the application). Contains the 'Models' and 'Controllers' subdirectories reflecting the 'app/Models' ('app/Controllers') structures. The model tests are unit ones whereas controller tests are functional.

In the next chapter we will discuss the initial configuration of the whole application that takes place in the 'config/application.php' file.