symfony 中文文档（进行中……）

关于 symfony
Symfony 是一个基于PHP5的开源web 框架（framework）。基于丰富的web开发实践，已经用于多个网站应用。Symfony 以快速创建可维护的web应用、改变重复的代码编写为高效、可控、有趣的工作为目标。

如果你一直在寻找一个像Rails/Django 框架（framework）的php项目，而且具有以下特性：
    简单的模版与帮助
    缓存管理
    多平台支持
    开发管理
    scaffolding
    友好的URLs (smart URLs)
    multilingual 与国际化支持（I18N support）
    面向对象与MVC
    Ajax支持
…where all elements work seamlessly together,then symfony is made for you.
所有这些特性的集成，那么symfony正适合你。

symfony仅需要很少的准备就可轻松安装于任何配置下。你只需要Unix或Windows系统下一个配置了PHP5的web服务器。他几乎与所有的数据库系统兼容。另外，symfony的管理费用很小，所以它的优点是不会增加主机开销。（so the benefits of the framework don't come at the cost of an increase in hosting costs.）

对于习惯于PHP和应用程序设计模式的人使用symfony 会非常简单而自然，他们的学习曲线不超过一天。Symfony简洁的设计与易读的代码将使你快速上手（delays short）。开发者可以使用灵活的规划规则（development principles）(such as DRY, KISS or the XP philosophy)，专注于应用逻辑和避免浪费时间书写无数的XML配置文件。

Symfony is aimed at building robust applications in an enterprise context. This means that you have full control over the configuration: from the directory structure to the foreign libraries, almost everything can be customized. To match your enterprise's development guidelines, symfony is bundled with additional tools to
help you test, debug and document your project.
Symfony 的目标是为企业（an enterprise context）构建高效的应用软件。也就是说你可以通过配置而完全控制：从目录结构到外部库，几乎所有的都可以用户化。为了适应你的企业发展规划，symfony 捆绑了附加工具可以帮助你测试、调试、文档化你的项目。

Last but not least, by choosing symfony you get the benefits of an active open-source community. It is entirely free and published under the MIT license.

Symfony 由 Sensio 发起，Sensio，一个法国web代理，以在web发展方面的创新观点而闻名。

Symfony简介

概要

Symfony是一个基于MVC模型的面向对象的PHP5框架（framework）。Symfony可以帮助你将web应用程序的业务逻辑、服务器端逻辑和页面显示分开。它也包含了许多的工具和类，这些工具和类可以帮助你缩短开发复杂web应用程序的时间。

什么是框架（framework）？

A framework adds new mechanisms on top of a programming language, and these mechanisms automate many of the development patterns used for a given purpose. A framework also adds structure to the code, and pushes the developer to write better, more readable and maintainable code. A framework also makes programming easier, since it packages complex operations into simple statements.

框架在编程语言之上替我们添加一些机制，这些机制可以帮助我们自动应用各种开发模式以更好的实现某些给定的开发目标。框架也会很好的架构我们的代码，推动开发者写出更好的、更易读的并且可维护的代码。由于框架将一些复杂操作封装在了一些简单的语句里，所以它可以使我们的开发更加简单。

由于框架的目的一般都是对所基于的编程语言进行一定扩展，所以它一般采用原编程语言，并且扩展之。一个PHP5的框架就是一批用PHP5写成的文件。

A framework will add layering to an application. In general, they divide applications in three layers:

框架一般都会将应用程序分层。一般来讲，它一般会将应用程序分为如下三层：

The presentation logic handles the interactions between the user and the software
表现层逻辑处理用户和应用程序之间的交互。
The data source logic carries the access to a database or other data providers
数据源逻辑处理所有与数据库或者其他数据提供者的交互。
The domain logic, or business logic, is the remaining piece. It involves calculation made on inputs, manipulation of data from the presentation, and dispatching of data source logic according to the commands received from the presentation.
领域逻辑，或者叫业务逻辑，这是留下来让你填写的地方。它包括计算用户输入，处理表现层的数据，根据表现层命令执行相应的数据源逻辑等。
Web application frameworks intend to facilitate the development of... web applications (websites, Intranets, etc.). Building a basic dynamic website can be easily achieved with existing programming languages, and PHP is known for its simplicity and broadly adopted for that purpose. With PHP alone, you can already query a database, manage session cookies, access files in the server, etc. But when it comes to building a more complex website, where business logic increases the volume of code to maintain, the need of a web application framework arises.

Web应用程序框架的目的就是想要简化各种Web应用程序的开发（包括网站，内网应用程序等）。用现存的编程语言当然可以比较轻松的建造基本的动态网站，比如PHP就是因其的简单性和广泛采用性而被大家所熟知。仅用PHP，你就可以查询数据库，管理session cookies，访问服务器上的文件，等等。但是，当你需要开发一个比较复杂的网站时，当由于业务代码的激增而导致有大量代码需要维护时，web应用程序框架的重要性就体现出来。


