Как стало ясным из предыдущих глав, фреймворк symfony - это совокупность файлов, написанных на PHP. Их использует проект symfony. Установить symfony означает получить эти файлы и сделать их доступными для проекта.

Symfony нужен PHP5, так как фреймворк написан на PHP5. Убедится в том, что PHP установлен, можно набрав в консоли команду:

>php -v

PHP 5.2.0 (cli) (built: Nov 2 2006 11:57:36)
Copyright (c) 1997-2006 The PHP Group
Zend Engine v2.2.0, Copyright (c) 1998-2006 Zend Technologies

Если версия не ниже 5.0, то вы готовы к установке, которая описывается в этой главе.

Установка Sandbox

NOTE sandbox — (англ.) песочница для детских игр

Если вы хотите увидеть, на что способен symfony, возможно, понадобится быстрая установка. В таком случае, вам подойдет sandbox.

Sandbox - это обыкновенный архив. Он содержит пустой проект symfony и включает в себя все необходимые библиотеки (symfony, pake, lime, Creole, Propel и Phing), стандартное приложение (default application) и базовую конфигурацию. Для работы sandbox-версии не нужны какие либо специфические настройки сервера или дополнительные пакеты.

Для установки скачайте sandbox архив по ссылке http://www.symfony-project.com/get/sf_sandbox.tgz и распакуйте в корневую web директорию вашего сервера (обычно web/ или www/; проще говоря, в директорию, на которую указывает DocumentRoot). Для простоты изложения будем считать, что архив был распакован в директорию sf_sandbox/.

CAUTION Все файлы содержатся в корневой web директории — это нормально для рабочей машины (localhost), но плохо для реального сервера. Ведь тогда вся начинка приложения доступна пользователю.

Убедиться в успешной установке можно через интерфейс командной строки, который предоставляет symfony. Зайдите в свежесозданную директорию sf_sandbox/ и наберите следующие команды:

Для *nix систем:

> ./symfony -V

Для Windows:

> symfony -V

Вы должны увидеть номер версии sandbox:

symfony version 1.0.0

Теперь можно убедиться, что сервер настроен правильно, запросив URL:

http://localhost/sf_sandbox/web/frontend_dev.php/

Вы должны увидеть поздравительную страницу (congratulations page), изображненную на Рисунке 3-1. Это означает что установка завершена. Если странички нет, сообщение об ошибке подскажет, какие изменения в настройках необходимы. Также можно обратиться к разделу "Устранение неисправностей" этой главы.

Рисунок 3-1 – Поздравительная страница sandbox

Sandbox предназначен для тренировки с symfony на локальной машине, а не для разработки сложных приложений, которые должны реально работать в сети. Однако, версия symfony, заключенная в sandbox, полнофункциональна и эквивалентна версии, которую можно установить через PEAR.

Чтобы удалить sandbox, просто удалите директорию sf_sandbox/.

Установка Библиотек Symfony

Когда вы будете разрабатывать приложение, вам, возможно, понадобится установить symfony дважды: один раз на рабочую машину (development environment), и еще один раз на хостинг (host server). Для каждого случая, можно избежать повторений, и хранить все файлы symfony в одном месте, независимо от того, разрабатывайте вы одно приложение или несколько.

Symfony развивается очень быстро, новая стабильная версия (stable version) может появится всего через несколько дней после вашей первой установки фреймворка. И в ваших интересах как можно быстрее обновить (upgrade) symfony. Это еще одна причина, по которой все проекты должны использовать один экземпляр библиотек symfony.

Для реальной разработки установить библиотеки можно двумя способами:

• Установка через PEAR, рекомендуется в большинстве случаев. Библиотеки легко обновлять и они могут быть используемы несколькими проектами сразу. Процесс установки — простой.
• Установка через Subversion (SVN) подразумевает, что вы опытный PHP разработчик, который хочет использовать преимущества последних патчев (patch), добавлять в фреймворк свои возможности (feature), и/или помогать развивать symfony.

Symfony интегрирует несколько других пакетов:

