The Application Files

When you create an application with Pluf you have a lot of freedom in the organisation of your files. The framework is not enforcing anything, but the following conventions will help you to have consistency, maintain your application in the future but also use several applications written with Pluf at the same time in one project.

We suppose here that you are going to write a todo list application with the name Todo.

Recommended directory structure

Here is the directory structure with the important files in a glance. To help the visualisation, a slash (/) is given at the end of the directories even so in configuration files you should never use a slash at the end of a directory name.

src/
src/Todo/
src/Todo/Item.php   
src/Todo/List.php
src/Todo/Views.php
src/Todo/Views/
src/Todo/Tests/
src/Todo/conf/
src/Todo/conf/todo.php
src/Todo/conf/todo.test.php
src/Todo/conf/urls.php
src/Todo/relations.php
src/Todo/templates/todo/
src/Todo/Migrations/
src/Todo/Migrations/Install.php
doc/
www/index.php
www/media/todo/
LICENSE
README
INSTALL
AUTHORS
CHANGELOG
VERSION

Explanation of the directories/files

The application folder is Todo. The name and the case of the name is important as it means that all the classes and functions your are going to write for your application will start with Todo. For example, all the classes and functions of Pluf start with the Pluf radical.

Tips: Find a name which is short but not common to avoid a name clash with another project. For example, Todo is really a bad name, but a good example name.

Configuration

By default, you need two configuration files, one for unit testing and one for local interaction, that is, your production configuration file on your production server and your development configuration file on your development system.

These files live in src/Todo/conf.

• src/Todo/conf/todo.php: Normal configuration file.
• src/Todo/conf/todo.test.php: Unit testing configuration file.

The name of the file is the lowercase name of your application, followed by the optional .test and then the .php extension.

Models

Models are directly in the application folder. This is to prevent having class names which are too long as they are often used in the rest of the code.

For example, here we have two model files:

• src/Todo/Item.php: Contains the class Todo_Item extends Pluf_Model.
• src/Todo/List.php: Contains the class Todo_List extends Pluf_Model.

The relations between the models within this application and with other applications is defined in the src/Todo/relations.php file. See the model definition for details.

Templates

Template files are located in src/Todo/templates/todo/.

You can wonder why adding the extra todo? This is to prevent name clash with the templates of other applications.

Suppose that you are using three applications within the same website. Your configuration file will contain the following template folders configuration:

$cfg['template_folders'] = array(
     '/path/to/src/Pluf/templates',
     '/path/to/src/Todo/templates',
     '/path/to/src/Extra/templates',
);

Now, if each application define a index.html file, without the extra folder, you will always access the Pluf index.html file, but if each application uses the extra folder, you can easily access the todo/index.html, pluf/index.html or the extra/index.html files.

Unit testing

All the unit test files are located in Todo/Tests. To learn more about unit testing with Pluf, read the unit testing documentation.

Documentation

First, all your code should be documented using PhpDoc strings. You can take a look at the code of Pluf to see some examples.

You are also free to write the documentation of your application in the doc/ folder. Any method you like is a good method to write documentation.

Installation/Migration

The installation and the migration from one version to another of an application written with Pluf is made using migration scripts. They are located in src/Todo/Migrations/.

People are used to have also an INSTALL file at the root of the application archive to have details about the installation procedure.

Report issues in the documentation

If you find errors or issues in the documentation, report a bug. We will update the documentation accordingly.