什么是symfony？

Symfony is a complete framework designed to help and speedup the development of web applications.

Symfony完全是为了帮助和加速web应用程序的开发而设计的。

It is based on the following concepts:

它基于如下的概念：

compatible with as many environments as possible
尽可能的兼容所有的应用环境
easy to install and configure
简单安装和配置
simple to learn
易于学习
enterprise ready
支持企业开发
convention rather than configuration, supporting fallback calls
依靠惯例而不是配置，支持回滚调用[i1]  
simple in most cases, but still flexible enough to adapt to complex cases
尽量使多数情况简单，但是当需要复杂时，依然能够支持
most common web features included
包括大多数通用的web特性
compliant with most of the web "best practices" and web "design patterns"
遵从大多数的web最佳实践和web设计模式
very readable code with easy maintenance
非常易读的代码，非常高的可维护性
open source
开源
The main concept underlying the symfony framework is that the most common tasks are done automatically so that the developer can focus entirely on the specifics of an application. There is no need to reinvent the wheel every time a new web application is built.

隐藏在symfony框架背后的最重要的思想就是越多的普通的工作由计算机来自动完成，开发者就可以更加完全的投入自己的精力于应用程序中那些更需要投入精力的特殊的地方。每次打造一个新的Web应用时，你都不需要重新发明轮子了。

To fulfill these requirements, symfony was written entirely in PHP5. It has been thoroughly tested in various real world projects, and is actually in use for high demand e-business websites. It is compatible with most of the available databases, among which:

为了完成这样的需求，symfony全部是用PHP5编写的。他已经被各式各样的真实地项目所完全测试，并且已经在一些高要求的电子商务网站中应用。它可以兼容几乎所有已知的数据库，比如：

MySQL
PostgreSQL
Oracle
MSSQL
and any other database if a Creole driver exists for it
任何其他的数据库，只要它具备Creole驱动
The symfony object model relies on three distinct layers:

Symfony的对象模型依赖于如下三个独特的层次：

a database abstraction
一个数据库抽象层
an object-relational mapping
一个对象-关系映射层
a Model-View-Controller model for the front and back-office
一个Model-View-Controller模型用来支持前端和后端的应用
Common features of web projects are made easy since Symfony natively automates them:

由于Symfony替你自动化了许多操作，所以一些通用的Web项目的特性将非常容易的被支持

internationalization
国际化
templating with helpers
templating with helpers[i2]  
form validation
表单验证
cache management
缓存管理
shopping cart management
购物车管理
smart URLs
智能URLs
Scaffolding
Scaffolding[i3]  
email sending
邮件发送
Pagination
分页支持
AJAX interactions
Ajax式交互
In addition, to fulfill the requirements of enterprises having their own coding guidelines and project management rules, symfony can be entirely reconfigured using YAML configuration files. It provides by default, several development environments, and is bundled with tools to easily achieve the following operations:

另外，由于企业开发有其自身的代码规范和项目管理规则，为了满足该需求，symfony可以用YAML配置文件来完全重新配置。一般的，它提供许多开发环境，并且绑定了一批工具来完成如下的操作：

prototyping
prototyping[i4]  
content management
内容管理
live configuration changes
在线配置变更
deployment
部署
unit testing
单元测试
applicative testing
可用性测试
logging
logging[i5]  
debugging
调试
Symfony uses some code fragments of other open source projects:

Symfony采用了一些其他的开源项目的代码片断；

Creole, for the database abstraction layer
Creole，为数据抽象层
Propel, for the object-relational mapping layer
Propel，为对象-关系映射层
Mojavi, for the Model-View-Controller model layer
Mojavi，为Model-View-Controller模型层
Is symfony made for me?

Symfony适合我吗？

Whether you are a PHP5 expert or a beginner in web application programming doesn't matter. The main factor that should direct your decision is the size of your project.

无论你是一个PHP5的高手或者是一个Web应用程序开发的初学者，都不要紧。决定Symfony是否适合你的关键因素是你需要开发的项目的大小。

If you want to develop a simple website with five to ten pages, having limited access to a database and no obligation for performance, availability or documentation, then you should stick with PHP alone. You wouldn't take much advantage of the features of a web application framework, and using object orientation or a MVC model would only slow down your development. Symfony is not optimized to run efficiently on a shared server with only CGI support.

如果你只是希望开发一个简单的只有5页或者10页的网站，仅仅需要简单的访问一下数据库，也不需要关注性能、可用性和文档化，那么你用PHP就可以了。这种情况即使你使用web应用程序框架也不会给你带来多大的好处。相反，面向对象的特性和MVC模型还有可能减慢你的开发。Symfony并不是为那些运行在共享服务器上，仅支持CGI的简单、高效应用而设计的。[i6]