• pake, это CLI утилита.
• lime, утилита для юнит тестирования.
• Creole это database abstraction layer. Как и PHP Data Objects (PDO), он является прослойкой между кодом разработчика и SQL запросами к базе. Благодаря Creole в любой момент можно перейти на другую базу данных.
• Propel — ORM. Благодаря Propel запросы к базе осуществляются на «объектном» языке.
• Phing, CLI для Propel.

Pake и lime разработаны командой symfony. Creole, Propel, и Phing сделаны другой командой и выпущены с лицензией GNU Lesser Public General License (LGPL). Symfony связан со всеми этими пакетами.

Установка Symfony через PEAR

Пакет symfony в PEAR содержит библиотеки symfony, и все, от чего они зависят. Он также содержит скрипт, который расширит возможности CLI, добавив команды symfony. Первый шаг установки — найти канал symfony в PEAR с помощью команды:

> pear channel-discover pear.symfony-project.com

Чтобы посмотреть список библиотек, доступных через этот канал, воспользуйтесь командой:

> pear remote-list -c symfony

Теперь вы готовы установить последнюю стабильную версию symfony (stable version). Введите команду:

> pear install symfony/symfony

downloading symfony-1.0.0.tgz ...
Starting to download symfony-1.0.0.tgz (1,283,270 bytes)
.................................................................
.................................................................
.............done: 1,283,270 bytes
install ok: channel://pear.symfony-project.com/symfony-1.0.0

Вот и все. Файлы symfony и CLI теперь установлены. Убедится в том, что установка прошла успешно, можно, запросив версию фреймворка через команду консоли:

> symfony -V

symfony version 1.0.0

TIP Если вы хотите установить бета версию, с самыми свежими исправлениями и улучшениями, следует использовать команду pear install symfony/symfony-beta вместо pear install symfony/symfony. Бета версии не вполне стабильны, и не рекомендуются для установки на реальные сервера.

Библиотеки symfony будут установлены в следующие директории:

• $php_dir/symfony/ содержит основные библиотеки.
• $data_dir/symfony/ содержит базовую структуру для приложений symfony; стандартные модули (default modules); настройки, данные i18n, и пр.
• $doc_dir/symfony/ содержит документацию.
• $test_dir/symfony/ содержит юнит тесты.

Переменные _dir являются частью настроек PEAR. Чтобы увидеть значения переменных воспользуйтесь командой:

> pear config-show

Установка Symfony из SVN Репозитория

Для реальных серверов (production server), если вы решили отказаться от PEAR, можно скачать последнюю версию библиотек symfony напрямую из Subversion репозитория symfony, воспользовавшись командой checkout:

> mkdir /path/to/symfony
> cd /path/to/symfony
> svn checkout http://svn.symfony-project.com/tags/RELEASE_1_0_0/ .

Команды symfony, доступные в случае установки через PEAR, фактически вызывают скрипт /path/to/symfony/data/bin/symfony. То есть следующее будет эквивалентным команде symfony –V :

> php /path/to/symfony/data/bin/symfony -V

symfony version 1.0.0

Если вы выбрали установку через SVN, то, возможно, у вас уже есть проект symfony. Для того, чтобы проект мог использовать все необходимые библиотеки, нужно задать две переменные в файле config/config.php, как показано ниже:

[php]
<?php

$sf_symfony_lib_dir  = '/path/to/symfony/lib/';
$sf_symfony_data_dir = '/path/to/symfony/data/';

В Главе 19 описываются другие способы указать проекту на файлы symfony (в том числе через symbolic link и relative path)

