4.1. Creating a Module Skeleton (The definitive guide of Symfony 1.0)

As Chapter 2 explained, symfony groups pages into modules. Before creating a page, you need to create a module, which is initially an empty shell with a file structure that symfony can recognize.

The symfony command line automates the creation of modules. You just need to call the init-module task with the application name and the module name as arguments. In the previous chapter, you created a myapp application. To add a mymodule module to this application, type the following commands:

> cd ~/myproject
> symfony init-module myapp mymodule

>> dir+      ~/myproject/apps/myapp/modules/mymodule
>> dir+      ~/myproject/apps/myapp/modules/mymodule/actions
>> file+     ~/myproject/apps/myapp/modules/mymodule/actions/actions.class.php
>> dir+      ~/myproject/apps/myapp/modules/mymodule/config
>> dir+      ~/myproject/apps/myapp/modules/mymodule/lib
>> dir+      ~/myproject/apps/myapp/modules/mymodule/templates
>> file+     ~/myproject/apps/myapp/modules/mymodule/templates/indexSuccess.php
>> dir+      ~/myproject/apps/myapp/modules/mymodule/validate
>> file+     ~/myproject/test/functional/myapp/mymoduleActionsTest.php
>> tokens    ~/myproject/test/functional/myapp/mymoduleActionsTest.php
>> tokens    ~/myproject/apps/myapp/modules/mymodule/actions/actions.class.php
>> tokens    ~/myproject/apps/myapp/modules/mymodule/templates/indexSuccess.php

Apart from the actions/, config/, lib/, templates/, and validate/ directories, this command created only three files. The one in the test/ folder concerns unit tests, and you don't need to bother with it until Chapter 15. The actions.class.php (shown in Listing 4-1) forwards to the default module congratulation page. The templates/indexSuccess.php file is empty.

Listing 4-1 - The Default Generated Action, in actions/actions.class.php

<?php

class mymoduleActions extends sfActions
{
  public function executeIndex()
  {
    $this->forward('default', 'module');
  }
}

Note If you look at an actual actions.class.php file, you will find more than these few lines, including a lot of comments. This is because symfony recommends using PHP comments to document your project and prepares each class file to be compatible with the phpDocumentor tool (phpdoc.org/).

For each new module, symfony creates a default index action. It is composed of an action method called executeIndex and a template file called indexSuccess.php. The meanings of the execute prefix and Success suffix will be explained in Chapters 6 and 7, respectively. In the meantime, you can consider that this naming is a convention. You can see the corresponding page (reproduced in Figure 4-1) by browsing to the following URL:

http://localhost/myapp_dev.php/mymodule/index

The default index action will not be used in this chapter, so you can remove the executeIndex() method from the actions.class.php file, and delete the indexSuccess.php file from the templates/ directory.

Note Symfony offers other ways to initiate a module than the command line. One of them is to create the directories and files yourself. In many cases, actions and templates of a module are meant to manipulate data of a given table. As the necessary code to create, retrieve, update, and delete records from a table is often the same, symfony provides a mechanism called scaffolding to generate this code for you. Refer to Chapter 14 for more information about this technique.

Figure 4.1 The default generated index page