On the other hand, if you develop bigger web applications, with a heavy business logic, PHP alone is not enough. If you plan to maintain or extend your application in the future, you will need your code to be lightweight, readable and performant. If you want to use the latest advances in user interaction (like AJAX) in an intuitive way, you can't just write hundreds of lines of Javascript. If you want to have fun and develop fast, then PHP alone will probably be disappointing. For all these cases, symfony is made for you.

反之，如果你正要开发一个较大型的项目，由大量的业务逻辑需要处理，那么仅仅有PHP就不够了。如果你打算在未来维护或者扩展你的应用程序，那么你需要让你的代码保持轻量级，可读并且高性能。如果你想用一种比较直接的方式采用一些最新技术在用户交互方面的优势，如Ajax，而不用编写成千上万行的Javascript代码。如果你想让开发高效并且充满乐趣，那么仅采用PHP进行开发将会令你失望。如果你碰到了上述所有情况的一种，那么，symfony就是为你而生的！

And of course, if you are a profesional web developer, you already know all the benefits of web application frameworks, and you need one which is mature, well documented, and with a large community. Search no more, for symfony is your solution.

当然，如果你是一个专业的web开发者，你当然已经知道了web应用程序框架的优势，你所需要的是一个成熟的，有良好文档支持的，有一个大型交互社区的框架。不用再寻找了，symfony就是合适你的解决方案!



Translated by coofucoo

4/19/2006


--------------------------------------------------------------------------------



[i1]该处翻译可能不准确。



[i2]无法翻译。



[i3]无法翻译。



[i4]无法翻译。



[i5]无需翻译。



[i6]看来CGI比较合适效率高，但是复杂度不高的情况。



Installing symfony
安装 symfony
Overview
概要
This chapter describes the steps to install the symfony framework, either from a 'sandbox' archive, from a PEAR package or manually from the source repository.
本章叙述symfony框架的安装步骤。包括从’sandbox’归档、从 pear 包 或者 从源仓库手动几种情况的安装。
Introduction
导言
The symfony framework is a set of files written in PHP. A project based on symfony uses these files, so installing symfony means getting these files and making them available for your project.

symfony框架就是用PHP5写成的文件集合。一个基于symfony的项目就是用这些文件，所以安装symfony就意味着获得这些文件并是他们对你的项目可用。

Symfony can be used for one or many projects. If you work on a single project, you may want to embed the framework within the application you develop. On the other hand, if you choose to use symfony for more than one project, you will prefer to keep all the symfony files in one single place to make the upgrade easier.

Symfony 可用于一个或多个项目。如果你用于一个单独的项目，你可能想把symfony框架嵌入你的应用程序之中。另一方面，如果你选择用symfony用于多个项目，那么为了升级方便你更喜欢将所有的symfony文件置于一个单独的地方。

In addition, when developing an application, you will probably need to install symfony twice: Once for your development environment, and once for the host server (unless your hosts already has symfony installed).
另外，当开发一个应用时，你可能需要两次安装symfony，一次用于开发环境，一次用于主机服务器(除非你的主机已经安装了symfony)。

All these different needs have different answers, that's why you have several alternatives to install symfony:

The sandbox is an empty symfony project where all the required libraries are already included, and where the basic configuration is already done. It is made mostly for symfony beginners, who want to play with the framework or try the tutorials without installing anything.
·sandbox 是一个包含了所有必需的库的空symfony 项目，并且基本配置都已经完成。这通常是为那些想体验一下symfony框架或者试验该指南而没有安装symfony的初学者准备的。

The PEAR installation is recommended to those who want to run several symfony-based projects, with an easy way to upgrade. It requires PEAR version 1.4.0 or higher, which is bundled in most PHP distributions.
·
The manual installation is meant to be used only by advanced PHP developers, who what to take advantage of the latest patches or add features of their own.
·
Note that the symfony framework evolves quickly, and that a new stable version can come out only a few days after your first installation. You have to think of the framework upgrade as a major concern, and that's why the first solution is not recommended if you develop a website for real. In fact, an application developed with the sandbox can not be upgraded easily.

Prerequisites
预备条件
In order to use symfony, you need to have PHP5 and a web server installed. If you want to use the PEAR install, you will also need PEAR. If you plan on using persistent data, a database will be needed. Symfony is compatible with MySQL, PostgreSQL, Oracle, MSSQL, and any other database having a Creole driver.
Note: You can find many LAMP packages offered for download, which contain the Apache
server, the MySQL database and PHP all bundled together and configured for a given
platform (XAMPP for many platforms, MAMP for Macintosh, WAMP for Windows, etc.). If you don't have PHP5 installed, they are probably the best option for you to start.