TIP Вы также можете скачать PEAR пакет (http://pear.symfony-project.com/get/symfony-1.0.0.tgz) и распаковать его. Результат будет таким же, как если бы вы сделали checkout.

Создание Приложения

Как стало ясно из Главы 2, связанные между собой приложения содержатся в одном проекте. Все приложения проекта используют базу данных. Для того, чтобы создать приложение, сначала нужно создать проект.

Создание Проекта

Любой проект symfony имеет определенную файловую структуру. Благодаря командам консоли создание проекта автоматизировано — symfony сам построит дерево директорий и выставит права доступа. Чтобы создать проект, нужно создать новую директорию и воспользоваться командой symfony.

В случае установки через PEAR следует использовать такие команды:

> mkdir ~/myproject
> cd ~/myproject
> symfony init-project myproject

Если symfony установлен через SVN, то создать проект можно с помощью таких команд:

> mkdir ~/myproject
> cd ~/myproject
> php /path/to/symfony/data/bin/symfony init-project myproject

Команды symfony следует вызывать из корневой директории проекта (myproject/ в предыдущих примерах), поскольку выполняемые командой действия касаются конкретного проекта.

Symfony создаст следующие директории:

apps/
batch/
cache/
config/
data/
doc/
lib/
log/
plugins/
test/
web/

TIP Команда init-project добавит скрипт symfony в корень проекта. Этот php скрипт делает то же, что и команды symfony, установленные через PEAR. Теперь вы можете вызывать php symfony вместо symfony, если использовать команды консоли symfony нельзя (в случае установки через SVN).

Создание Приложения (Application)

Пока что проект пуст и смотреть в нем нечего. Нужно создать хотя бы одно приложение (application). Чтоб инициализировать приложение (application), используйте команду symfony init-app, дописав в качестве аргумента имя:

> symfony init-app myapp

Эта команда создаст директорию myapp/ в папке apps/, со стандартным набором поддиректорий и конфигурационными файлами, которые содержат настройки приложения по умолчанию:

apps/
  myapp/
    config/
    i18n/
    lib/
    modules/
    templates/

Также в папке web/ будут созданы два PHP файла, соответствующее двум фронт-контроллерам (front controller) — по одному на режим:

web/
  index.php
  myapp_dev.php

Index.php - это фронт-контроллер свежесозданного приложения, соответствующий рабочей среде (production front controller). Так как myapp - это первое приложение, symfony создал файл index.php вместо myapp.php (В дальнейшем, если вы, например, создадите приложение newmyapp, новый рабочий фронт-контроллер будет называться newmyapp.php). Для того, чтобы запустить приложение в режиме разработки (development environment), запустите myapp_dev.php. Вы узнаете больше об этих режимах в Главе 5.

Приведу здесь переводы терминов:

Production environment — рабочяя среда, рабочий режим

Development environment — среда разработки, режим разработки

переводчик

Настройка Веб Сервера

Скрипты, хранящиеся в директории web/, - это точки входа в приложение. Для того, чтоб пользователь мог достичь их из Internet, необходимо настроить веб сервер. На вашем сервере разработки, так же как и на профессиональных хостингах, у вас, возможно, есть доступ к настройкам Apache, и вы можете настроить свой виртуальный хост (virtual host). Но в случае shared-host сервера вы располагаете только файлом .htaccess.

Настройка Виртуального Хоста

В листинге 3-1 приведен пример добавления нового виртуального хоста (virtual host) для сервера Apache.

Листинг 3-1 – Пример настроек Apache, в файле apache/conf/httpd.conf

<VirtualHost *:80>
  ServerName myapp.example.com
  DocumentRoot "/home/steve/myproject/web"
  DirectoryIndex index.php
  Alias /sf /$sf_symfony_data_dir/web/sf
  <Directory "/$sf_symfony_data_dir/web/sf">
    AllowOverride All
    Allow from All
  </Directory>
  <Directory "/home/steve/myproject/web">
    AllowOverride All
    Allow from All
  </Directory>
</VirtualHost>

В листинге 3-1, путь /path/to/symfony/data нужно заменить на реальный путь. Например, в случае PEAR установки и *nix системы будет что-то вроде этого:

    Alias /sf /usr/local/lib/php/data/symfony/web/sf

NOTE Прописывать alias для директории web/sf/ не обязательно. Но этот alias позволит Apache находить изображения, таблицы стилей и .js файлы. Все это понадобится для панели отладки, генератора админинтерфейса, стандартных страничек symfony и для использования Ajax. Как альтернатива alias, можно создать символическую ссылку (symbolic link, symlink), или же скопировать директорию /path/to/symfony/data/web/sf/ в myproject/web/sf/.

Осталось только перезапустить Apache - и все. Новое приложение можно вызвать, набрав в браузере URL:

http://localhost/myapp_dev.php/

Вы должны увидеть поздравительную страницу, похожую на ту, что была приведена выше на Рисунке 3-1.

SIDEBAR URL Rewriting

Symfony использует URL rewriting для отображения «красивых url» (smart URLs) — осмысленные адреса, удобные для поисковых машин (search engine), скрывают всю техническую информацию от пользователя. Подробнее об этой возможности (routing) в Главе 9.

Если ваш Apache скомпилирован без модуля mod_rewrite, убедитесь, что у вас есть установленный mod_rewrite Dynamic Shared Object (DSO), и следующие строки присутствуют в httpd.conf:

AddModule mod_rewrite.c LoadModule rewrite_module modules/mod_rewrite.so

Для Internet Information Services (IIS) вам понадобится установленный и запущенный isapi/rewrite. Детальная инструкция по установке для IIS доступна на сайте проекта.

Настройка Shared-Host Сервера

Установка приложения на shared-host чуть сложнее, так как структура директорий фиксирована и вы не можете ее поменять.

CAUTION Заниматься разработкой и тестированием непосредственно на shared-host — плохая привычка. Одна из причин — приложение еще не закончено, но уже доступно извне. Это открывает внутреннюю работу и делает видимыми дыры в системе безопасности (security). Еще одна причина — shared-host часто не обеспечивает достаточного быстродействия для работы над приложением с использованием инструментов отладки. Вы не должны начинать разработку с установки на shared-host, лучше работать над приложением на своей локальной машине и после того, как проект будет закончен, установить его на shared-host. Глава 16 описывает методы и средства установки проекта на реальные сервера.

Представим на минутку, что web директория на shared-host называется www/ вместо web/, и что у вас есть доступ только к файлу .htaccess, но не к httpd.conf.

К счастью, в проекте symfony любой путь к директории можно задать. Глава 19 расскажет больше об этом. В нашем же случае мы можем поменять имя web директории с web/ на www/, и соответственно перенастроить проект, как показано в листинге 3-2. Эти строки должны быть добавлены в конец файла config.php.

Листинг 3-2 – Изменение настроек структуры директорий, в файле apps/myapp/config/config.php

[php]
$sf_root_dir = sfConfig::get('sf_root_dir');
sfConfig::add(array(
  'sf_web_dir_name' => $sf_web_dir_name = 'www',
  'sf_web_dir'      => $sf_root_dir.DIRECTORY_SEPARATOR.$sf_web_dir_name,
  'sf_upload_dir'   => $sf_root_dir.DIRECTORY_SEPARATOR.$sf_web_dir_name.
 DIRECTORY_SEPARATOR.sfConfig::get('sf_upload_dir_name'),
));

По умолчанию web директория проекта содержит файл .htaccess. Содержимое файла приведено в листинге 3-3. Изменяйте его по мере необходимости, для того чтоб ваш проект соответствовал правилам shared-host.

Листинг 3-3 – Содержимое .htaccess, в myproject/www/.htaccess

Options +FollowSymLinks +ExecCGI

<IfModule mod_rewrite.c>
  RewriteEngine On

  # we skip all files with .something
  RewriteCond %{REQUEST_URI} \..+$
  RewriteCond %{REQUEST_URI} !\.html$
  RewriteRule .* - [L]

  # we check if the .html version is here (caching)
  RewriteRule ^$ index.html [QSA]
  RewriteRule ^([^.]+)$ $1.html [QSA]
  RewriteCond %{REQUEST_FILENAME} !-f

  # no, so we redirect to our front web controller
  RewriteRule ^(.*)$ index.php [QSA,L]
</IfModule>

# big crash from our front web controller
ErrorDocument 500 "<h2>Application error</h2>symfony applicationfailed to start properly"

Теперь можно просмотреть ваше приложение. Загрузите поздравительную страничку запросив URL:

http://www.example.com/myapp_dev.php/

SIDEBAR Другие Настройки Сервера

Symfony может быть настроен и пр-другому. Например, можно использовать alias вместо виртуального хоста (virtual host) для настройки сервера. Также можно запускать приложения symfony на сервере IIS. Путей много, их описание не является целью этой книги.

Обратитесь к wiki (http://www.symfony-project.com/trac/wiki), если вас интересуют специфические конфигурации сервера. Wiki содержит много пошаговых туториалов и инструкций.

Устранение проблем (Troubleshooting)

Если вы столкнулись с проблемами во время установки, попытайтесь извлечь максимальную пользу из информации об ошибках, которая будет отображена в вашем браузере или консоли (шелле). Часто эта информация содержит необходимые объяснения или даже ссылки на конкретные веб странички, посвященные данной ошибке.

Типичные проблемы

Если у вас все еще есть проблемы с запуском symfony, проверьте следующее:

• Некоторые установки php включают в себя команды PHP4 и PHP5. В этом случае в консоли следует использовать не php, а php5. Попробуйте вызвать php5 symfony вместо команды symfony. Возможно, еще понадобится добавить SetEnv PHP_VER 5 в настройки .htaccess, или переименовать скрипты директории web/ с .php на php5. Ошибка, которую выдает PHP4, пытаясь получить доступ к symfony, выглядит примерно так:

  Parse error, unexpected ',', expecting '(' in .../symfony.php on line 19.
  

• Предел памяти, определенный в php.ini, должен быть не меньше 16M. Часто симптомом этой проблемы является сообщение об ошибке при установке через PEAR или при использовании командной строки:

  Allowed memory size of 8388608 bytes exhausted
  

• Настройка zend.ze1_compatibility_mode в php.ini должна быть отключена (выставлено значение off). Если же эта установка включена, то при попытке запустить скрипт в браузере возникнет ошибка "implicit cloning":

  Strict Standards: Implicit cloning object of class 'sfTimer'because of 'zend.ze1_compatibility_mode'
  

• Сервер должен иметь права на запись в директории log/ и cache/. Попытка запустить приложение symfony в браузере, не настроив права доступа к этим папкам, приведет к следующей ошибке:

  sfCacheException [message]   
  

  Unable to write cache file"/usr/myproject/cache/frontend/prod/config/config_config_handlers.yml.php"

• Include path вашей системы должен содержать путь к команде php, а include path в php.ini - путь к PEAR (если вы используйте PEAR).

• Иногда сервер использует несколько php.ini (например, в случае пакета WAMP). Вызовите phpinfo(), чтоб узнать какой именно php.ini используется вашим приложением.

NOTE Для улучшения быстродействия настоятельно рекомендуется выставить установки magic_quotes_gpc и register_globals на значение off в вашем php.ini

Ресурсы Symfony

Возможно, кто-то уже сталкивался с вашей проблемой, и для нее уже есть готовые решения. Поискать их можно тут:

• Форум symfony, посвященный установке (http://www.symfony-project.com/forum/), содержит много информации касательно платформ, установки на хост, окружения (environment), настроек и т. д.
• Можно найти ответ на свой вопрос в архивах писем из рассылки (users mailing-list) по адресу http://groups.google.fr/group/symfony-users.
• Wiki (http://www.symfony-project.com/trac/wiki#Installingsymfony) содержит пошаговые туториалы и инструкции по установке, написанные пользователями.

Если вы все же не нашли решения свей проблемы, вынесите ее на обсуждение в сообщество symfony (symfony community). Вы можете задать вопрос на форуме, отослать письмо в список рассылки (mailing list) или даже обсудить все вживую с наиболее активными участниками сообщества в IRC канале #symfony.

Контроль Версий (Source Versioning)

После того, как проект создан, рекомендуется начать процесс контроля версий (source versioning). Система контроля версий хранит след всех изменений, сделанных в коде, обеспечивает доступ к предыдущим версиям проекта, упрощает наложение заплаток (patching) и обеспечивает эффективную работу команды. Symfony поддерживает CVS, хотя рекомендуется использовать Subversion (http://subversion.tigris.org/). Следующие примеры иллюстрируют команды Subversion, и подразумевают, что вы уже установили сервер Subversion и теперь хотите создать новый репозиторий для вашего проекта. Для пользователей Windows рекомендуется использовать клиент TortoiseSVN (http://tortoisesvn.tigris.org/). Обратитесь к документации Subversion, чтоб узнать больше о контроле версий и используемых командах.

Немного ссылок на википедию

Система управления версиями

Subversion

переводчик

Следующий пример подразумевает, что $SVNREP_DIR задана как переменная среды (environment variable). Если же это не сделано, то просто замените $SVNREP_DIR на реальный путь к репозиторию.

В дальнейшем важно понимать, что и репозиторий, и проект, который мы стремимся добавить в репозиторий, находятся на одной машине.

переводчик

Итак, давайте создадим новый репозиторий для проекта myproject.

> svnadmin create $SVNREP_DIR/myproject

Затем базовая структура репозитория создается из директорий trunk, tags, и branches следующей длинной командой:

> svn mkdir -m "layout 

creation" file:///$SVNREP_DIR/myproject/trunk file:///$SVNREP_DIR/myproject/tags file:///$SVNREP_DIR/myproject/branches

Теперь приступим к первой ревизии (revision). Необходимо импортировать все файлы проекта, кроме файлов кэша и журналов событий (логов):

> cd ~/myproject
> rm -rf cache/*
> rm -rf log/*
> svn import -m "initial import" . file:///$SVNREP_DIR/myproject/trunk

Проверим, успешно ли прошла передача файлов, набрав в консоли:

> svn ls file:///$SVNREP_DIR/myproject/trunk/

Похоже, все прошло успешно. Теперь в репозитории хранится контрольная версия (и история) всех файлов вашего проекта. Далее нужно установить соответствие между файлами исходной папки /myproject/ и файлами, хранящимися в репозитории. Чтобы сделать это, прежде всего переименуйте директорию myproject/ (если все пойдет по плану, скоро вы ее удалите) и сделайте checkout в новую директорию.

Прокомментирую этот абзац. Дело в том, что после импорта проекта в репозиторий соответствие межу файлами исходного проекта и файлами проекта, хранящегося в репозитории, все еще не установлено. Чтобы установить это соответствие исходная директория с проектом удаляется и делается checkout в новую директорию. Таким образом, в новую папку скачиваются файлы проекта из репозитория, и в итоге мы имеем рабочую версию проекта, "связанную" с проектом, хранящимся в репозитории.

переводчик

> cd ~
> mv myproject myproject.origin
> svn co file:///$SVNREP_DIR/myproject/trunk myproject
> ls myproject

Вот и все. Теперь вы можете работать с файлами в папке /myproject/ и фиксировать (commit) изменения в репозитории. Не забудьте удалить бесполезную теперь директорию myproject.origin/.

Осталось сделать последние шаги. Если вы фиксируйте (commit) вашу рабочую версию в репозитории, то будут переданы и нежелательные файлы, такие как файлы папок cache/ и log/. Поэтому нужно задать перечень директорий и файлов которые нужно игнорировать (ignore list). Также нужно снова выставить права на запись для папок cache/ и log/.

> cd ~/myproject
> chmod 777 cache
> chmod 777 log
> svn propedit svn:ignore log
> svn propedit svn:ignore cache

Должен открыться заданный для SVN текстовый редактор по умолчанию. Если этого не произошло, используйте ваш любимый редактор, прописав его в команде:

> export SVN_EDITOR=<name of editor>
> svn propedit svn:ignore log
> svn propedit svn:ignore cache

Теперь просто добавьте все поддиректории myproject/, которые должны игнорироваться SVN при фиксации (commit):

*

Сохраните и выйдете. Вот и все.

Итого

Чтоб играться и исследовать symfony больше всего подходит заранее настроенный sandbox.

Установка через PEAR или через SVN подойдет для реальной разработки и в случае установки на сервер. Вы получите установленные библиотеки symfony, но вам понадобится создать проект и приложение самому. Последний шаг — конфигурация веб сервера, которая допускает множество вариантов. Symfony отлично работает, если настроить виртуальный хост (virtual host), именно это решение рекомендовано.

Если в процессе установки возникли ошибки, вы можете найти множество туториалов и ответов на часто задаваемые вопросы на сайте symfony. Если решение не найдено, обсудите вашу проблему в сообществе symfony, и вы быстро получите нужный ответ.

Хорошей идеей будет поставить свежесозданный проект на контроль версий.

Теперь вы готовы использовать symfony, и можно приступить к разработке базового веб приложения.

Перевел Алексей Гоголев postman [at] dev [dot] co [dot] ua

Статья также доступна по адресу http://developer.co.ua/posts/view/glava_3_zapuskaem_symfony