Development

Changeset 8283

You must first sign up to be able to contribute.

Changeset 8283

Show
Ignore:
Timestamp:
04/04/08 14:52:12 (5 months ago)
Author:
francois
Message:

[doc 1.1] changed CLI task names to new ones, and added php before the symfony command (thanks tonypiper for the patch) (closes #3276)

Files:

Legend:

Unmodified
Added
Removed
Modified
Copied
Moved

  • doc/branches/1.1/book/03-Running-Symfony.txt

    r7703 r8283  
    2626>Having all the files under the root web directory is fine for your own tests in a local host, but is a bad practice in a production server. It makes all the internals of your application visible to end users. 
    2727 
    28 Test your installation by executing the symfony CLI. Go to the new `sf_sandbox/` directory and type the following on a *nix system: 
    29  
    30     > ./symfony -V 
    31  
    32 On Windows, issue this command: 
    33  
    34     > symfony -V 
     28Test your installation by executing the symfony CLI. Go to the new `sf_sandbox/` directory and type the following: 
     29 
     30    > php symfony -V 
    3531 
    3632You should see the sandbox version number: 
    …… 
    167163    > cd ~/myproject 
    168164    > php /path/to/symfony/data/bin/symfony generate:project myproject 
    169  
    170 The `symfony` command must always be called from the project's root directory (`myproject/` in the preceding examples), because all the tasks performed by this command are project-specific. 
    171165 
    172166Symfony will create a directory structure that looks like this: 
    …… 
    191185The 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: 
    192186 
    193     > symfony generate:app frontend 
     187    > php symfony generate:app frontend 
    194188 
    195189This 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: 
    …… 
    210204 
    211205`index.php` is the production front controller of the new application. Because you created the first application of the project, symfony created a file called `index.php` instead of `frontend.php` (if you now add a new application called `backend`, the new production front controller will be named `backend.php`). To run your application in the development environment, call the front controller `frontend_dev.php`. You'll learn more about these environments in Chapter 5. 
     206 
     207The `symfony` command must always be called from the project's root directory (`myproject/` in the preceding examples), because all the tasks performed by this command are project-specific. 
    212208 
    213209Configuring the Web Server 
    …… 
    239235In the configuration in Listing 3-1, the `$sf_symfony_data_dir` placeholder must be replaced by the actual path. For example, for a PEAR installation in *nix, you should type something like this: 
    240236 
    241         Alias /sf /usr/local/lib/php/data/symfony/web/sf 
     237    Alias /sf /usr/local/lib/php/data/symfony/web/sf 
    242238 
    243239>**NOTE** 

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

    r7704 r8283  
    1111As 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. 
    1212 
    13 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 `frontend` application. To add a `content` module to this application, type the following commands: 
     13The symfony command line automates the creation of modules. You just need to call the `generate: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 

  • doc/branches/1.1/book/05-Configuring-Symfony.txt

    r7705 r8283  
    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: 
    463  
    464     > symfony clear-cache 
     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: 
     463 
     464    > php symfony cache:clear 
    465465 
    466466Accessing the Configuration from Code 

  • doc/branches/1.1/book/06-Inside-the-Controller-Layer.txt

    r8255 r8283  
    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 `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 
    …… 
    107107 
    108108You 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. 
    109  
    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. 
    112109 
    113110Actions 

  • doc/branches/1.1/book/08-Inside-the-Model-Layer.txt

    r8262 r8283  
    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: 
    …… 
    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. 
    …… 
    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** 
    …… 
    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. 
    …… 
    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. 

  • doc/branches/1.1/book/12-Caching.txt

    r7789 r8283  
    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 
    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 
    …… 
    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 

  • doc/branches/1.1/book/13-I18n-and-L10n.txt

    r7705 r8283  
    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 the `propel:build-model` task 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 

  • doc/branches/1.1/book/14-Generators.txt

    r7986 r8283  
    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> 
    23  
    24 The code generation tasks are `propel-init-crud`, `propel-generate-crud`, and `propel-init-admin`. 
     22    > php symfony <TASK_NAME> <APP_NAME> <MODULE_NAME> <CLASS_NAME> 
     23 
     24The code generation tasks are `propel-init-crud`, `propel:generate-crud`, and `propel:init-admin`. 
    2525 
    2626### Scaffolding and Administration 
    …… 
    3737Symfony offers two ways to generate code: either by inheritance (`init`) or by code generation (`generate`). 
    3838 
    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-`. 
     39You 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-`. 
    4040 
    4141Initiated action code is empty. For instance, an initiated `article` module has actions looking like this: 
    …… 
    4646    } 
    4747 
    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-`. 
     48On 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-`. 
    4949 
    5050As 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. 
    …… 
    8989To generate the scaffolding for an `article` module based on the `Article` model class, type the following: 
    9090 
    91     > symfony propel-generate-crud frontend article Article 
     91    > php symfony propel:generate-crud frontend article Article 
    9292 
    9393Symfony 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. 
    …… 
    161161To initiate a Propel scaffolding that will create an `article` module to deal with the records of the `Article` model class name, type the following: 
    162162 
    163     > symfony propel-init-crud frontend article Article 
     163    > php symfony propel-init-crud frontend article Article 
    164164 
    165165You can then access the `list` view using the default action: 
    …… 
    176176-------------- 
    177177 
    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: 
    179  
    180     > symfony init-app backend 
     178Symfony 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: 
     179 
     180    > php symfony generate:app backend 
    181181 
    182182Administration 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. 
    …… 
    184184### Initiating an Administration Module 
    185185 
    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: 
    187  
    188     > symfony propel-init-admin backend article Article 
     186With 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: 
     187 
     188    > php symfony propel:init-admin backend article Article 
    189189 
    190190This call is enough to create an `article` module in the `backend` application based on the `Article` class definition, and is accessible by the following: 
    …… 
    301301The 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. 
    302302 
    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: 
    304  
    305     > symfony propel-init-admin backend comment Comment 
     303The 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: 
     304 
     305    > php symfony propel:init-admin backend comment Comment 
    306306 
    307307Figure 14-7 - The administration generator cheat sheet 

  • doc/branches/1.1/book/15-Unit-and-Functional-Testing.txt

    r7705 r8283  
    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 
    …… 
    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 
    …… 
    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 
    …… 
    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 For 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. 
     406For example, every time you generate a module skeleton with the `generate:module` or the `propel:generate-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. 
    407407 
    408408Listing 15-9 - Default Functional Test for a New Module, in `tests/functional/frontend/foobarActionsTest.php` 
    …… 
    429429A functional test can contain several requests and more complex assertions; you will soon discover all the possibilities in the upcoming sections. 
    430430 
    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). 
     431To 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). 
    432432 
    433433Listing 15-10 - Launching a Single Functional Test from the Command Line 
    434434 
    435     > symfony test-functional frontend foobarActions 
     435    > php symfony test:functional frontend foobarActions 
    436436 
    437437    # get /comment/index 
    …… 
    738738    $b = new sfTestBrowser('myapp.example.com', '123.456.789.123'); 
    739739 
    740 ### The test-functional Task 
    741  
    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. 
     740### The test:functional Task 
     741 
     742The `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. 
    743743 
    744744Listing 15-27 - Functional Test Task Syntax 
    …… 
    754754 
    755755    ## Run all functional tests for one application, recursively 
    756     > symfony test-functional frontend 
     756    > php symfony test:functional frontend 
    757757 
    758758    ## Run one given functional test 
    759     > symfony test-functional frontend myScenario 
     759    > php symfony test:functional frontend myScenario 
    760760 
    761761    ## Run several tests based on a pattern 
    762     > symfony test-functional frontend my* 
     762    > php symfony test:functional frontend my* 
    763763 
    764764Test Naming Practices 
    …… 
    826826### Executing Tests in a Test Harness 
    827827 
    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. 
     828The `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. 
    829829 
    830830Listing 15-31 - Launching All Tests in a Test Harness 
    831831 
    832     > symfony test-unit 
     832    > php symfony test:unit 
    833833 
    834834    unit/myFunctionTest.php................ok 
    …… 
    843843The 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. 
    844844 
    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. 
     845You 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. 
    846846 
    847847Listing 15-32 - Launching All the Tests of a Project 
    848848 
    849     > symfony test-all 
     849    > php symfony test:all 
    850850 
    851851### Accessing a Database 
    …… 
    862862    $con = Propel::getConnection(); 
    863863 
    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. 
     864You 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. 
    865865 
    866866Listing 15-34 - Populating a Database from a Test File 
    …… 
    978978------- 
    979979 
    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. 
     980Automated 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. 
    981981 
    982982If 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/branches/1.1/book/16-Application-Management-Tools.txt

    r8262 r8283  
    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. 
    …… 
    133133Listing 16-6 - Launching Log Rotation 
    134134 
    135     > symfony --period=7 --history=10 log-rotate frontend prod 
     135    > php symfony log:rotate frontend prod --period=7 --history=10 
    136136 
    137137The backup log files are stored in the `logs/history/` directory and suffixed with the date they were saved. 
    …… 
    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). 
    374  
    375     > symfony propel:data-load --env=prod frontend 
     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). 
     374 
     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 
    …… 
    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. 
    …… 
    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. 
    445  
    446     > symfony unfreeze 
     444To revert a project to its initial state, use the `project:unfreeze` task. It erases the `data/symfony/`, `lib/symfony/`, and `web/sf/` directories. 
     445 
     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. 
    …… 
    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. 
    …… 
    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. 
    530  
    531     > symfony clear-cache 
     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. 
     530 
     531    > php symfony cache:clear 
    532532 
    533533>**TIP** 
    …… 
    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. 
    543  
    544     > symfony enable APPLICATION_NAME ENVIRONMENT_NAME 
     542The `project:enable` task reenables the application and clears the cache. 
     543 
     544    > php symfony project:enable APPLICATION_NAME ENVIRONMENT_NAME 
    545545 
    546546>**SIDEBAR** 
    …… 
    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. 
    552 > 
    553 >     > symfony clear-controllers 
    554 > 
    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). 
    556 > 
    557 >     > symfony fix-perms 
    558  
    559 >**SIDEBAR** 
    560 >Access to the symfony commands in production 
    561 > 
    562 >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: 
    563 > 
    564 > 
    565 >     // With symfony installed via PEAR 
    566 >     > symfony [options] <TASK> [parameters] 
    567 > 
    568 >     // With symfony frozen in the project or symlinked 
    569 >     > php symfony [options] <TASK> [parameters] 
     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. 
     552> 
     553>     > php symfony project:clear-controllers 
     554> 
     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). 
     556> 
     557>     > php symfony project:permissions 
    570558 
    571559Summary 

  • doc/branches/1.1/book/17-Extending-Symfony.txt

    r7705 r8283  
    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. 

  • doc/branches/1.1/book/18-Performance.txt

    r8266 r8283  
    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 
    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. 
    …… 
    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 
    …… 
    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. 

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

    r8281 r8283  
    3434 
    3535  * `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). 
    36   * `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. 
     36  * `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. 
    3737 
    3838To 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. 
    …… 
    5757`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 
    5858`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` 
    59 `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` 
     59`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` 
    6060`compressed`            | Enables PHP response compression. Set it to `on` to compress the outgoing HTML via the PHP compression handler. | `off` 
    6161`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` 
    …… 
    402402    $sf_symfony_data_dir = '/path/to/symfony/data'; 
    403403 
    404 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. 
     404These 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. 
    405405 
    406406This means that you can switch to another installation of symfony by changing the paths to the framework files.