Development

Documentation/zh_CN/book/1.0/03-Running-Symfony (diff)

You must first sign up to be able to contribute.

Changes from Version 1 of Documentation/zh_CN/book/1.0/03-Running-Symfony

Show
Ignore:
Author:
Le.Jiang (IP: 218.80.121.212)
Timestamp:
03/13/07 17:13:51 (11 years ago)
Comment:

page creation

Legend:

Unmodified
Added
Removed
Modified
  • Documentation/zh_CN/book/1.0/03-Running-Symfony

    v0 v1  
     1{{{ 
     2#!WikiMarkdown  
     3Chapter 3 - 运行Symfony 
     4=========================== 
     5 
     6如上章所述, Symfony是由许多PHP文件组成的框架. Symfony的项目需要使用这些文件, 所以安装Symfony其实就是让项目中可以使用这些文件. 
     7 
     8Symfony是基于PHP5的框架. 所以用一下命令确认你安装了正确的版本:  
     9 
     10    > php -v 
     11 
     12    PHP 5.2.0 (cli) (built: Nov 2 2006 11:57:36) 
     13    Copyright (c) 1997-2006 The PHP Group 
     14    Zend Engine v2.2.0, Copyright (c) 1998-2006 Zend Technologies 
     15 
     16如果版本号大于5.0, 你就可以开始安装了, 安装过程将在此章节介绍。. 
     17 
     18安装沙盒(Sandbox) 
     19---------------------- 
     20 
     21如果你只是想要快速安装,试用一下Symfony。 你需要沙盒。 
     22 
     23The sandbox is a simple archive of files. It contains an empty symfony project including all the required libraries (symfony, pake, lime, Creole, Propel, and Phing), a default application, and basic configuration. It will work out of the box, without specific server configuration or any additional packages. 
     24 
     25To install it, download the sandbox archive from [http://www.symfony-project.com/get/sf_sandbox.tgz](http://www.symfony-project.com/get/sf_sandbox.tgz). Unpack it under the root web directory configured for your server (usually `web/` or `www/`). For the purposes of uniformity, this chapter will assume you unpacked it to the directory `sf_sandbox/`. 
     26 
     27>**CAUTION** 
     28>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. 
     29 
     30Test your installation by executing the symfony CLI. Go to the new `sf_sandbox/` directory and type the following on a *nix system: 
     31 
     32    > ./symfony -V 
     33 
     34On Windows, issue this command: 
     35 
     36    > symfony -V 
     37 
     38You should see the sandbox version number: 
     39 
     40    symfony version 1.0.0 
     41 
     42Now make sure that your web server can browse the sandbox by requesting this URL: 
     43 
     44    http://localhost/sf_sandbox/web/frontend_dev.php/ 
     45 
     46You should see a congratulations page that looks like Figure 3-1, and it means that your installation is finished. If not, then an error message will guide you through the configuration changes needed. You can also refer to the "Troubleshooting" section later in this chapter. 
     47 
     48Figure 3-1 - Sandbox congratulations page 
     49 
     50![Sandbox congratulations page](/images/book/F0301.jpg "Sandbox congratulations page") 
     51 
     52The sandbox is intended for you to practice with symfony on a local computer, not to develop complex applications that may end up on the Web. However, the version of symfony shipped with the sandbox is fully functional and equivalent to the one you can install via PEAR. 
     53 
     54To uninstall a sandbox, just remove the `sf_sandbox/` directory from your `web/` folder. 
     55 
     56Installing the Symfony Libraries 
     57-------------------------------- 
     58 
     59When developing an application, you will probably need to install symfony twice: once for your development environment and once for the host server (unless your host already has symfony installed). For each server, you will probably want to avoid duplication by keeping all the symfony files in a single place, whether you develop only one application or several applications. 
     60 
     61Since the symfony framework evolves quickly, a new stable version could very well be released only a few days after your first installation. You need to think of the framework upgrade as a major concern, and that's another reason why you should share one instance of the symfony libraries across all your symfony projects. 
     62 
     63When it comes to installing the libraries for a real application development, you have two alternatives: 
     64 
     65  * The PEAR installation is recommended for most people. It can be easily shared and upgraded, and the installation process is straightforward. 
     66  * The Subversion (SVN) installation is meant to be used only by advanced PHP developers, who want to take advantage of the latest patches, add features of their own, and/or contribute to the symfony project. 
     67 
     68Symfony integrates a few other packages: 
     69 
     70  * pake is a CLI utility. 
     71  * lime is a unit testing utility. 
     72  * Creole is a database abstraction engine. Just like PHP Data Objects (PDO), it provides an interface between your code and the database SQL code, and makes it possible to switch to another engine. 
     73  * Propel is for ORM. It provides object persistence and query service. 
     74  * Phing is a CLI for Propel. 
     75 
     76Pake and lime are developed by the symfony team. Creole, Propel, and Phing come from another team and are released under the GNU Lesser Public General License (LGPL). All these packages are bundled with symfony. 
     77 
     78### Installing the Symfony PEAR Package 
     79 
     80The symfony PEAR package contains the symfony libraries and all its dependencies. It also contains a script that will extend your CLI to include the `symfony` command. 
     81 
     82The first step to install it is to add the symfony channel to PEAR, by issuing this command: 
     83 
     84    > pear channel-discover pear.symfony-project.com 
     85 
     86To see the libraries available in this channel, type the following: 
     87 
     88    > pear remote-list -c symfony 
     89 
     90Now you are ready to install the latest stable version of symfony. Issue this command: 
     91 
     92    > pear install symfony/symfony 
     93 
     94    downloading symfony-1.0.0.tgz ... 
     95    Starting to download symfony-1.0.0.tgz (1,283,270 bytes) 
     96    ................................................................. 
     97    ................................................................. 
     98    .............done: 1,283,270 bytes 
     99    install ok: channel://pear.symfony-project.com/symfony-1.0.0 
     100 
     101That'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: 
     102 
     103    > symfony -V 
     104 
     105    symfony version 1.0.0 
     106 
     107>**TIP** 
     108>If you prefer to install the most recent beta, which has the latest bug fixes and enhancements, type `pear install symfony/symfony-beta` instead. Beta releases are not completely stable and are generally not recommended for production environments. 
     109 
     110The symfony libraries are now installed in directories as follows: 
     111 
     112  * `$php_dir/symfony/` contains the main libraries. 
     113  * `$data_dir/symfony/` contains the skeleton of symfony applications; default modules; and configuration, i18n data, and so on. 
     114  * `$doc_dir/symfony/` contains the documentation. 
     115  * `$test_dir/symfony/` contains unit tests. 
     116 
     117The _dir variables are part of your PEAR configuration. To see their values, type the following: 
     118 
     119    > pear config-show 
     120 
     121### Checking Out Symfony from the SVN Repository 
     122 
     123For production servers, or when PEAR is not an option, you can download the latest version of the symfony libraries directly from the symfony Subversion repository by requesting a checkout: 
     124 
     125    > mkdir /path/to/symfony 
     126    > cd /path/to/symfony 
     127    > svn checkout http://svn.symfony-project.com/tags/RELEASE_1_0_0/ . 
     128 
     129The `symfony` command, available only for PEAR installations, is a call to the `/path/to/symfony/data/bin/symfony` script. So the following would be the equivalent to the `symfony -V` command for an SVN installation: 
     130 
     131    > php /path/to/symfony/data/bin/symfony -V 
     132 
     133    symfony version 1.0.0 
     134 
     135If you chose an SVN installation, you probably already have an existing symfony project. For this project to make use of the symfony files, you need to change the two variables defined in your project's `config/config.php` file, as follows: 
     136 
     137    [php] 
     138    <?php 
     139 
     140    $sf_symfony_lib_dir  = '/path/to/symfony/lib/'; 
     141    $sf_symfony_data_dir = '/path/to/symfony/data/'; 
     142 
     143Chapter 19 proposes other ways to link a project with a symfony installation (including symbolic links and relative paths). 
     144 
     145>**TIP** 
     146>Alternatively, you can also download the PEAR package ([http://pear.symfony-project.com/get/symfony-1.0.0.tgz](http://pear.symfony-project.com/get/symfony-1.0.0.tgz)) and unpack it somewhere. You will have the same result as with a checkout. 
     147 
     148Setting Up an Application 
     149------------------------- 
     150 
     151As you learned in Chapter 2, symfony gathers related applications in projects. All the applications of a project share the same databases. In order to set up an application, you must first set up a project. 
     152 
     153### Creating the Project 
     154 
     155Each symfony project follows a predefined directory structure. The symfony command line automates the creation of new projects by initiating the skeleton of the project, with the proper tree structure and access rights. So to create a project, simply create a new directory and ask symfony to make it a project. 
     156 
     157For a PEAR installation, issue these commands: 
     158 
     159    > mkdir ~/myproject 
     160    > cd ~/myproject 
     161    > symfony init-project myproject 
     162 
     163For an SVN installation, create a project with these commands: 
     164 
     165    > mkdir ~/myproject 
     166    > cd ~/myproject 
     167    > php /path/to/symfony/data/bin/symfony init-project myproject 
     168 
     169The `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. 
     170 
     171Symfony will create a directory structure that looks like this: 
     172 
     173    apps/ 
     174    batch/ 
     175    cache/ 
     176    config/ 
     177    data/ 
     178    doc/ 
     179    lib/ 
     180    log/ 
     181    plugins/ 
     182    test/ 
     183    web/ 
     184 
     185>**TIP** 
     186>The `init-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). 
     187 
     188### Creating the Application 
     189 
     190The project is not yet ready to be viewed, because it requires at least one application. To initialize it, use the `symfony init-app` command and pass the name of the application as an argument: 
     191 
     192    > symfony init-app myapp 
     193 
     194This will create a `myapp/` 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: 
     195 
     196    apps/ 
     197      myapp/ 
     198        config/ 
     199        i18n/ 
     200        lib/ 
     201        modules/ 
     202        templates/ 
     203 
     204Some PHP files corresponding to the front controllers of each default environment are also created in the project `web` directory: 
     205 
     206    web/ 
     207      index.php 
     208      myapp_dev.php 
     209 
     210`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 `myapp.php` (if you now add a new application called `mynewapp`, the new production front controller will be named `mynewapp.php`). To run your application in the development environment, call the front controller `myapp_dev.php`. You'll learn more about these environments in Chapter 5. 
     211 
     212Configuring the Web Server 
     213-------------------------- 
     214 
     215The scripts of the `web/` directory are the entry points to the application. To be able to access them from the Internet, the web server must be configured. In your development server, as well as in a professional hosting solution, you probably have access to the Apache configuration and you can set up a virtual host. On a shared-host server, you probably have access only to an `.htaccess` file. 
     216 
     217### Setting Up a Virtual Host 
     218 
     219Listing 3-1 is an example of Apache configuration, where a new virtual host is added in the `httpd.conf` file. 
     220 
     221Listing 3-1 - Sample Apache Configuration, in `apache/conf/httpd.conf` 
     222 
     223    <VirtualHost *:80> 
     224      ServerName myapp.example.com 
     225      DocumentRoot "/home/steve/myproject/web" 
     226      DirectoryIndex index.php 
     227      Alias /sf /$sf_symfony_data_dir/web/sf 
     228      <Directory "/$sf_symfony_data_dir/web/sf"> 
     229        AllowOverride All 
     230        Allow from All 
     231      </Directory> 
     232      <Directory "/home/steve/myproject/web"> 
     233        AllowOverride All 
     234        Allow from All 
     235      </Directory> 
     236    </VirtualHost> 
     237 
     238In the configuration in Listing 3-1, the `/path/to/symfony/data` placeholder must be replaced by the actual path. For example, for a PEAR installation in *nix, you should type something like this: 
     239 
     240        Alias /sf /usr/local/lib/php/data/symfony/web/sf 
     241 
     242>**NOTE** 
     243>The alias to the `web/sf/` directory is not mandatory. It allows Apache to find images, style sheets, and JavaScript files for the web debug toolbar, the admin generator, the default symfony pages, and the Ajax support. An alternative to this alias would be to create a symbolic link (symlink) or copy the `/path/to/symfony/data/web/sf/` directory to `myproject/web/sf/`. 
     244 
     245Restart Apache, and that's it. Your newly created application can now be called and viewed through a standard web browser at the following URL: 
     246 
     247    http://localhost/myapp_dev.php/ 
     248 
     249You should see a congratulations page similar to the one shown earlier in Figure 3-1. 
     250 
     251>**SIDEBAR** 
     252>URL Rewriting 
     253> 
     254>Symfony uses URL rewriting to display "smart URLs"--meaningful locations that display well on search engines and hide all the technical data from the user. You will learn more about this feature, called routing, in Chapter 9. 
     255> 
     256>If your version of Apache is not compiled with the `mod_rewrite` module, check that you have the `mod_rewrite` Dynamic Shared Object (DSO) installed and the following lines in your `httpd.conf`: 
     257> 
     258> 
     259>    AddModule mod_rewrite.c 
     260>    LoadModule rewrite_module modules/mod_rewrite.so 
     261> 
     262> 
     263>For Internet Information Services (IIS), you will need `isapi/rewrite` installed and running. Check the symfony online documentation for a detailed IIS installation guide. 
     264 
     265### Configuring a Shared-Host Server 
     266 
     267Setting up an application in a shared host is a little trickier, since the host usually has a specific directory layout that you can't change. 
     268 
     269>**CAUTION** 
     270>Doing tests and development directly in a shared host is not a good practice. One reason is that it makes the application visible even if it is not finished, revealing its internals and opening large security breaches. Another reason is that the performance of shared hosts is often not sufficient to browse your application with the debug tools on efficiently. So you should not start your development with a shared-host installation, but rather build your application locally and deploy it to the shared host when it is finished. Chapter 16 will tell you more about deployment techniques and tools. 
     271 
     272Let's imagine that your shared host requires that the web folder is named `www/` instead of `web/`, and that it doesn't give you access to the `httpd.conf` file, but only to an `.htaccess` file in the web folder. 
     273 
     274In a symfony project, every path to a directory is configurable. Chapter 19 will tell you more about it, but in the meantime, you can still rename the `web` directory to `www` and have the application take it into account by changing the configuration, as shown in Listing 3-2. These lines are to be added to the end of the application `config.php` file. 
     275 
     276Listing 3-2 - Changing the Default Directory Structure Settings, in `apps/myapp/config/config.php` 
     277 
     278    [php] 
     279    $sf_root_dir = sfConfig::get('sf_root_dir'); 
     280    sfConfig::add(array( 
     281      'sf_web_dir_name' => $sf_web_dir_name = 'www', 
     282      'sf_web_dir'      => $sf_root_dir.DIRECTORY_SEPARATOR.$sf_web_dir_name, 
     283      'sf_upload_dir'   => $sf_root_dir.DIRECTORY_SEPARATOR.$sf_web_dir_name.DIRECTORY_SEPARATOR.sfConfig::get('sf_upload_dir_name'), 
     284    )); 
     285 
     286The project web root contains an .htaccess file by default. It is shown in Listing 3-3. Modify it as necessary to match your shared host requirements. 
     287 
     288Listing 3-3 - Default `.htaccess` Configuration, Now in `myproject/www/.htaccess` 
     289 
     290    Options +FollowSymLinks +ExecCGI 
     291 
     292    <IfModule mod_rewrite.c> 
     293      RewriteEngine On 
     294 
     295      # we skip all files with .something 
     296      RewriteCond %{REQUEST_URI} \..+$ 
     297      RewriteCond %{REQUEST_URI} !\.html$ 
     298      RewriteRule .* - [L] 
     299 
     300      # we check if the .html version is here (caching) 
     301      RewriteRule ^$ index.html [QSA] 
     302      RewriteRule ^([^.]+)$ $1.html [QSA] 
     303      RewriteCond %{REQUEST_FILENAME} !-f 
     304 
     305      # no, so we redirect to our front web controller 
     306      RewriteRule ^(.*)$ index.php [QSA,L] 
     307    </IfModule> 
     308 
     309    # big crash from our front web controller 
     310    ErrorDocument 500 "<h2>Application error</h2>symfony applicationfailed to start properly" 
     311 
     312You should now be ready to browse your application. Check the congratulation page by requesting this URL: 
     313 
     314    http://www.example.com/myapp_dev.php/ 
     315 
     316>**SIDEBAR** 
     317>Other Server Configurations 
     318> 
     319>Symfony is compatible with other server configurations. You can, for instance, access a symfony application using an alias instead of a virtual host. You can also run a symfony application with an IIS server. There are as many techniques as there are configurations, and it is not the purpose of this book to explain them all. 
     320> 
     321>To find directions for a specific server configuration, refer to the symfony wiki ([http://www.symfony-project.com/trac/wiki](http://www.symfony-project.com/trac/wiki)), which contains many step-by-step tutorials. 
     322 
     323Troubleshooting 
     324--------------- 
     325 
     326If you encounter problems during the installation, try to make the best out of the errors or exceptions thrown to the shell or to the browser. They are often self-explanatory and may even contain links to specific resources on the Web about your issue. 
     327 
     328### Typical Problems 
     329 
     330If you are still having problems getting symfony running, check the following: 
     331 
     332  * Some PHP installations come with both a PHP 4 and a PHP 5 command. In that case, the command line is probably `php5` instead of `php`, so try calling `php5 symfony` instead of the `symfony` command. You may also need to add `SetEnv PHP_VER 5` to your `.htaccess` configuration, or rename the scripts of the `web/` directory from `.php` to `.php5`. The error thrown by a PHP 4 command line trying to access symfony looks like this: 
     333 
     334        Parse error, unexpected ',', expecting '(' in .../symfony.php on line 19. 
     335 
     336  * The memory limit, defined in the `php.ini`, must be set to `16M` at least. The usual symptom for this problem is an error message when installing symfony via PEAR or using the command line. 
     337 
     338        Allowed memory size of 8388608 bytes exhausted 
     339 
     340  * The `zend.ze1_compatibility_mode` setting must be set to `off` in your `php.ini`. If it is not, trying to browse to one of the web scripts will produce an "implicit cloning" error: 
     341 
     342        Strict Standards: Implicit cloning object of class 'sfTimer'because of 'zend.ze1_compatibility_mode' 
     343 
     344  * The `log/` and `cache/` directories of your project must be writable by the web server. Attempts to browse a symfony application without these directory permissions will result in an exception: 
     345 
     346        sfCacheException [message] Unable to write cache file"/usr/myproject/cache/frontend/prod/config/config_config_handlers.yml.php" 
     347 
     348  * The include path of your system must include the path to the `php` command, and the include path of your `php.ini` must contain a path to PEAR (if you use PEAR). 
     349  * Sometimes, there is more than one `php.ini` on a server's file system (for instance, if you use the WAMP package). Call `phpinfo()` to know the exact location of the `php.ini` file used by your application. 
     350 
     351>**NOTE** 
     352>Although it is not mandatory, it is strongly advised, for performance reasons, to set the `magic_quotes_gpc` and `register_globals` settings to `off` in your `php.ini`. 
     353 
     354### Symfony Resources 
     355 
     356You can check if your problem has already happened to someone else and find solutions in various places: 
     357 
     358  * The symfony installation forum ([http://www.symfony-project.com/forum/](http://www.symfony-project.com/forum/)) is full of installation questions about a given platform, environment, configuration, host, and so on. 
     359  * The archives of the users mailing-list ([http://groups.google.fr/group/symfony-users](http://groups.google.fr/group/symfony-users)) are also searchable. You may find similar experiences to your own there. 
     360  * The symfony wiki ([http://www.symfony-project.com/trac/wiki#Installingsymfony](http://www.symfony-project.com/trac/wiki#Installingsymfony)) contains step-by-step tutorials, contributed by symfony users, about installation. 
     361 
     362If you don't find any answer, try posing your question to the symfony community. You can post your query in the forum, the mailing list, or even drop to the `#symfony` IRC channel to get feedback from the most active members of the community. 
     363 
     364Source Versioning 
     365----------------- 
     366 
     367Once the setup of the application is done, starting a source versioning (or version control) process is recommended. Source versioning keeps track of all modifications in the code, gives access to previous releases, facilitates patching, and allows for efficient team work. Symfony natively supports CVS, although Subversion ([http://subversion.tigris.org/](http://subversion.tigris.org/)) is recommended. The following examples show the commands for Subversion, and assume that you already have a Subversion server installed and that you wish to create a new repository for your project. For Windows users, a recommended Subversion client is TortoiseSVN ([http://tortoisesvn.tigris.org/](http://tortoisesvn.tigris.org/)). For more information about source versioning and the commands used here, consult the Subversion documentation. 
     368 
     369The following example assumes that `$SVNREP_DIR` is defined as an environment variable. If you don't have it defined, you will need to substitute the actual location of the repository in place of `$SVNREP_DIR`. 
     370 
     371So let's create the new repository for the `myproject` project: 
     372 
     373    > svnadmin create $SVNREP_DIR/myproject 
     374 
     375Then the base structure (layout) of the repository is created with the `trunk`, `tags`, and `branches` directories with this pretty long command: 
     376 
     377    > svn mkdir -m "layout creation" file:///$SVNREP_DIR/myproject/trunk file:///$SVNREP_DIR/myproject/tags file:///$SVNREP_DIR/myproject/branches 
     378 
     379This will be your first revision. Now you need to import the files of the project except the cache and log temporary files: 
     380 
     381    > cd ~/myproject 
     382    > rm -rf cache/* 
     383    > rm -rf log/* 
     384    > svn import -m "initial import" . file:///$SVNREP_DIR/myproject/trunk 
     385 
     386Check the committed files by typing the following: 
     387 
     388    > svn ls file:///$SVNREP_DIR/myproject/trunk/ 
     389 
     390That seems good. Now the SVN repository has the reference version (and the history) of all your project files. This means that the files of the actual `~/myproject/` directory need to refer to the repository. To do that, first rename the `myproject/` directory--you will erase it soon if everything works well--and do a checkout of the repository in a new directory: 
     391 
     392    > cd ~ 
     393    > mv myproject myproject.origin 
     394    > svn co file:///$SVNREP_DIR/myproject/trunk myproject 
     395    > ls myproject 
     396 
     397That's it. Now you can work on the files located in ~`/myproject/` and commit your modifications to the repository. Don't forget to do some cleanup and erase the `myproject.origin/` directory, which is now useless. 
     398 
     399There is one remaining thing to set up. If you commit your working directory to the repository, you may copy some unwanted files, like the ones located in the `cache` and `log` directories of your project. So you need to specify an ignore list to SVN for this project. You also need to set full access to the `cache/` and `log/` directories again: 
     400 
     401    > cd ~/myproject 
     402    > chmod 777 cache 
     403    > chmod 777 log 
     404    > svn propedit svn:ignore log 
     405    > svn propedit svn:ignore cache 
     406 
     407The default text editor configured for SVN should launch. If this doesn't happen, make Subversion use your preferred editor by typing this: 
     408 
     409    > export SVN_EDITOR=<name of editor> 
     410    > svn propedit svn:ignore log 
     411    > svn propedit svn:ignore cache 
     412 
     413Now simply add all files from the subdirectories of `myproject/` that SVN should ignore when committing: 
     414 
     415    * 
     416 
     417Save and quit. You're finished. 
     418 
     419Summary 
     420------- 
     421 
     422To test and play with symfony on your local server, your best option for installation is definitely the sandbox, which contains a preconfigured symfony environment. 
     423 
     424For a real development or in a production server, opt for the PEAR installation or the SVN checkout. This will install the symfony libraries, and you still need to initialize a project and an application. The last step of the application setup is the server configuration, which can be done in many ways. Symfony works perfectly fine with a virtual host, and it is the recommended solution. 
     425 
     426If you have any problems during installation, you will find many tutorials and answers to frequently asked questions on the symfony website. If necessary, you can submit your problem to the symfony community, and you will get a quick and effective answer. 
     427 
     428Once your project is initiated, it is a good habit to start a version-control process. 
     429 
     430Now that you are ready to use symfony, it is time to see how to build a basic web application. 
     431}}}