Development

#3276: docfixes.patch

You must first sign up to be able to contribute.

Ticket #3276: docfixes.patch

File docfixes.patch, 50.5 kB (added by tonypiper, 9 months ago)

  • doc/03-Running-Symfony.txt

    old new  
    2727 
    2828Test your installation by executing the symfony CLI. Go to the new `sf_sandbox/` directory and type the following on a *nix system: 
    2929 
    30     > ./symfony -V 
     30    > php ./symfony -V 
    3131 
    3232On Windows, issue this command: 
    3333 
    34     > symfony -V 
     34    > php symfony -V 
    3535 
    3636You should see the sandbox version number: 
    3737 
    …… 
    101101 
    102102That's it. The symfony files and CLI are installed. Check that the installation succeeded by calling the new `symfony` command line, asking for the version number: 
    103103 
    104     > symfony -V 
     104    > php symfony -V 
    105105 
    106106    symfony version 1.1.0 (/path/to/the/pear/symfony/lib/dir) 
    107107 
    …… 
    159159 
    160160    > mkdir ~/myproject 
    161161    > cd ~/myproject 
    162     > symfony generate:project myproject 
     162    > php symfony generate:project myproject 
    163163 
    164164For an SVN installation, create a project with these commands: 
    165165 
    …… 
    184184    web/ 
    185185 
    186186>**TIP** 
     187>@francoisz: do we still need this tip? 
    187188>The `generate:project` task adds a `symfony` script in the project root directory. This PHP script does the same as the `symfony` command installed by PEAR, so you can call `php symfony` instead of `symfony` if you don't have native command-line support (for SVN installations). 
    188189 
    189190### Creating the Application 
    …… 
    190191 
    191192The project is not yet ready to be viewed, because it requires at least one application. To initialize it, use the `symfony generate:app` command and pass the name of the application as an argument: 
    192193 
    193     > symfony generate:app frontend 
     194    > php symfony generate:app frontend 
    194195 
    195196This will create a `frontend/` directory in the `apps/` folder of the project root, with a default application configuration and a set of directories ready to host the file of your website: 
    196197 

  • doc/04-The-Basics-of-Page-Creation.txt

    old new  
    1313The 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 `frontend` application. To add a `content` module to this application, type the following commands: 
    1414 
    1515    > cd ~/myproject 
    16     > symfony generate:module frontend content 
     16    > php symfony generate:module frontend content 
    1717 
    1818    >> dir+      ~/myproject/apps/frontend/modules/content/actions 
    1919    >> file+     ~/myproject/apps/frontend/modules/content/actions/actions.class.php 

  • doc/05-Configuring-Symfony.txt

    old new  
    459459 
    460460This presents a major advantage over many PHP frameworks, where configuration files are compiled at every request, even in production. Unlike Java, PHP doesn't share an execution context between requests. For other PHP frameworks, keeping the flexibility of XML configuration files requires a major performance hit to process all the configuration at every request. This is not the case in symfony. Thanks to the cache system, the overhead caused by configuration is very low. 
    461461 
    462 There is an important consequence of this mechanism. If you change the configuration in the production environment, you need to force the reparsing of all the configuration files for your modification to be taken into account. For that, you just need to clear the cache, either by deleting the content of the cache/ directory or, more easily, by calling the clear-cache symfony task: 
     462There is an important consequence of this mechanism. If you change the configuration in the production environment, you need to force the reparsing of all the configuration files for your modification to be taken into account. For that, you just need to clear the cache, either by deleting the content of the cache/ directory or, more easily, by calling the `cache:clear` task: 
    463463 
    464     > symfony clear-cache 
     464    > php symfony cache:clear 
    465465 
    466466Accessing the Configuration from Code 
    467467------------------------------------- 

  • doc/06-Inside-the-Controller-Layer.txt

    old new  
    6161 
    6262One front controller exists per environment. As a matter of fact, it is the very existence of a front controller that defines an environment. The environment is defined in the `SF_ENVIRONMENT` constant. 
    6363 
    64 To change the environment in which you're browsing your application, just choose another front controller. The default front controllers available when you create a new application with the `symfony init-app` task are `index.php` for the production environment and `frontend_dev.php` for the development environment (provided that your application is called `frontend`). The default `mod_rewrite` configuration will use `index.php` when the URL doesn't contain a front controller script name. So both of these URLs display the same page (`mymodule/index`) in the production environment: 
     64To change the environment in which you're browsing your application, just choose another front controller. The default front controllers available when you create a new application with the `php symfony generate:app` task are `index.php` for the production environment and `frontend_dev.php` for the development environment (provided that your application is called `frontend`). The default `mod_rewrite` configuration will use `index.php` when the URL doesn't contain a front controller script name. So both of these URLs display the same page (`mymodule/index`) in the production environment: 
    6565 
    6666    http://localhost/index.php/mymodule/index 
    6767    http://localhost/mymodule/index 
    …… 
    8989 
    9090### Batch Files 
    9191 
     92@francoisz: is this still valid? 
    9293You may want to execute a script from the command line (or via a cron table) with access to all the symfony classes and features, for instance to launch batch e-mail jobs or to periodically update your model through a process-intensive calculation. For such a script, you need to include the same lines as in a front controller at the beginning. Listing 6-3 shows an example of the beginning of a batch script. 
    9394 
    9495Listing 6-3 - Sample Batch Script 
    …… 
    107108 
    108109You can see that the only missing line is the call to the `dispatch()` method of the sfController object, which can be used only with a web server, not in a batch process. Defining an application and an environment gives you access to a specific configuration. Including the application `config.php` initiates the context and the autoloading. 
    109110 
    110 >**TIP** 
    111 >The symfony CLI offers an `init-batch` task, which automatically creates a skeleton similar to the one in Listing 6-3 in the `batch/` directory. Just pass it an application name, an environment name, and a batch name as arguments. 
    112  
    113111Actions 
    114112------- 
    115113 

  • doc/08-Inside-the-Model-Layer.txt

    old new  
    110110 
    111111The schema is used to build the model classes of the ORM layer. To save execution time, these classes are generated with a command-line task called `propel-build-model`. 
    112112 
    113     > symfony propel-build-model 
     113    > php symfony propel:build-model 
    114114 
    115115>**TIP** 
    116 >After building your model, you must remember to clear symfony's internal cache with `symfony cc` so symfony can find your newly created models. 
     116>After building your model, you must remember to clear symfony's internal cache with `php symfony cc` so symfony can find your newly created models. 
    117117 
    118118Typing this command will launch the analysis of the schema and the generation of base data model classes in the `lib/model/om/` directory of your project: 
    119119 
    …… 
    920920 
    921921If you start your application by writing the `schema.yml` file, symfony can generate a SQL query that creates the tables directly from the YAML data model. To use the query, go to your root project directory and type this: 
    922922 
    923     > symfony propel-build-sql 
     923    > php symfony propel:build-sql 
    924924 
    925925A `lib.model.schema.sql` file will be created in `myproject/data/sql/`. Note that the generated SQL code will be optimized for the database system defined in the `phptype` parameter of the `propel.ini` file. 
    926926 
    …… 
    929929    > mysqladmin -u root -p create blog 
    930930    > mysql -u root -p blog < data/sql/lib.model.schema.sql 
    931931 
    932 The generated SQL is also helpful to rebuild the database in another environment, or to change to another DBMS. If the connection settings are properly defined in your `propel.ini`, you can even use the `symfony propel-insert-sql` command to do this automatically. 
     932The generated SQL is also helpful to rebuild the database in another environment, or to change to another DBMS. If the connection settings are properly defined in your `propel.ini`, you can even use the `php symfony propel:insert-sql` command to do this automatically. 
    933933 
    934934>**TIP** 
    935935>The command line also offers a task to populate your database with data based on a text file. See Chapter 16 for more information about the `propel:data-load` task and the YAML fixture files. 
    …… 
    940940 
    941941In order to do this, you need to make sure that the project `propel.ini` file points to the correct database and contains all connection settings, and then call the `propel-build-schema` command: 
    942942 
    943     > symfony propel-build-schema 
     943    > php symfony propel:build-schema 
    944944 
    945945A brand-new `schema.yml` file built from your database structure is generated in the `config/` directory. You can build your model based on this schema. 
    946946 
    …… 
    946946 
    947947The schema-generation command is quite powerful and can add a lot of database-dependent information to your schema. As the YAML format doesn't handle this kind of vendor information, you need to generate an XML schema to take advantage of it. You can do this simply by adding an `xml` argument to the `build-schema` task: 
    948948 
    949     > symfony propel-build-schema xml 
     949    > php symfony propel:build-schema xml 
    950950 
    951951Instead of generating a `schema.yml` file, this will create a `schema.xml` file fully compatible with Propel, containing all the vendor information. But be aware that generated XML schemas tend to be quite verbose and difficult to read. 
    952952 

  • doc/12-Caching.txt

    old new  
    281281 
    282282### Clearing the Entire Cache 
    283283 
    284 The `clear-cache` task of the symfony command line erases the cache (HTML, configuration, and i18n cache). You can pass it arguments to erase only a subset of the cache, as shown in Listing 12-8. Remember to call it only from the root of a symfony project. 
     284The `cache:clear` task of the symfony command line erases the cache (HTML, configuration, and i18n cache). You can pass it arguments to erase only a subset of the cache, as shown in Listing 12-8. Remember to call it only from the root of a symfony project. 
    285285 
    286286Listing 12-8 - Clearing the Cache 
    287287 
    …… 
    286286Listing 12-8 - Clearing the Cache 
    287287 
    288288    // Erase the whole cache 
    289     > symfony clear-cache 
     289    > php symfony cache:clear 
    290290 
    291291    // Short syntax 
    292     > symfony cc 
     292    > php symfony cc 
    293293 
    294294    // Erase only the cache of the frontend application 
    295     > symfony clear-cache frontend 
     295    > php symfony cache:clear frontend 
    296296 
    297297    // Erase only the HTML cache of the frontend application 
    298     > symfony clear-cache frontend template 
     298    > php symfony cache:clear frontend template 
    299299 
    300300    // Erase only the configuration cache of the frontend application 
    301     > symfony clear-cache frontend config 
     301    > php symfony cache:clear frontend config 
    302302 
    303303### Clearing Selective Parts of the Cache 
    304304 
    …… 
    472472 
    473473    http://myapp.example.com/frontend_staging.php/user/list 
    474474 
    475 >**TIP** 
    476 >Instead of copying an existing one, you can create a new front controller with the `symfony` command line. For instance, to create a `staging` environment for the `frontend` application, called `frontend_staging.php` and where `SF_DEBUG` is `true`, just call `symfony init-controller frontend staging frontend_staging true`. 
    477  
    478475### Monitoring Performance 
    479476 
    480477Chapter 16 will explore the web debug toolbar and its contents. However, as this toolbar offers valuable information about cached elements, here is a brief description of its cache features. 

  • doc/13-I18n-and-L10n.txt

    old new  
    215215 
    216216### Using the Generated I18n Objects 
    217217 
    218 Once the corresponding object model is built (don't forget to call `symfony` `propel-build-model` and clear the cache with a `symfony cc` after each modification of the `schema.yml`), you can use your `Product` class with i18n support as if there were only one table, as shown in Listing 13-8. 
     218Once the corresponding object model is built (don't forget to call `php symfony propel:build-model` and clear the cache with a `php symfony cc` after each modification of the `schema.yml`), you can use your `Product` class with i18n support as if there were only one table, as shown in Listing 13-8. 
    219219 
    220220Listing 13-8 - Dealing with i18n Objects 
    221221 

  • doc/14-Generators.txt

    old new  
    1919 
    2020All the code generation tasks based on the model create an entire module, and result from a single call to the symfony command line in the shape of the following: 
    2121 
    22     > symfony <TASK_NAME> <APP_NAME> <MODULE_NAME> <CLASS_NAME> 
     22    > php symfony <TASK_NAME> <APP_NAME> <MODULE_NAME> <CLASS_NAME> 
    2323 
    24 The code generation tasks are `propel-init-crud`, `propel-generate-crud`, and `propel-init-admin`. 
     24@francoisz: propel-init-crud is now merged with propel:generate-crud... so this section needs fixing 
     25The code generation tasks are `propel-init-crud`, `propel:generate-crud`, and `propel:init-admin`. 
    2526 
    2627### Scaffolding and Administration 
    2728 
    …… 
    3637 
    3738Symfony offers two ways to generate code: either by inheritance (`init`) or by code generation (`generate`). 
    3839 
    39 You can initiate a module, that is, create empty classes that inherit from the framework. This masks the PHP code of the actions and the templates to avoid them from being modified. This is useful if your data structure is not final, or if you just need a quick interface to a database to manipulate records. The code executed at runtime is not located in your application, but in the cache. The command-line tasks for this kind of generation start with `propel-init-`. 
     40You can initiate a module, that is, create empty classes that inherit from the framework. This masks the PHP code of the actions and the templates to avoid them from being modified. This is useful if your data structure is not final, or if you just need a quick interface to a database to manipulate records. The code executed at runtime is not located in your application, but in the cache. The command-line tasks for this kind of generation start with `propel:init-`. 
    4041 
    4142Initiated action code is empty. For instance, an initiated `article` module has actions looking like this: 
    4243 
    …… 
    4546    { 
    4647    } 
    4748 
    48 On the other hand, you can also generate the code of the actions and the templates so that it can be modified. The resulting module is therefore independent from the classes of the framework, and cannot be altered using configuration files. The command-line tasks for this kind of generation start with `propel-generate-`. 
     49On the other hand, you can also generate the code of the actions and the templates so that it can be modified. The resulting module is therefore independent from the classes of the framework, and cannot be altered using configuration files. The command-line tasks for this kind of generation start with `propel:generate-`. 
    4950 
    5051As the scaffoldings are built to serve as a base for further developments, it is often best to generate a scaffolding. On the other hand, an administration should be easy to update through a change in the configuration, and it should remain usable even if the data model changes. That's why administrations are initiated only. 
    5152 
    …… 
    8889 
    8990To generate the scaffolding for an `article` module based on the `Article` model class, type the following: 
    9091 
    91     > symfony propel-generate-crud frontend article Article 
     92    > php symfony propel:generate-crud frontend article Article 
    9293 
    9394Symfony reads the definition of the `Article` class in the `schema.yml` and creates a set of templates and actions based on it, in the `frontend/modules/article/` directory. 
    9495 
    …… 
    160161 
    161162To initiate a Propel scaffolding that will create an `article` module to deal with the records of the `Article` model class name, type the following: 
    162163 
    163     > symfony propel-init-crud frontend article Article 
     164@francoisz: propel-init-crud is now merged with propel:generate-crud... so this section needs fixing 
     165    > php symfony propel-init-crud frontend article Article 
    164166 
    165167You can then access the `list` view using the default action: 
    166168 
    …… 
    175177Administration 
    176178-------------- 
    177179 
    178 Symfony can generate more advanced modules, still based on model class definitions from the `schema.yml` file, for the back-end of your applications. You can create an entire site administration with only generated administration modules. The examples of this section will describe administration modules added to a `backend` application. If your project doesn't have a `backend` application, create its skeleton now by calling the `init-app` task: 
     180Symfony can generate more advanced modules, still based on model class definitions from the `schema.yml` file, for the back-end of your applications. You can create an entire site administration with only generated administration modules. The examples of this section will describe administration modules added to a `backend` application. If your project doesn't have a `backend` application, create its skeleton now by calling the `generate:app` task: 
    179181 
    180     > symfony init-app backend 
     182    > php symfony generate:app backend 
    181183 
    182184Administration modules interpret the model by way of a special configuration file called `generator.yml`, which can be altered to extend all the generated components and the module look and feel. Such modules benefit from the usual module mechanisms described in previous chapters (layout, validation, routing, custom configuration, autoloading, and so on). You can also override the generated action or templates, in order to integrate your own features into the generated administration, but `generator.yml` should take care of the most common requirements and restrict the use of PHP code only to the very specific. 
    183185 
    …… 
    183185 
    184186### Initiating an Administration Module 
    185187 
    186 With symfony, you build an administration on a per-module basis. A module is generated based on a Propel object using the `propel-init-admin` task, which uses syntax similar to that used to initiate a scaffolding: 
     188With symfony, you build an administration on a per-module basis. A module is generated based on a Propel object using the `propel:init-admin` task, which uses syntax similar to that used to initiate a scaffolding: 
    187189 
    188     > symfony propel-init-admin backend article Article 
     190    > php symfony propel:init-admin backend article Article 
    189191 
    190192This call is enough to create an `article` module in the `backend` application based on the `Article` class definition, and is accessible by the following: 
    191193 
    …… 
    300302 
    301303The generator configuration file is very powerful, allowing you to alter the generated administration in many ways. But such capabilities come with a price: The overall syntax description is long to read and learn, making this chapter one of the longest in this book. The symfony website proposes an additional resource that will help you learn this syntax: the administration generator cheat sheet, reproduced in Figure 14-7. Download it from [http://www.symfony-project.org/uploads/assets/sfAdminGeneratorRefCard.pdf](http://www.symfony-project.org/uploads/assets/sfAdminGeneratorRefCard.pdf), and keep it close to you when you read the following examples of this chapter. 
    302304 
    303 The examples of this section will tweak the `article` administration module, as well as the `comment` administration module, based on the `Comment` class definition. Create the latter with the `propel-init-admin` task: 
     305The examples of this section will tweak the `article` administration module, as well as the `comment` administration module, based on the `Comment` class definition. Create the latter with the `propel:init-admin` task: 
    304306 
    305     > symfony propel-init-admin backend comment Comment 
     307    > php symfony propel:init-admin backend comment Comment 
    306308 
    307309Figure 14-7 - The administration generator cheat sheet 
    308310 

  • doc/15-Unit-and-Functional-Testing.txt

    old new  
    107107 
    108108Listing 15-2 - Launching a Single Unit Test from the Command Line 
    109109 
    110     > symfony test-unit strtolower 
     110    > php symfony test:unit strtolower 
    111111 
    112112    1..7 
    113113    # strtolower() 
    …… 
    224224 
    225225Listing 15-4 - The Count of Test Run Helps You to Plan Tests 
    226226 
    227     > symfony test-unit example 
     227    > php symfony test:unit example 
    228228 
    229229    1..16 
    230230    # hello world 
    …… 
    268268        foo/ 
    269269          barTest.php 
    270270 
    271     > symfony test-unit myFunction                   ## Run myFunctionTest.php 
    272     > symfony test-unit myFunction mySecondFunction  ## Run both tests 
    273     > symfony test-unit 'foo/*'                      ## Run barTest.php 
    274     > symfony test-unit '*'                          ## Run all tests (recursive) 
     271    > php symfony test:unit myFunction                   ## Run myFunctionTest.php 
     272    > php symfony test:unit myFunction mySecondFunction  ## Run both tests 
     273    > php symfony test:unit 'foo/*'                      ## Run barTest.php 
     274    > php symfony test:unit '*'                          ## Run all tests (recursive) 
    275275 
    276276### Stubs, Fixtures, and Autoloading 
    277277 
    …… 
    403403 
    404404A functional test traditionally starts with an initialization of a test browser object. This object makes a request to an action and verifies that some elements are present in the response. 
    405405 
     406@francoisz: propel-init-crud is now merged with propel:generate-crud... so this section needs fixing 
    406407For example, every time you generate a module skeleton with the `init-module` or the `propel-init-crud` tasks, symfony creates a simple functional test for this module. The test makes a request to the default action of the module and checks the response status code, the module and action calculated by the routing system, and the presence of a certain sentence in the response content. For a `foobar` module, the generated `foobarActionsTest.php` file looks like Listing 15-9. 
    407408 
    408409Listing 15-9 - Default Functional Test for a New Module, in `tests/functional/frontend/foobarActionsTest.php` 
    …… 
    428429 
    429430A functional test can contain several requests and more complex assertions; you will soon discover all the possibilities in the upcoming sections. 
    430431 
    431 To launch a functional test, use the `test-functional` task with the symfony command line, as shown in Listing 15-10. This task expects an application name and a test name (omit the `Test.php` suffix). 
     432To launch a functional test, use the `test:functional` task with the symfony command line, as shown in Listing 15-10. This task expects an application name and a test name (omit the `Test.php` suffix). 
    432433 
    433434Listing 15-10 - Launching a Single Functional Test from the Command Line 
    434435 
    435     > symfony test-functional frontend foobarActions 
     436    > php symfony test:functional frontend foobarActions 
    436437 
    437438    # get /comment/index 
    438439    ok 1 - status code is 200 
    …… 
    737738    [php] 
    738739    $b = new sfTestBrowser('myapp.example.com', '123.456.789.123'); 
    739740 
    740 ### The test-functional Task 
     741### The test:functional Task 
    741742 
    742 The `test-functional` task can run one or more functional tests, depending on the number of arguments received. The rules look much like the ones of the `test-unit` task, except that the functional test task always expects an application as first argument, as shown in Listing 15-27. 
     743The `test:functional` task can run one or more functional tests, depending on the number of arguments received. The rules look much like the ones of the `test-unit` task, except that the functional test task always expects an application as first argument, as shown in Listing 15-27. 
    743744 
    744745Listing 15-27 - Functional Test Task Syntax 
    745746 
    …… 
    753754          myOtherScenarioTest.php 
    754755 
    755756    ## Run all functional tests for one application, recursively 
    756     > symfony test-functional frontend 
     757    > php symfony test:functional frontend 
    757758 
    758759    ## Run one given functional test 
    759     > symfony test-functional frontend myScenario 
     760    > php symfony test:functional frontend myScenario 
    760761 
    761762    ## Run several tests based on a pattern 
    762     > symfony test-functional frontend my* 
     763    > php symfony test:functional frontend my* 
    763764 
    764765Test Naming Practices 
    765766--------------------- 
    …… 
    825826 
    826827### Executing Tests in a Test Harness 
    827828 
    828 The `test-unit` and `test-functional` tasks can launch a single test or a set of tests. But if you call these tasks without any parameter, they launch all the unit and functional tests written in the `test/` directory. A particular mechanism is involved to isolate each test file in an independent sandbox, to avoid contamination risks between tests. Furthermore, as it wouldn't make sense to keep the same output as with single test files in that case (the output would be thousands of lines long), the tests results are compacted into a synthetic view. That's why the execution of a large number of test files uses a test harness, that is, an automated test framework with special abilities. A test harness relies on a component of the lime framework called `lime_harness`. It shows a test status file by file, and an overview at the end of the number of tests passed over the total, as you see in Listing 15-31. 
     829The `test:unit` and `test:functional` tasks can launch a single test or a set of tests. But if you call these tasks without any parameter, they launch all the unit and functional tests written in the `test/` directory. A particular mechanism is involved to isolate each test file in an independent sandbox, to avoid contamination risks between tests. Furthermore, as it wouldn't make sense to keep the same output as with single test files in that case (the output would be thousands of lines long), the tests results are compacted into a synthetic view. That's why the execution of a large number of test files uses a test harness, that is, an automated test framework with special abilities. A test harness relies on a component of the lime framework called `lime_harness`. It shows a test status file by file, and an overview at the end of the number of tests passed over the total, as you see in Listing 15-31. 
    829830 
    830831Listing 15-31 - Launching All Tests in a Test Harness 
    831832 
    832     > symfony test-unit 
     833    > php symfony test:unit 
    833834 
    834835    unit/myFunctionTest.php................ok 
    835836    unit/mySecondFunctionTest.php..........ok 
    …… 
    842843 
    843844The tests are executed the same way as when you call them one by one, only the output is made shorter to be really useful. In particular, the final chart focuses on the failed tests and helps you locate them. 
    844845 
    845 You can launch all the tests with one call using the `test-all` task, which also uses a test harness, as shown in Listing 15-32. This is something that you should do before every transfer to production, to ensure that no regression has appeared since the latest release. 
     846You can launch all the tests with one call using the `test:all` task, which also uses a test harness, as shown in Listing 15-32. This is something that you should do before every transfer to production, to ensure that no regression has appeared since the latest release. 
    846847 
    847848Listing 15-32 - Launching All the Tests of a Project 
    848849 
    849     > symfony test-all 
     850    > php symfony test:all 
    850851 
    851852### Accessing a Database 
    852853 
    …… 
    861862    // Optionally, you can retrieve the current database connection 
    862863    $con = Propel::getConnection(); 
    863864 
    864 You should populate the database with fixtures before starting the tests. This can be done via the `sfPropelData` object. This object can load data from a file, just like the `propel-load-data` task, or from an array, as shown in Listing 15-34. 
     865You should populate the database with fixtures before starting the tests. This can be done via the `sfPropelData` object. This object can load data from a file, just like the `propel:data-load` task, or from an array, as shown in Listing 15-34. 
    865866 
    866867Listing 15-34 - Populating a Database from a Test File 
    867868 
    …… 
    977978Summary 
    978979------- 
    979980 
    980 Automated tests include unit tests to validate methods or functions and functional tests to validate features. Symfony relies on the lime testing framework for unit tests and provides an `sfTestBrowser` class especially for functional tests. They both provide many assertion methods, from basic to the most advanced, like CSS selectors. Use the symfony command line to launch tests, either one by one (with the `test-unit` and `test-functional` tasks) or in a test harness (with the `test-all` task). When dealing with data, automated tests use fixtures and stubs, and this is easily achieved within symfony unit tests. 
     981Automated tests include unit tests to validate methods or functions and functional tests to validate features. Symfony relies on the lime testing framework for unit tests and provides an `sfTestBrowser` class especially for functional tests. They both provide many assertion methods, from basic to the most advanced, like CSS selectors. Use the symfony command line to launch tests, either one by one (with the `test:unit` and `test:functional` tasks) or in a test harness (with the `test:all` task). When dealing with data, automated tests use fixtures and stubs, and this is easily achieved within symfony unit tests. 
    981982 
    982983If you make sure to write enough unit tests to cover a large part of your applications (maybe using the TDD methodology), you will feel safer when refactoring internals or adding new features, and you may even gain some time on the documentation task. 

  • doc/16-Application-Management-Tools.txt

    old new  
    126126 
    127127Don't forget to periodically purge the `log/` directory of your applications, because these files have the strange habit of growing by several megabytes in a few days, depending, of course, on your traffic. Symfony provides a special `log-purge` task for this purpose, which you can launch regularly by hand or put in a cron table. For example, the following command erases the symfony log files: 
    128128 
    129     > symfony log-purge 
     129    > php symfony log:clear 
    130130 
    131131For both better performance and security, you probably want to store symfony logs in several small files instead of one single large file. The ideal storage strategy for log files is to back up and empty the main log file regularly, but to keep only a limited number of backups. You can enable such a log rotation with a `period` of `7` days and a `history` (number of backups) of `10`, as shown in Listing 16-6. You would work with one active log file plus ten backup files containing seven days' worth of history each. Whenever the next period of seven days ends, the current active log file goes into backup, and the oldest backup is erased. 
    132132 
    …… 
    132132 
    133133Listing 16-6 - Launching Log Rotation 
    134134 
    135     > symfony --period=7 --history=10 log-rotate frontend prod 
     135    > php symfony --period=7 --history=10 log:rotate frontend prod 
    136136 
    137137The backup log files are stored in the `logs/history/` directory and suffixed with the date they were saved. 
    138138 
    …… 
    370370 
    371371### Launching the Import 
    372372 
    373 The `propel-load-data` task imports data from YAML files to a database. The connection settings come from the `databases.yml` file, and therefore need an application name to run. Optionally, you can specify an environment name by adding a `--env` option (`dev` by default). 
     373The `propel:data-load` task imports data from YAML files to a database. The connection settings come from the `databases.yml` file, and therefore need an application name to run. Optionally, you can specify an environment name by adding a `--env` option (`dev` by default). 
    374374 
    375     > symfony propel:data-load --env=prod frontend 
     375    > php symfony propel:data-load --env=prod frontend 
    376376 
    377377This command reads all the YAML fixture files from the `data/fixtures/` directory and inserts the records into the database. By default, it replaces the existing database content, but if you add an `--append` option, the command will not erase the current data. 
    378378 
    379     > symfony propel:data-load --append frontend 
     379    > php symfony propel:data-load --append frontend 
    380380 
    381381You can specify another fixture directory in the call. In this case, add a path relative to the project directory. 
    382382 
    383     > symfony propel:data-load frontend --dir[]=data/myfixtures 
     383    > php symfony propel:data-load frontend --dir[]=data/myfixtures 
    384384 
    385385### Using Linked Tables 
    386386 
    …… 
    434434 
    435435That's why symfony provides a utility to "freeze" a project--to copy all the necessary symfony libraries into the project `data/`, `lib/`, and `web/` directories. The project then becomes a kind of sandbox, an independent, stand-alone application. 
    436436 
    437     > symfony freeze 
     437    > php symfony project:freeze 
    438438 
    439439Once a project is frozen, you can transfer the project directory into production, and it will work without any need for PEAR, symbolic links, or whatever else. 
    440440 
    …… 
    441441>**TIP** 
    442442>Various frozen projects can work on the same server with different versions of symfony without any problems. 
    443443 
    444 To revert a project to its initial state, use the `unfreeze` task. It erases the `data/symfony/`, `lib/symfony/`, and `web/sf/` directories. 
     444To revert a project to its initial state, use the `project:unfreeze` task. It erases the `data/symfony/`, `lib/symfony/`, and `web/sf/` directories. 
    445445 
    446     > symfony unfreeze 
     446    > php symfony project:unfreeze 
    447447 
    448448Note that if you had symbolic links to a symfony installation prior to the freeze, symfony will remember them and re-create the symbolic links in the original location. 
    449449 
    …… 
    473473 
    474474Doing an rsync over SSH requires several commands, and synchronization can occur a lot of times in the life of an application. Fortunately, symfony automates this process with just one command: 
    475475 
    476     > symfony sync production 
     476    > php symfony project:deploy production 
    477477 
    478478This command launches the rsync command in dry mode; that is, it shows which files must be synchronized but doesn't actually synchronize them. If you want the synchronization to be done, you need to request it explicitly by adding `go`. 
    479479 
    480     > symfony sync production go 
     480    > php symfony project:deploy production go 
    481481 
    482482Don't forget to clear the cache in the production server after synchronization. 
    483483 
    …… 
    526526 
    527527### Managing a Production Application 
    528528 
    529 The command that is used most often in production servers is `clear-cache`. You must run it every time you upgrade symfony or your project (for instance, after calling the `sync` task), and every time you change the configuration in production. 
     529The command that is used most often in production servers is `cache:clear`. You must run it every time you upgrade symfony or your project (for instance, after calling the `project:deploy` task), and every time you change the configuration in production. 
    530530 
    531     > symfony clear-cache 
     531    > php symfony cache:clear 
    532532 
    533533>**TIP** 
    534534>If the command-line interface is not available in your production server, you can still clear the cache manually by erasing the contents of the `cache/` folder. 
    …… 
    535535 
    536536You can temporarily disable your application--for instance, when you need to upgrade a library or a large amount of data. 
    537537 
    538     > symfony disable APPLICATION_NAME ENVIRONMENT_NAME 
     538    > php symfony project:disable APPLICATION_NAME ENVIRONMENT_NAME 
    539539 
    540540By default, a disabled application displays the `$sf_symfony_data_dir/web/errors/unavailable.php` page, but if you create your own `unavailable.php` file in your project's `web/errors/` directory, symfony will use it instead. 
    541541 
    542 The `enable` task reenables the application and clears the cache. 
     542The `project:enable` task reenables the application and clears the cache. 
    543543 
    544     > symfony enable APPLICATION_NAME ENVIRONMENT_NAME 
     544    > php symfony project:enable APPLICATION_NAME ENVIRONMENT_NAME 
    545545 
    546546>**SIDEBAR** 
    547547>Displaying an unavailable page when clearing the cache 
    …… 
    548548> 
    549549>If you set the `check_lock` parameter to `on` in the `settings.yml` file, symfony will lock the application when the cache is being cleared, and all the requests arriving before the cache is finally cleared are then redirected to a page saying that the application is temporarily unavailable. If the cache is large, the delay to clear it may be longer than a few milliseconds, and if your site's traffic is high, this is a recommended setting. This unavailable page is the same as the one displayed when you call the symfony `disable` task. The `check_lock` parameter is deactivated by default because it has a very slight negative impact on performance. 
    550550> 
    551 >The `clear-controllers` task clears the `web/` directory of all controllers other than the ones running in a production environment. If you do not include the development front controllers in the `rsync_exclude.txt` file, this command guarantees that a backdoor will not reveal the internals of your application. 
     551>The `project:clear-controllers` task clears the `web/` directory of all controllers other than the ones running in a production environment. If you do not include the development front controllers in the `rsync_exclude.txt` file, this command guarantees that a backdoor will not reveal the internals of your application. 
    552552> 
    553 >     > symfony clear-controllers 
     553>     > php symfony project:clear-controllers 
    554554> 
    555 >The permissions of the project files and directories can be broken if you use a checkout from an SVN repository. The `fix-perms` task fixes directory permissions, to change the `log/` and `cache/` permissions to 0777, for example (these directories need to be writable for the framework to work correctly). 
     555>The permissions of the project files and directories can be broken if you use a checkout from an SVN repository. The `project:permissions` task fixes directory permissions, to change the `log/` and `cache/` permissions to 0777, for example (these directories need to be writable for the framework to work correctly). 
    556556> 
    557 >     > symfony fix-perms 
     557>     > php symfony project:permissions 
    558558 
    559559>**SIDEBAR** 
     560>@francoisz: Do we need this sidebar now tonypiper, 2008-04-04? 
    560561>Access to the symfony commands in production 
    561562> 
    562563>If your production server has a PEAR installation of symfony, then the symfony command line is available from every directory and will work just as it does in development. For frozen projects, however, you need to add `php` before the `symfony` command to be able to launch tasks: 
    …… 
    563564> 
    564565> 
    565566>     // With symfony installed via PEAR 
    566 >     > symfony [options] <TASK> [parameters] 
     567>     > php symfony [options] <TASK> [parameters] 
    567568> 
    568569>     // With symfony frozen in the project or symlinked 
    569570>     > php symfony [options] <TASK> [parameters] 

  • doc/17-Extending-Symfony.txt

    old new  
    680680          ... 
    681681 
    682682  * The plug-in configuration is to be included in the plug-in bootstrap script (`config.php`). This file is executed after the application and project configuration, so symfony is already bootstrapped at that time. You can use this file, for instance, to add directories to the PHP include path or to extend existing classes with mixins. 
    683   * Fixtures files located in the plug-in `data/fixtures/` directory are processed by the `propel-load-data` task. 
    684   * Tasks are immediately available to the symfony command line as soon as the plug-in is installed. It is a best practice to prefix the task by something meaningful--for instance, the plug-in name. Type `symfony` to see the list of available tasks, including the ones added by plug-ins. 
     683  * Fixtures files located in the plug-in `data/fixtures/` directory are processed by the `propel:data-load` task. 
     684  * Tasks are immediately available to the symfony command line as soon as the plug-in is installed. It is a best practice to prefix the task by something meaningful--for instance, the plug-in name. Type `php symfony` to see the list of available tasks, including the ones added by plug-ins. 
    685685  * Custom classes are autoloaded just like the ones you put in your project `lib/` folders. 
    686686  * Helpers are automatically found when you call `use_helper()` in templates. They must be in a` helper/` subdirectory of one of the plug-in's `lib/` directory. 
    687687  * Model classes in `myplugin/lib/model/` specialize the model classes generated by the Propel builder (in `myplugin/lib/model/om/` and `myplugin/lib/model/map/`). They are, of course, autoloaded. Be aware that you cannot override the generated model classes of a plug-in in your own project directories. 

  • doc/18-Performance.txt

    old new  
    392392  * When you create a new class: Adding a class to an autoloading directory (one of the project's `lib/` folders) is not enough to have symfony find it automatically. You must clear the autoloading configuration cache so that symfony browses again all the directories of the `autoload.yml` file and references the location of autoloadable classes--including the new ones. 
    393393  * When you change the configuration in production: The configuration is parsed only during the first request in production. Further requests use the cached version instead. So a change in the configuration in the production environment (or any environment where `SF_DEBUG` is turned off) doesn't take effect until you clear the cached version of the file. 
    394394  * When you modify a template in an environment where the template cache is enabled: The valid cached templates are always used instead of existing templates in production, so a template change is ignored until the template cache is cleared or outdated. 
    395   * When you update an application with the `sync` command: This case usually covers the three previous modifications. 
     395  * When you update an application with the `project:deploy` command: This case usually covers the three previous modifications. 
    396396 
    397397The problem with clearing the whole cache is that the next request will take quite long to process, because the configuration cache needs to be regenerated. Besides, the templates that were not modified will be cleared from the cache as well, losing the benefit of previous requests. 
    398398 
    399 That means it's a good idea to clear only the cache files that really need to be regenerated. Use the options of the `clear-cache` task to define a subset of cache files to clear, as demonstrated in Listing 18-14. 
     399That means it's a good idea to clear only the cache files that really need to be regenerated. Use the options of the `cache:clear` task to define a subset of cache files to clear, as demonstrated in Listing 18-14. 
    400400 
    401401Listing 18-14 - Clearing Only Selective Parts of the Cache 
    402402 
    …… 
    401401Listing 18-14 - Clearing Only Selective Parts of the Cache 
    402402 
    403403    // Clear only the cache of the frontend application 
    404     > symfony clear-cache frontend 
     404    > php symfony cache:clear frontend 
    405405 
    406406    // Clear only the HTML cache of the frontend application 
    407     > symfony clear-cache frontend template 
     407    > php symfony cache:clear frontend template 
    408408 
    409409    // Clear only the configuration cache of the frontend application 
    410     > symfony clear-cache frontend config 
     410    > php symfony cache:clear frontend config 
    411411 
    412412You can also remove files by hand in the `cache/` directory, or clear template cache files selectively from the action with the `$cacheManager->remove()` method, as described in Chapter 12. 
    413413 
    …… 
    488488The `sfFunctionCache` constructor expects a cache object. The first argument of the `call()` method must be a callable, so it can be a function name, an array of a class name and static method name, or an array of an object name and public method name. As for the other argument of the `call()` method, it's an array of arguments that will be passed to the callable. 
    489489 
    490490>**CAUTION** 
    491 >If you use a file based cache object as in the example, it's better to give a cache directory under the `cache/` directory, as it will be cleanup automatically by the `clear-cache` task. If you store the function cache somewhere else, it will not be cleared automatically when you clear the cache through the command line. 
     491>If you use a file based cache object as in the example, it's better to give a cache directory under the `cache/` directory, as it will be cleanup automatically by the `cache:clear` task. If you store the function cache somewhere else, it will not be cleared automatically when you clear the cache through the command line. 
    492492 
    493493### Caching Data in the Server 
    494494 
    …… 
    617617 
    618618To apply the optimizations, you must first install the plug-in from [http://trac.symfony-project.com/wiki/sfOptimizerPlugin](http://trac.symfony-project.com/wiki/sfOptimizerPlugin) and then call the `optimize` task, specifying an application and an environment: 
    619619 
    620     > symfony optimize frontend prod 
     620    > php symfony optimize frontend prod 
    621621 
    622622If you want to apply other optimization strategies to your code, the `sfOptimizer` plug-in might be a good starting place. 
    623623 

  • doc/19-Mastering-Symfony-s-Configuration-Files.txt

    old new  
    3838Two other pages bear a symfony look and feel, and they also need to be customized before deployment to production. These pages are not in the `default` module, because they are called when symfony cannot run properly. Instead, you will find these default pages in the `$sf_symfony_data_dir/web/errors/` directory: 
    3939 
    4040  * `error500.php`: Page called when an internal server error occurs in the production environment. In other environments (where `SF_DEBUG` is set to `true`), when an error occurs, symfony displays the full execution stack and an explicit error message (see Chapter 16 for details). 
    41   * `unavailable.php`: Page called when a user requests a page while the application is disabled (with the `disable` task). It is also called while the cache is being cleared (that is, between a call to the `symfony clear-cache` task and the end of this task execution). On systems with a very large cache, the cache-clearing process can take several seconds. Symfony cannot execute a request with a partially cleared cache, so requests received before the end of the process are redirected to this page. 
     41  * `unavailable.php`: Page called when a user requests a page while the application is disabled (with the `disable` task). It is also called while the cache is being cleared (that is, between a call to the `php symfony cache:clear` task and the end of this task execution). On systems with a very large cache, the cache-clearing process can take several seconds. Symfony cannot execute a request with a partially cleared cache, so requests received before the end of the process are redirected to this page. 
    4242 
    4343To customize these pages, simply create `error500.php` and `unavailable.php` pages in your application's `web/errors/` directory. Symfony will use these instead of its own. 
    4444 
    …… 
    6262`cache`                 | Enables template caching (see Chapter 12). Set it to `on` if one of your modules includes `cache.yml` file. The cache filter (`sfCacheFilter`) is enabled only if it is on. | `off` in development, `on` in production 
    6363`web_debug`             | Enables the web debug toolbar for easy debugging (see Chapter 16). Set it to `on` to display the toolbar on every page. The web debug filter (`sfWebDebugFilter`) is enabled ony if it is on. | `on` in development, `off` in production 
    6464`check_symfony_version` | Enables the check of the symfony version for every request. Set it to on for automatic cache clearing after a framework upgrade. Leave it set to off if you always clear the cache after an upgrade. | `off` 
    65 `check_lock`            | Enables the application lock system, triggered by the `clear-cache` and `disable` tasks (see the previous section). Set it to `on` to have all requests to disabled applications redirected to the `$sf_symfony_data_dir/web/errors/unavailable.php` page. | `off` 
     65`check_lock`            | Enables the application lock system, triggered by the `cache:clear` and `project:disable` tasks (see the previous section). Set it to `on` to have all requests to disabled applications redirected to the `$sf_symfony_data_dir/web/errors/unavailable.php` page. | `off` 
    6666`compressed`            | Enables PHP response compression. Set it to `on` to compress the outgoing HTML via the PHP compression handler. | `off` 
    6767`use_process_cache`     | Enables symfony optimizations based on PHP accelerators. When such an accelerator (for instance, APC, XCache, or eAccelerator) is installed, symfony takes advantage of its features to keep objects and configuration in memory between requests. Set the parameter to `off` in development or when you don't want PHP accelerator optimizations. Note that even if you don't have any accelerator installed, leaving it set to `on` will not harm performance. | `on` 
    6868 
    …… 
    377377    $sf_symfony_lib_dir  = '/path/to/symfony/lib'; 
    378378    $sf_symfony_data_dir = '/path/to/symfony/data'; 
    379379 
    380 These paths are initialized when you call a `symfony init-project` from the command line, and refer to the symfony installation used to build the project. They are used both by the command line and by the MVC architecture. 
     380These paths are initialized when you call a `php symfony generate:project` from the command line, and refer to the symfony installation used to build the project. They are used both by the command line and by the MVC architecture. 
    381381 
    382382This means that you can switch to another installation of symfony by changing the paths to the framework files. 
    383383