Symfony 2009 advent calendar – это 24 урока продвинутого уровня о symfony. Все уроки представлены на 5 языках: английском, французском, испанском, итальянском, японском. Русского нет, это досадное упущение постараюсь исправить.

Перевод статьи Symfony 2009 Advent Calendar: Advanced Routing (part 2).

Коллекции маршрутов

Для завершения проекта Sympal Builder нам нужно создать админку, в которой каждый клиент может управлять страницами своего сайтика. Для того, чтобы это реализовать, нам нужен набор экшенов (actions), которые будут осуществлять list, create, update, delete для объектов Page. Так как эти действия стандартные, мы можем сгенерировать модуль автоматически. Выполним следующий таск из командной строки, для генерации модуля в апликации backend:

$ php symfony doctrine:generate-module backend pageAdmin Page --with-doctrine-route --with-show

Будет сгенерирован модуль с файлом actions.class.php и соответствующие ему шаблоны, которые позволят выполнять необходимые действия для объекта Page. Кастомизацию сгенерированного CRUD оставим за пределами нашего рассказа ))

Не смотря на то, что мы сгенерировали нужный модуль автоматически, нам нужно еще создать маршрут для каждого экшена. Так как мы использовали при генерации опцию –with-doctrine-route, то каждый экшен был сгенерирован таким образом, чтобы работать с объектом маршрута. Это уменьшает объем кода в каждом экшене. Например, экшн edit состоит из одной строчки:

public function executeEdit(sfWebRequest $request)
{
  $this->form = new PageForm($this->getRoute()->getObject());
}

В итоге, нам нужны маршруты для действий: index, new, create, edit, update, delete. Для создания этих маршрутов в RESTful стиле, внесем изменения в routing.yml:

pageAdmin:
  url:         /pages
  class:       sfDoctrineRoute
  options:     { model: Page, type: list }
  params:      { module: page, action: index }
  requirements:
    sf_method: [get]
pageAdmin_new:
  url:        /pages/new
  class:      sfDoctrineRoute
  options:    { model: Page, type: object }
  params:     { module: page, action: new }
  requirements:
    sf_method: [get]
pageAdmin_create:
  url:        /pages
  class:      sfDoctrineRoute
  options:    { model: Page, type: object }
  params:     { module: page, action: create }
  requirements:
    sf_method: [post]
pageAdmin_edit:
  url:        /pages/:id/edit
  class:      sfDoctrineRoute
  options:    { model: Page, type: object }
  params:     { module: page, action: edit }
  requirements:
    sf_method: [get]
pageAdmin_update:
  url:        /pages/:id
  class:      sfDoctrineRoute
  options:    { model: Page, type: object }
  params:     { module: page, action: update }
  requirements:
    sf_method: [put]
pageAdmin_delete:
  url:        /pages/:id
  class:      sfDoctrineRoute
  options:    { model: Page, type: object }
  params:     { module: page, action: delete }
  requirements:
    sf_method: [delete]
pageAdmin_show:
  url:        /pages/:id
  class:      sfDoctrineRoute
  options:    { model: Page, type: object }
  params:     { module: page, action: show }
  requirements:
    sf_method: [get]

Для того чтобы визуально представить эти маршруты, воспользуемся таском app:routes, который отображает данные о каждом маршруте для указанной апликации (в рамках проекта):

$ php symfony app:routes backend

>> app       Current routes for application "backend"
Name             Method Pattern
pageAdmin        GET    /pages
pageAdmin_new    GET    /pages/new
pageAdmin_create POST   /pages
pageAdmin_edit   GET    /pages/:id/edit
pageAdmin_update PUT    /pages/:id
pageAdmin_delete DELETE /pages/:id
pageAdmin_show   GET    /pages/:id

Заменяем маршруты на коллекцию маршрутов

К счастью, symfony предлагает нам более простой путь для создания маршрутов, которые относятся к традиционному CRUD. Заменим все что мы написали в routing.yml на один маршрут:

pageAdmin:
  class:   sfDoctrineRouteCollection
  options:
    model:        Page
    prefix_path:  /pages
    module:       pageAdmin

Еще раз выполним таск app:routes для того чтобы посмотреть что получилось. Как вы можете видеть, все наши маршруты остались на месте:

$ php symfony app:routes backend

>> app       Current routes for application "backend"
Name             Method Pattern
pageAdmin        GET    /pages.:sf_format
pageAdmin_new    GET    /pages/new.:sf_format
pageAdmin_create POST   /pages.:sf_format
pageAdmin_edit   GET    /pages/:id/edit.:sf_format
pageAdmin_update PUT    /pages/:id.:sf_format
pageAdmin_delete DELETE /pages/:id.:sf_format
pageAdmin_show   GET    /pages/:id.:sf_format

Коллекция маршрутов это специальный тип объекта маршрута, который представляет более чем один маршрут. Маршрут sfDoctrineRouteCollection, например, автоматически генерирует семь основных маршрутов, необходимых для CRUD. За кулисами же, sfDoctrineRouteCollection кроме создания семи маршрутов, которые мы раньше описывали в routing.yml, ничего не делает. Коллекции маршрутов, в основном существуют в качестве ярлыка для создания типичных групп маршрутизации.

Создание новой коллекции маршрутов

Сейчас, каждый клиент имеет возможность модифицировать объекты Page при помощи CRUD по адресу /pages. К несчастью, каждый клиент сейчас также может видеть и модифицировать все страницы, в том числе и не принадлежащие ему. Например, по адресу http://pete.sympalbuilder.com/backend.php/pages отобразится список, состоящий из обеих страниц из нашей фикстуры (см. первую часть) – страницы location из магазина зверюшек Пита и страницы menu из СитиПаба.

Для того чтобы поправить положение, мы используем ранее определенный для фронтэнда класс acClientObjectRoute. Класс sfDoctrineRouteCollection генерирует группу объектов sfDoctrineRoute. В нашем же приложении нужно сгенерировать группу объектов acClientObjectRoute.

Для того чтобы выполнить нашу задумку, нужно создать новый класс коллекции маршрутов. Создадим файл acClientObjectRouteCollection.class.php и разместим его в директории lib/routing. Его содержимое невероятно просто:

// lib/routing/acClientObjectRouteCollection.class.php
class acClientObjectRouteCollection extends sfObjectRouteCollection
{
  protected
    $routeClass = 'acClientObjectRoute';
}

Свойство $routeClass определяет класс, который будет использоваться для создания каждого маршрута. Теперь, когда мы изменили тип маршрутов, основная часть работы выполнена. Например, по адресу http://pete.sympalbuilder.com/backend.php/pages теперь будет отображаться только одна страница: location из магазина зверюшек Пита. Благодаря нашему классу маршрута, экшн index возвращает только те объекты Page, которые соответствуют клиенту, основываясь на поддомене из запроса. Написав всего-лишь несколько строк кода, мы создали модуль для админки, который может безопасно использоваться различными клиентами.

Недостающая часть: создание новых страниц

Сейчас, при создании (или редактировании) страницы, отображается селектбокс для выбора клиента, к которому она относится. Вместо того , чтобы давать пользователю возможность выбирать клиента (что есть потенциальная дыра в безопасности), будем устанавливать клиента автоматически, по поддомену из запроса.

Для начала, изменим объект PageForm (lib/form/PageForm.class.php):

public function configure()
{
  $this->useFields(array(
    'title',
    'content',
  ));
}

Теперь селектбокс не будет отображаться, чего мы и хотели. Но теперь при создании страницы мы не сможем установить client_id (( Для того чтобы исправить этот баг, укажем необходимого клиента для экшенов new и create:

public function executeNew(sfWebRequest $request)
{
  $page = new Page();
  $page->Client = $this->getRoute()->getClient();
  $this->form = new PageForm($page);
}

Тут мы используем функцию getClient(), которая пока еще не существует )) в классе acClientObjectRoute. Добавим этот метод путем небольших модификаций:

// lib/routing/acClientObjectRoute.class.php
class acClientObjectRoute extends sfDoctrineRoute
{
  // ...

  protected $client = null;

  public function matchesUrl($url, $context = array())
  {
    // ...

    $this->client = $client;

    return array_merge(array('client_id' => $client->id), $parameters);
  }

  public function getClient()
  {
    return $this->client;
  }
}

Путем добавления свойства $client (которое принимает значение в методе matchesUrl()), мы легким движением руки сделаем доступным объект клиента через маршрут. Колонка client_id для нового объекта Page теперь автоматически (и правильно) устанавливается на основании поддомена текущего хоста.

Настройка коллекции маршрутов

Используя маршрутизатор, мы легко решили проблемы, которые у нас возникали при создании нашего вымышленного приложения Sympal Builder. По мере роста приложения, разработчик должен иметь возможность повторного использования маршрутов для других модулей в админке (например, для создания фотогалерей для каждого клиента).

С другой стороны, создавать коллекции маршрутов можно также для добавления часто используемых маршрутов. Например, предположим, в проекте есть много моделей с колонкой is_active. В админке нужно иметь простой способ переключения статуса is_active для любого объекта. Для начала, модифицируем acClientObjectRouteCollection и добавим новый маршрут в коллекцию:

// lib/routing/acClientObjectRouteCollection.class.php
protected function generateRoutes()
{
  parent::generateRoutes();

  if (isset($this->options['with_is_active']) && $this->options['with_is_active'])
  {
    $routeName = $this->options['name'].'_toggleActive';

    $this->routes[$routeName] = $this->getRouteForToggleActive();
  }
}

Метод sfRouteCollection::generateRoutes() вызывается когда объект коллекции инициализирован и готов к созданию всех необходимых маршрутов и добавлению их переменную класса $routes. Тут мы добавляем новый protected метод getRouteForToggleActive():

protected function getRouteForToggleActive()
{
  $url = sprintf(
    '%s/:%s/toggleActive.:sf_format',
    $this->options['prefix_path'],
    $this->options['column']
  );

  $params = array(
    'module' => $this->options['module'],
    'action' => 'toggleActive',
    'sf_format' => 'html'
  );

  $requirements = array('sf_method' => 'put');

  $options = array(
    'model' => $this->options['model'],
    'type' => 'object',
    'method' => $this->options['model_methods']['object']
  );

  return new $this->routeClass(
    $url,
    $params,
    $requirements,
    $options
  );
}

Теперь остался один шаг – настройка коллекции маршрутов в routing.yml. Обратите внимание, что generateRoutes() ищет опцию with_is_active перед добавлением нового маршрута. Добавление этого куска кода дает нам лучший контроль в ситуации, когда мы хотим использовать acClientObjectRouteCollection где-то, где нет необходимости в маршруте toggleActive:

# apps/frontend/config/routing.yml
pageAdmin:
  class:   acClientObjectRouteCollection
  options:
    model:          Page
    prefix_path:    /pages
    module:         pageAdmin
    with_is_active: true

Выполним таск app:routes и удостоверимся что новый маршрут toggleActive наличествует в списке. Нам осталось лишь создать экшн, который будет делать грязную работу )) Так как вы возможно захотите использовать эту коллекцию маршрутов в различных модулях, создадим файл backendActions.class.php в директории apps/backend/lib/action (директорию надо будет создать):

# apps/backend/lib/action/backendActions.class.php
class backendActions extends sfActions
{
  public function executeToggleActive(sfWebRequest $request)
  {
    $obj = $this->getRoute()->getObject();

    $obj->is_active = !$obj->is_active;

    $obj->save();

    $this->redirect($this->getModuleName().'/index');
  }
}

И, наконец, изменим базовый класс pageAdminActions, чтобы он наследовался от нашего только что созданного класса backendActions:

class pageAdminActions extends backendActions
{
  // ...
}

И чего же мы достигли? Теперь каждый новый модуль может автоматически использовать новый функционал всего лишь используя acClientObjectRouteCollection и наследуясь от класса backendActions. Таким образом, общий функционал может быть легко использоваться различными модулями.

Свойства коллекции маршрутов

Объект коллекции маршрутов содержит ряд свойств (опций), которые позволяют производить его гибкую настройку. Во многих случаях, разработчик может использовать эти свойства для конфигурирования коллекции без необходимости создавать новый класс коллекции маршрутов. Подробный список свойств коллекции маршрутов вы можете посмотреть в справочнике The symfony Reference Book.

Маршруты экшенов

Каждый объект коллекции маршрутов принимает три различные опции, который определяют маршруты, которые будут сгенерированы в коллекции. Не вдаваясь в детали, следующая коллекция будет генерировать все семь маршрутов по-умолчанию, наряду с дополнительной коллекцией маршрутов и объектом маршрута:

pageAdmin:
  class:   acClientObjectRouteCollection
  options:
    # ...
    actions:      [list, new, create, edit, update, delete, show]
    collection_actions:
      indexAlt:   [get]
    object_actions:
      toggle:     [put]

Колонка (Column)

По умолчанию, первичный ключ модели используется во всех сгенерированных URLs и используется в запросах к БД которые выполняются для получения объектов. Это легко можно изменить. Например, следующий код будет использовать колонку slug вместо первичного ключа:

pageAdmin:
  class:   acClientObjectRouteCollection
  options:
    # ...
    column: slug

Методы модели

По умолчанию, маршрут получает все зависимые объекты для коллекции маршрутов по указанной колонке. Если такое поведение нужно изменить, добавьте свойство model_methods в маршрут. В этом примере методы fetchAll() и findForRoute() должны быть добавлены к классу PageTable. Оба метода будут получать массив параметров запроса как аргумент:

pageAdmin:
  class:   acClientObjectRouteCollection
  options:
    # ...
    model_methods:
      list:       fetchAll
      object:     findForRoute

Параметры по умолчанию

Наконец, предположим что вам нужно сделать особый параметр запроса, доступным в запросе для каждого маршрута в коллекции. Это легко сделать при помощи параметра default_params:

pageAdmin:
  class:   acClientObjectRouteCollection
  options:
    # ...
    default_params:
      foo:   bar

Заключение

Основная работа маршрутизатора – сверять и генерировать URLы – в symfony переросла в гибкую систему, способную обслуживать сложные URL, необходимые в проектах. Под контролем объекта маршрута, структура URL может быть абстрагирована от бизнес-логики и целиком храниться в маршруте, которому принадлежит. В результате мы получаем больший контроль, большую гибкость и более управляемый код.

Symfony 2009 advent calendar – это 24 урока продвинутого уровня о symfony. Все уроки представлены на 5 языках: английском, французском, испанском, итальянском, японском. Русского нет, это досадное упущение постараюсь исправить.

Перевод статьи Symfony 2009 Advent Calendar: Advanced Routing (part 1).

by Ryan Weaver

Маршрутизатор (или же каркас маршрутизации), если смотреть изнутри, представляет из себя карту, которая связывает каждый URL с некоторой локацией внутри проекта на symfony и наоборот. Он может с легкостью создать красивые URL, оставаясь независимым от логики приложения. Учитывая прогресс, которого удалось достигнуть в предыдущих версиях symfony, маршрутизатор делает следующий шаг вперед.

Эта глава иллюстрирует процесс создания простого веб-приложения, в котором каждый клиент использует отдельный субдомен (например client1.mydomain.com и client2.mydomain.com). Это будет совсем несложно, когда мы расширим возможности маршрутизатора ))

Для примера из этой главы мы будем использовать Doctrine в качестве ORM

Настройка проекта: CMS для многих клиентов

Для начала представим некую вымышленную компанию, Sympal Builder, которая желает создать CMS, с помощью которой ее клиенты смогут создавать вебсайты на поддоменах сайта sympalbuilder.com. Т.е. клиент XXX может просмотреть свой сайт по адресу xxx.sympalbuilder.com и использовать админку по адресу xxx.sympalbuilder.com/backend.php.

Наименование Sympal мы позаимствовали у одноименного проекта Jonathan Wage – Sympal, CMF, созданная на symfony.

Проект имеет два основных требования:

• Пользователь должен иметь возможность создавать страницы и указывать для них title, content и URL.
• Приложение должно быть создано внутри одного проекта symfony, который контролирует фронтэнд и бэкэнд всех клентских сайтов, определяя клиента и загружая корректные данные для поддомена.

Для создания нашего приложения, вебсервер должен быть настроен направлять все запросы на *.sympalbuilder.com на тот же document root – web директорию нашего проекта на symfony.

Схема и данные

База данных для проекта будет состоять из объектов Client и Page. Каждый Client представлен на своем поддомене и может содержать много объектов Page.

# config/doctrine/schema.yml
Client:
  columns:
    name:       string(255)
    subdomain:  string(50)
  indexes:
    subdomain_index:
      fields:   [subdomain]
      type:     unique

Page:
  columns:
    title:      string(255)
    slug:       string(255)
    content:    clob
    client_id:  integer
  relations:
    Client:
      alias:        Client
      foreignAlias: Pages
      onDelete:     CASCADE
  indexes:
    slug_index:
      fields:   [slug, client_id]
      type:     unique

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

Для того чтобы наш проект заработал, необходимо разместить следующие тестовые данные в файле data/fixtures/fixtures.yml:

# data/fixtures/fixtures.yml
Client:
  client_pete:
    name:      Pete's Pet Shop
    subdomain: pete
  client_pub:
    name:      City Pub and Grill
    subdomain: citypub

Page:
  page_pete_location_hours:
    title:     Location and Hours | Pete's Pet Shop
    content:   We're open Mon - Sat, 8 am - 7pm
    slug:      location
    Client:    client_pete
  page_pub_menu:
    title:     City Pub And Grill | Menu
    content:   Our menu consists of fish, Steak, salads, and more.
    slug:      menu
    Client:    client_pub

Это тестовые данные для двух вебсайтов, каждый из них имеет по одной странице. Полный URL каждой страницы определяется колонкой subdomain в таблице Client и колонкой slug в таблице Page.

http://pete.sympalbuilder.com/location

http://citypub.sympalbuilder.com/menu

Маршрутизация

Каждая страница вебсайта Sympal Builder напрямую соответствует объекту Page, который определяет ее title и content. Для того чтобы связать каждый URL с его страницей, создадим маршрут типа sfDoctrineRoute, который использует поле slug:

# apps/frontend/config/routing.yml
page_show:
  url:        /:slug
  class:      sfDoctrineRoute
  options:
    model:    Page
    type:     object
  params:
    module:   page
    action:   show

Этот маршрут связывает страницу http://pete.sympalbuilder.com/location с соответствующим объектом Page. К несчастью, этот маршрут также соответствует URL’у http://pete.sympalbuilder.com/menu, т.е. меню ресторана (это другая страница, которая относится к клиенту citypub) также будет отбражаться и на сайте Пита!  На этом шаге маршрут не знает о важности клиентских поддоменов.

Для того чтобы проект заработал, маршрут должен стать более умным. Он должен находить корректную страницу основываясь на полях slug и client_id одновременно, что позволит определять соответствующий хост (например pete.sympalbuilder.com) по колонке subdomain в модели Client. Для того чтобы достичь этого, мы воспользуемся каркасом маршрутизации и создадим свой собственный класс маршрута.

Но, для начала, нам необходимо немного узнать о том, как работает система маршрутизации.

Как работает система маршрутизации

Не смотря на то, что маршруты в основном определены в YAML-файле, они трансформируются в объект в момент вызова при помощи специального класса, который называется cache config handler. В итоге, PHP код представляет каждый маршрут в приложении. Поскольку специфика данного процесса выходит за рамки данной статьи, давайте сразу перейдем к его окончанию, т.е. к компилированной версии маршрута page_show. Компилированный файл находится в файле cache/yourappname/envname/config/config_routing.yml.php для конкретного приложения (app) и окружения (env). Ниже приведена сокращенная версия того как выглядит в итоге маршрут page_show:

new sfDoctrineRoute('/:slug', array (
  'module' => 'page',
  'action' => 'show',
), array (
  'slug' => '[^/\.]+',
), array (
  'model' => 'Page',
  'type' => 'object',
));

Наименование класса каждого маршрута определяется ключом class внутри файла routing.yml. Если этот ключ не указан, маршрут по умолчанию будет являться классом sfRoute. Другой стандартный класс маршрута – это sfRequestRoute, который позволяет разработчику создавать RESTful маршруты. Полный список классов маршрутов и доступных для них опций вы можете найти в с правочнике symfony.

Сверка входящего запроса с конкретным маршрутом

Одно из основных занятий маршрутизатора – сверять каждый входящий URL с корректным объектом маршрута. Класс sfPatternRouting это ядро движка маршрутизации и занимается только этой задачей. Не смотря на его важность, разработчики редко взаимодействуют напрямую с sfPatternRouting.

Для определения корректного маршрута, sfPatternRouting циклически просматривает каждый sfRoute и “спрашивает”, подходит ли ему входящий URL. Изнутри это выглядит следующим образом: sfPatternRouting вызывает метод sfRoute::matchesUrl() для каждого объекта маршрута. Этот метод просто возвращает false, если маршрут не соответствует входящему URL.

А вот если маршрут соответствует входящему URL, sfRoute::matchesUrl() делает несколько больше, нежели просто возвращает true. Вместо этого, маршрут возвращает массив параметров, которые объединяются с объектом запроса. Например, URL http://pete.sympalbuilder.com/location соответствует маршруту page_show, чей метод matchesUrl() вернет следующий массив:

array('slug' => 'location')

Эти данные будут включены в объект запроса, именно поэтому можно получить доступ к переменным маршрута (например, slug) из экшена или из других мест где это требуется.

$this->slug = $request->getParameter('slug');

Как вы могли предположить, переопределение метода sfRoute::matchesUrl() это отличный способ настроить маршрут и сделать почти все что угодно.

Создание собственного класса маршрута

Для того чтобы расширить возможности маршрута page_show для того чтобы он осуществлял проверку, основываясь на поддомене из объекта Client, мы создадим свой собственный класс маршрута. Создадим файл acClientObjectRoute.class.php и разместим его в директории lib/routing нашего проекта (вам нужно будет создать эту директорию):

// lib/routing/acClientObjectRoute.class.php
class acClientObjectRoute extends sfDoctrineRoute
{
  public function matchesUrl($url, $context = array())
  {
    if (false === $parameters = parent::matchesUrl($url, $context))
    {
      return false;
    }

    return $parameters;
  }
}

Следующим шагом проинструктируем маршрут page_show чтобы он использовал наш класс маршрута. В routing.yml нужно обновить ключ class в маршруте:

# apps/fo/config/routing.yml
page_show:
  url:        /:slug
  class:      acClientObjectRoute
  options:
    model:    Page
    type:     object
  params:
    module:   page
    action:   show

Пока что acClientObjectRoute не добавляет функциональности, но тем не менее все части на своих местах. Метод matchesUrl имеет две специфичные функции.

Добавляем логику в наш маршрут

Для того чтобы добавить в маршрут необходимую функциональность, заменим содержимое файла acClientObjectRoute.class.php на следующее:

class acClientObjectRoute extends sfDoctrineRoute
{
  protected $baseHost = '.sympalbuilder.com';

  public function matchesUrl($url, $context = array())
  {
    if (false === $parameters = parent::matchesUrl($url, $context))
    {
      return false;
    }

    // return false if the baseHost isn't found
    if (strpos($context['host'], $this->baseHost) === false)
    {
      return false;
    }

    $subdomain = str_replace($this->baseHost, '', $context['host']);

    $client = Doctrine_Core::getTable('Client')
      ->findOneBySubdomain($subdomain)
    ;

    if (!$client)
    {
      return false;
    }

    return array_merge(array('client_id' => $client->id), $parameters);
  }
}

Вызов parent::matchesUrl() необходим чтобы запустить обычный процесс проверки соответствия маршрутов. В нашем примере, так как URL /location соответствует маршруту page_show, метод parent::matchesUrl() должен вернуть соответствующий параметр slug:

array('slug' => 'location')

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

public function matchesUrl($url, $context = array())
{
  // ...

  $subdomain = str_replace($this->baseHost, '', $context['host']);

  $client = Doctrine_Core::getTable('Client')
    ->findOneBySubdomain($subdomain)
  ;

  if (!$client)
  {
    return false;
  }

  return array_merge(array('client_id' => $client->id), $parameters);
}

Путем выполнения простой строковой замены мы можем изолировать кусочек, соответствующий поддомену и запросить базу данных, есть ли клиент с таким поддоменом. Если ни один клиент не соответствует этому критерию, тогда мы с чистой совестью вернем false, подразумевая этим, что запрос не соответствует маршруту. Если же мы нашли клиента с текущим поддоменом, мы объединяем дополнительный параметр client_id с возвращаемым массивом.

Массив $context, передаваемый в matchesUrl заполняется кучей полезной информации о текущем запросе, включая host, is_secure, request_uri, HTTP метод и так далее…

И чего же мы в конце концов добились? Класс acClientObjectRoute теперь делает следующее:

• Входящий $url будет соответствовать только если host содержит поддомен, соответствующий одному их клиентских объектов.
• Если маршрут соответствует, метод возвращает дополнительный параметр – client_id соответствующего клиента, объединяемый с параметрами запроса.

Используем новый маршрут

Теперь, когда acClientObjectRoute возвращает корректный параметр client_id, мы можем получить его значение через объект запроса. Например, экшен page/show может использовать client_id для определения корректного объекта Page:

public function executeShow(sfWebRequest $request)
{
  $this->page = Doctrine_Core::getTable('Page')->findOneBySlugAndClientId(
    $request->getParameter('slug'),
    $request->getParameter('client_id')
  );

  $this->forward404Unless($this->page);
}

Метод findOneBySlugAndClientId() это один из магических поисковых методов(magic finder) – нововведение Doctrine 1.2, которое позволяет искать объекты, основываясь на нескольких полях.

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

protected function getRealVariables()
{
  return array_merge(array('client_id'), parent::getRealVariables());
}

Теперь, экшен может полностью полагаться на маршрут, который вернет правильный объект. Теперь экшен page/show может уместиться в одну строку:

public function executeShow(sfWebRequest $request)
{
  $this->page = $this->getRoute()->getObject();
}

Без лишних телодвижений, этот код будет запрашивать объект Page, основываясь на обеих колонках: slug и client_id. Кроме того, как и все другие объекты маршрутов, экшен будет автоматически перенаправлен на страницу 404, если соответствующий объект не найден.

Как же это работает? Объекты маршрутов, например sfDoctrineRoute, который расширяет наш класс acClientObjectRoute, автоматически запрашивает соответствующий объект, основываясь на переменных в ключе url маршрута. Например, маршрут page_show, который содержит переменную :slug в его url, будет запрашивать объект Page, основываясь на колонке slug.

В этом приложении, маршрут page_show должен также запрашивать объекты Page, основываясь на колонке client_id. Для того чтобы добиться этого, мы переопределили метод sfObjectRoute::getRealVariables(), который вызывается внутри для определения какие колонки нужно использовать для запроса объекта. Т.о., добавив в этот массив client_id, мы дали возможность acClientObjectRoute сформировать запрос используя и slug и client_id.

Объекты маршрутов автоматически игнорируют любые переменные, которые не соответствуют реальным столбцам в базе данных. Например, если URL содержит переменную :page, но соответствующая таблица такой колонки не имеет, эта переменная будет проигнорирована.

Итак, теперь наш маршрут умеет все что нам необходимо, при этом мы затратили очень мало усилий чтобы достичь этого. В следующей части мы используем наш маршрут еще раз, чтобы создать админку для пользователей.

Генерируем корректный URL

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

<?php echo link_to('Locations', 'page_show', $page) ?>

Генерируется url: /location?client_id=1

Как вы видите, client_id автоматически добавляется к url. Это происходит потому что маршрут пытается использовать все его переменные для генерации URL. Так как маршрут теперь осведомлен о двух параметрах – slug и client_id, он использует их оба для создания маршрута.

Для того чтобы поправить этот баг, добавим следующий метод к классу acClientObjectRoute :

protected function doConvertObjectToArray($object)
{
  $parameters = parent::doConvertObjectToArray($object);

  unset($parameters['client_id']);

  return $parameters;
}

Когда объект маршрута создается, он пытается получить всю необходимую информацию, вызывая doConvertObjectToArray(). По умолчанию, client_id возвращается в массиве $parameters. Когда мы его удаляем (unset), мы предотвращаем включение его в сгенерированный URL. Помните, мы позволили себе подобную роскошь, поскольку информация о клиенте содержится в его поддомене.

Вы можете переопределить doConvertObjectToArray процесс целиком и обрабатывать его самостоятельно, путем добавления метода toParams в класс модели. Этот метод должен возвращать массив параметров, которые вы хотите использовать в процессе генерации маршрута.

Продолжение следует! ;–)

Symfony 2009 advent calendar – это 24 урока продвинутого уровня о symfony. Все уроки представлены на 5 языках: английском, французском, испанском, итальянском, японском. Русского нет, это досадное упущение постараюсь исправить.

Перевод введения к новой книге (или циклу статей если вам угодно) от идеолога и родоначальника symfony, Fabien Potencier, The symfony 2009 Advent Calendar: Introduction).

На момент написания этих слов, symfony отпраздновал знаменательную дату – свой четвертый день рождения. Всего за четыре года, symfony framework вырос и стал одним из наиболее популярных PHP-фреймворков в мире, питая своей энергией такие сайты как Delicious, Yahoo Bookmarks и Daily Motion. Но, с недавним релизом symfony 1.4 (ноябрь 2009) мы добрались до конца цикла (или если угодно, исчерпали возможности развития, подошли к качественному скачку). Эта книга – прекрасный способ окончить цикл разработки версии 1.xxx и, таким образом, вы собираетесь прочесть последнюю книгу о symfony 1го бранча, которая будет опубликована проектной группой symfony. Наша следующая книга будет скорее всего о symfony 2.0, который ожидается в конце 2010 года.

Зачем нужна еще одна книга?

Мы уже опубликовали две книги о symfony 1.3 и 1.4: “Practical symfony” и “The symfony reference guide“. Первая из них – отличный способ начать изучение symfony, так как вы изучаете основы его через разработку реального проекта шаг за шагом. Другая же книга – это справочник, который содержит бОльшую часть информации о конфигурировании symfony, которая вам может понадобиться в повседневной разработке.

“More with symfony” (она же “The symfony 2009 Advent Calendar”) – это книга, о более продвинутых аспектах symfony-разработки. Это не та книга, которую нужно читать в первую очередь при знакомстве с symfony, но она будет полезна тем, кто уже разработал несколько небольших проектов на symfony. Если вы хотите узнать как устроен symfony, как он работает, или же вы хотите расширить возможности фреймворка для выполнения различных специфических задач – эта книга для вас. Таким образом, “More with symfony” это то что вам нужно, чтобы поднять свои навыки по symfony на новый качественный уровень.

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

Я, к примеру, начал читать ее с раздела, посвященного facebook-разработке ))) // hudson

Об этой книге

Эта книга особенная, потому что она написана сообществом и для сообщества. Масса людей вложило свой труд в ее написание, начиная от авторов и заканчивая переводчиками, корректорами; множество их усилий слились в этой книге.

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

Эта книга появилась на свет благодаря духу open source и она публикуется под лицензией open source. Уже один этот факт меняет все. Это означает что никто не оплачивает работу над книгой: все, кто работал над ее созданием, трудились в поте лиц потому что они этого хотели. Каждый, кто хотел поделиться своими знаниями, получить что-то от сообщества, помочь распространению информации о symfony и, наконец, получить удовольствие и стать знаменитыми )))

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

Выражения благодарности

Когда я начал подумывать о написании еще одной книги о symfony в августе 2009 года, у меня сразу возникла сумасшедшая идея: а что если написать книгу за два месяца и опубликовать ее сразу на пяти языках! Конечно, вовлечение сообщества в проект таких масштабов было просто необходимо. Я начал рассказывать об этой идее в ходе PHP-конференции в Японии и в считанные часы японская команда переводчиков была готова к работе. Это было просто невероятно! Реакция авторов и переводчиков в равной степени обнадеживала и спустя немного времени, проект “More with symfony” был запущен.

Я хочу поблагодарить всех, кто принял участие тем или иным образом во время создания этой книги: Ryan Weaver, Geoffrey Bachelet, Hugo Hamon, Jonathan Wage, Thomas Rabaix, Fabrice Bernhard, Kris Wallsmith, Stefan Koopmanschap, Laurent Bonnet, Julien Madelin, Franck Bodiot, Javier Eguiluz, Nicolas Ricci, Fabrizio Pucci, Francesco Fullone, Massimiliano Arione, Daniel Londero, Xavier Briand, Guillaume Bretou, Akky Akimoto, Hidenori Goto, Hideki Suzuki, Katsuhiro Ogawa, Kousuke Ebihara, Masaki Kagaya, Masao Maeda, Shin Ohno, Tomohiro Mitsumune, и Yoshihiro Takahara.

Прежде чем начать

Эта книга была написана для версий symfony 1.3 и 1.4. Написание книги для двух версий одного и того же программного обеспечения – явление несколько необычное, в этой секции будут даны разъяснения по поводу основных различий этих двух версий, чтобы вы могли выбрать одну из них для ваших проектов.

Обе версии symfony 1.3 и 1.4 вышли в релиз примерно в одно и то же время (в конце 2009 года). Собственно говоря, обе они имеют абсолютно одинаковый набор фич. Единственное отличие этих двух версий в том, как они поддерживают обратную совместимость с более ранними версиями symfony.

Symfony 1.3 это релиз который вам нужен, если нужно делать upgrade для существующего проекта, который работает со старой версией symfony (1.0, 1.1, 1.2). Он содержит слой для обратной совместимости и все фичи, которые устарели и не рекомендованы к применению во время отладки и стабилизации ветки 1.3. Это означает, что апгрейд будет простым и безопасным.

Если сегодня вы начинаете новый проект, вы должны использовать symfony 1.4. Эта версия имеет те же возможности что и 1.3, но все устаревшие фичи, включая слоя для обеспечения обратной совместимости были удалены. Эта версия более “чистая” с точки зрения кода и немного более быстрая по сравнению с 1.3. Другой плюс от использования symfony 1.4 заключается в более длительное поддержке этой версии – она будет поддерживаться три года (до ноября 2012 года).

Конечно же, вы можете мигрировать свои проекты на 1.3 и затем понемногу модифицировать ваш код, удаляя устаревшие фичи и в конечном счете перейти на 1.4 для того чтобы иметь более длительную поддержку. У вас достаточно времени для планирования, так как Symfony 1.3 будет поддерживаться в течение года (до ноября 2010 года).

Так как в этой книге не упоминаются устаревшие фичи, все пример работают идентично в обеих версиях.

От переводчика: вообще говоря, введение несет не очень много полезной информации, но мне понравилось как Фабиен описывает книгу и как она появилось, поэтому решил перевести и его. // hudson

Symfony 2009 advent calendar – это 24 урока продвинутого уровня о symfony. Все уроки представлены на 5 языках: английском, французском, испанском, итальянском, японском. Русского нет, это досадное упущение постараюсь исправить.

Перевод статьи Symfony 2009 Advent Calendar: Developing for Facebook (part 2).

Facebook Connect

О том как Facebook Connect работает и о различных стратегиях интеграции

Facebook Connect, прежде всего, предоставляет свою сессию для совместного доступа вашему вебсайту. Работа этой функции становится возможной благодаря копированию аутентификационных кукисов с Facebook через iframe на сайте, который указывает на страницу Facebook, которая в свою очередь открывает iframe на сайт. Для этого, Facebook Connect должен иметь доступ к вебсайту, что делает невозможным использовать или тестировать Facebook Connect на локальном сервере или в интранет-сети. Входной точкой является xd_receiver.htm, который поставляется с sfFacebookConnectPlugin‘ом. Не забудьте выполнить таск plugin:publish-assets для того чтобы этот файл стал доступен.

Когда подготовительные процедуры выполнены, официальная библиотека Facebook получает возможность использовать сессию Facebook. В дополнение к этому, sfFacebookConnectPlugin создает пользователя sfGuard, связанного с сессией Facebook и который прочно связан с существующим сайтом на symfony. Вот почему плагин по умолчанию редиректит пользователя на экшен sfFacebookConnectAuth/signIn после того как тот нажмет кнопку Facebook Connect и сессия пройдет валидацию. Первым делом плагин ищет существующего пользователя с тем же UID’ом или с тем же хэшем Email (см. также раздел “Сопоставляем существующих пользователей с их аккаунтами на Facebook” в конце этой статьи). Если пользователь не найден, создается новый пользователь.

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

public function setDefaultsFromFacebookSession()
{
  if ($fb_uid = sfFacebook::getAnyFacebookUid())
  {
    $ret = sfFacebook::getFacebookApi()->users_getInfo(
      array(
        $fb_uid
      ),
      array(
        'first_name',
        'last_name',
      )
    );

    if ($ret && count($ret)>0)
    {
      if (array_key_exists('first_name', $ret[0]))
      {
        $this->setDefault('first_name',$ret[0]['first_name']);
      }
      if (array_key_exists('last_name', $ret[0]))
      {
        $this->setDefault('last_name',$ret[0]['last_name']);
      }
    }
  }

Для использования второй стратегии, просто разрешите в app.yml редирект после Facebook Connect и маршрут, который необходимо будет использовать.

# default values
all:
  facebook:
    redirect_after_connect: true
    redirect_after_connect_url: '@register_with_facebook'

Фильтр Facebook Connect

Другая важная особенность Facebook Connect заключается в том, что пользователи Facebook, при просмотре интернет-страниц, зачастую уже залогинены в Facebook. Вот тут во всю раскрывается сила sfFacebookConnectRememberMeFilter. Если пользователь, зашедший на ваш вебсайт, уже залогинен в Facebook, sfFacebookConnectRememberMeFilter автоматически залогинит его на вашем сайте, примерно так, как это делает фильтр “Remember me”.

$sfGuardUser = sfFacebook::getSfGuardUserByFacebookSession();
if ($sfGuardUser)
{
  $this->getContext()->getUser()->signIn($sfGuardUser, true);
}

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

Как избежать фатального JavaScript бага в IE

Один из самых ужасных багов, который вы можете получить на вебсайте, является ошибка “Operation aborted” в IE, которая запросто рушит рендеринг вебсайта на стороне клиента. Это следствие кривого движка рендеринга в IE6/7, который может обрушиться, если вы добавляете DOM-элементы к элементу BODY из скрипта, который не является прямым потомком элемента BODY. К несчастью, это как правило случается, если вы загружаете JavaScript для Facebook Connect и не озаботились загрузить его напрямую из body в конце документа. Тем не менее, этого легко избежать при помощи slot’ов. Используйте slot для того чтобы включить скрипт Facebook Connect’а когда это необходимо, в ваш шаблон лэйаута в конце документа (перед тагом </body>):

// in a template that uses a XFBML tag or a Facebook Connect button
slot('fb_connect');
include_facebook_connect_script();
end_slot();

// just before </body> in the layout to avoid problems in IE
if (has_slot('fb_connect'))
{
  include_slot('fb_connect');
}

Лучшие практики для Facebook-приложений

Благодаря sfFacebookConnectPlugin, интеграция с sfGuardPlugin выполняется гладко и выбор, будет ли приложение FBML, IFrame или Facebook Connect, можно отложить на последок. Для того чтобы мы могли двигаться дальше и создавать навороченные приложения для Facebook, ниже приведено несколько важных советов.

Используйте environments в symfony для того чтобы поднять несколько тестовых серверов для Facebook Connect

Очень важный аспект философии symfony заключается в быстрой отладке и качественном тестировании приложения. Интеграция с Facebook может серьезно осложнить эту задачу, так как почти все время будет требоваться соединение с Internet для коммуникаций с сервером Facebook и открытый 80й порт для обмена аутентификационными кукисами. Кроме того, есть еще ограничение: приложение, использующее Facebook Connect может быть подключено только к одному хосту. Это становится настоящей проблемой, когда приложение разрабатывается на одной машине, тестируется на другой, помещается в пре-продакшн на третий сервер и, наконец, используется в продуктовом окружении на четвертом.

В этой ситуации наиболее простым решением будет создать приложение для каждого сервера и создать в symfony environment для каждого из них. В симфони это делается легким движением руки ))) делаем копию frontend_dev.php (или его аналога), в frontend_preprod.php и редактируем строку во вновь созданном файле для изменения dev environment’а на новый, который мы назовем preprod:

// заменяем энвайронмент на новый:
$configuration = ProjectConfiguration::getApplicationConfiguration('frontend', 'preprod', true);

Далее, вносим поправки в app.yml для того чтобы сконфигурировать новое Facebook-приложение для каждого нового окружения:

prod:
  facebook:
    api_key: xxx
    api_secret: xxx
    api_id: xxx

dev:
  facebook:
    api_key: xxx
    api_secret: xxx
    api_id: xxx

preprod:
  facebook:
    api_key: xxx
    api_secret: xxx
    api_id: xxx

Теперь приложение тестируемо на каждом отдельном сервере с использованием соответствующей среде frontend_xxx.php точки входа.

Используйте систему логгирования symfony для отладки FBML

Решение с переключением лэйаутов позволяет разрабатывать и тестировать большинство FBML приложений вне сайта Facebook. Тем не менее, финальный тест внутри Facebook может выдавать какие-то невразумительные ошибки. Действительно, основная проблема рендеринга FBML напрямую в Facebook заключается в том, что ошибка 500 обрабатывается и заменяется на не очень информативную стандартную страницу с ошибкой. Кроме того, web debug toolbar, не отображается в Facebook-фрейме. К счастью, на помощь к нам приходит замечательная система логгирования symfony. sfFacebookConnectPlugin автоматически логгирует многие важные действия, вы также с легкостью можете добавить строки в файл лога в любой точке приложения:

if (sfConfig::get('sf_logging_enabled'))
{
  sfContext::getInstance()->getLogger()->info($message);
}

Используйте Proxy во избежание ошибочных редиректов Facebook

Имеется странный баг Facebook, который заключается в том, что когда Facebook Connect сконфигурирован в приложении, Facebook Connect рассматривается как домашняя директория (home) приложения. Не смотря на то, что home может быть сконфигурирован, он должен быть расположен на том же домене, что и Facebook Connect хост. Таким образом, не существует другого решения кроме как сдаться и сконфигурировать home как простой экшен, осуществляющий перенаправление куда потребуется. Следующий код осуществляет перенаправление на Facebook-приложение:

public function executeRedirect(sfWebRequest $request)
{
  return $this->redirect('http://apps.facebook.com'.sfConfig::get('app_facebook_app_url'));
}

Используйте fb_url_for() хелпер

Для создания универсального приложения, которое может быть использовано как FBML внути Facebook или XFBML в iframe в любую (даже последнюю минуту), необходимо уделить внимание проблеме маршрутизации:

• Для FBML-приложения, ссылки внутри приложения должны указывать на /app-name/symfony-route;
• Для iframe приложения важно передавать информацию о сессии facebook при переходе между страницами.

Плагин sfFacebookConnectPlugin предоставляет особый хелпер, который решает указанные проблемы, это fb_url_for() хелпер.

Редиректы внутри FBML приложения

Symfony разработчики быстро привыкают выполнять редирект после успешного POST, и это в общем-то хорошая практика для избежания дублирования данных в БД. Перенаправление в FBML апликации же не работает как ожидается. Вместо этого необходимо применять специализированный таг <fb:redirect> для того чтобы Facebook выполнил редирект. Для сохранения независимости от контекста (FBML таг или обычный редирект) существует специальный статический метод в классе sfFacebook, который может быть использован, например, в экшене сохранения формы:

if ($form->isValid())
{
  $form->save();
  return sfFacebook::redirect($url);
}

Сопоставляем существующих пользователей с их аккаунтами на Facebook

Одна из целей Facebook Connect - упростить регистрацию для новых пользователей. Кроме того, интерес также может представлять сопоставление существующих пользователей с их аккаунтами на Facebook как для получения более полной информации о них, так и для взаимодействия с их фидом. Эта вспомогательная цель может быть достигнута двумя способами:

• Заставить существующих пользователей кликать на кнопку Connect with Facebook. Экшен sfFacebookConnectAuth/signIn не будет создавать нового пользователя, если он уже залогинен, он лишь будет сохранять данные Faceook пользователя для текущего sfGuard-пользователя. Это просто.
• Использовать Facebook-систему распознавания email'ов. Когда пользователь использует Facebook Connect на сайте, Facebook может предоставить специальный хэш его email-адреса, который можно сравнить с хэшами в существующей базе данных для того чтобы определить аккаунт, принадлежащий пользователю. Тем не менее, по соображениям безопасности, Facebook предоставляет указанные хэши только если пользователь был зарегистрирован ранее при помощи его API! Таким образом, необходимо регистрировать email'ы всех новых пользователей, чтобы можно было опознать их впоследствии. Этим и занимается таск registerUsers. Этот таск должен запускаться как минимум каждую ночь для того чтобы регистрировать вновь созданных пользователей. В принципе, вы также можете использовать метод registerUsers из класса sfFacebookConnect: sfFacebookConnect::registerUsers(array($sfGuardUser));

Что дальше?

Надеюсь эта статья выполнит свое назначение: поможет вам начать разработку приложения для Facebook c использованием symfony и пояснит основные возможности разработки для Facebook. Тем не менее sfFacebookConnectPlugin не заменяет собой Facebook API, поэтому чтение оригинальной документации никто не отменял, тем более что там вы можете получить самую полную информацию о разработке для facebook.

В заключение, хочу выразить благодарность сообществу symfony за качество и отзывчивость, в особенности тем, кто уже внес вклад в развитие sfFacebookConnectPlugin своими комментариями и патчами: Damien Alexandre, Thomas Parisot, Maxime Picaud, Alban Creton (и да простят меня все кого я тут не упомянул ))) И, конечно же, если вам есть что сказать или дополнить, не колеблясь вносите свой вклад!

Symfony 2009 advent calendar – это 24 урока продвинутого уровня о symfony. Все уроки представлены на 5 языках: английском, французском, испанском, итальянском, японском. Русского нет, это досадное упущение постараюсь исправить.

Перевод статьи Symfony 2009 advent calendar: day 18 – Developing for Facebook (part 1).

Предисловие: тема разработки для facebook меня достаточно серьезно заинтересовала с полгода назад. После неудачной попытки доложиться по этому вопросу на phpconf’09 (тянул до последнего и не попал в программу))) я хотел систематизировать свои наблюдения и наработки в виде серии статей, однако все было недосуг. И вот, вижу данный урок на symfony, основном моем инструменте последних лет. Поэтому, немного сломав порядок перевода статей advent calendar, задуманный мной, начну с освещения этого интересного материала.

Facebook, со своими 350 миллионами пользователей, де-факто стал стандартом для социальных сетей. Одна из его самых интересных особенностей – это Facebook Platform, API, который позволяет сторонним разработчикам разрабатывать приложения как “внутри” facebook, так и подключать другие сайты и с системой аутентификации facebook (т.н. facebook connect).

Так как фронтэнд facebook’а написан на PHP, неудивительно, что официальная клиентская библиотека к этому API также написана на PHP. Этот факт делает symfony логичным выбором для быстрой разработки качественных приложенией для facebook, а также facebook connect’ед сайтов. Более того, разработка для facebook реально показывает, как вы можете пользоваться всей мощью функциональности symfony, экономя драгоценное время при сохранении высокого качества.

Далее мы рассмотрим следующие вопросы: после краткого описания что из себя представляет facebook api и с чем его едят. Мы расскажем как лучше всего использовать symfony при разработке facebook приложений, как получить отдачу от коммьюнити с помощью sfFacebookPlugin, продемонстрируем все на простом приложении “Hello you!” и, наконец, дадим несколько советов, как решить наиболее типичные проблемы.

Разработка для facebook

Не смотря на то, что API в целом одинаков в обоих случаях, есть два различных юзкейса: мы можем создать приложение “внутри” facebook или же реализовать facebook connect на внешнем сайте.

Facebook приложения

Facebook приложения – это веб приложения внутри facebook. Их основной плюс в том, что они напрямую встраиваются в социальную сеть с более чем 300 миллионами пользователей, что позволяет приложению наращивать посещаемость потрясающими темпами с использованием виральных (вирусных) технологий. Последний и наиболее успешный пример – Farmville, с 60 миллионами активных пользователей ежемесячно и с 2 миллионами поклонников, и эти показатели достигнуты всего за несколько месяцев! Эти цифры эквиваленты населению Франции, которое ежемесячно возвращается для того чтобы работать на своей виртуальной ферме. Facebook приложения взаимодействуют с сайтом и социальной сетью различными способами. Ниже приведены различные варианты того, где приложение может появиться:

Канвас (the Canvas)

Канвас переводится с английского как холст, но в среде русскоговорящих разработчиков более принято прямое произношение. Я буду далее использовать именно его. // hudson

Итак, канва, это, как правило, основная часть приложения. Это небольшой вебсайт, встраиваемый внутрь фрейма facebook.

Вкладка профиля (the Profile Tab)

Приложение также может располагаться на вкладке пользовательского профайла или фанатской страницы. Имеются следующие ограничения:

• Только одна страница. Нет возможности определять ссылки на внутренние страницы приложения на вкладке.
• Никой динамики в виде flash или JavaScript во время загрузки. Для динамической функциональности приложение должно ожидать пользовательского действия на странице (клика на ссылку или кнопку)

Ящик профиля (the Profile Box)

Эта функциональность осталась от старых версий facebook и фактически мало кем используется. Этот атавизм можно найти на вкладке “Boxes” пользовательского профайла.

Дополнительная информационная вкладка (the Information Tab’s Addendum)

Некоторая статическая информация, привязанная к тому или иному пользователю и приложение могут отображаться на информационной вкладке пользовательского профайла.

Публикация заметок и новостной поток (Publishing Notices and in the News Stream)

Приложение может публиковать новости, ссылки, картинки, видеоролики в потоке новостей (news stream) на стенах друзей или напрямую модифицировать статус пользователя.

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

Информационная страница (the Information page)

Это аналог профайла, но для приложения. Эта страница создается автоматически. Это место, где создатель приложения может контактировать с пользователями обычным на facebook образом. Данная страница должна больше заботить маркетологов, нежели девелоперов )))

Facebook Connect

Непереводимая игра слов (прим.пер.) ))) Коннект позволяет подключить к любому вебсайту кое-что из немалой функциональности facebook и предоставить ее пользователям сайта. Уже подключенные сайты легко распознать по большой синей кнопке с текстом “connect with facebook”. Наиболее известные из них – digg.com, cnet.com, netvibes.com, yelp.com и т.д. Ниже перечислены четыре основные причины для того чтобы подключить ваш сайт к facebook:

• Аутентификация одним кликом. Как и OpenID, Facebook Connect предоставляет вашему сайту автоматический логин с использованием facebook сессии. Когда соединение между вебсайтом и facebook установлено пользователем, автоматически создается facebook сессия, тем самым сохраняется время разработчика, которое он потратил бы на свою собственную систему аутентификации.
• Получение более детальной информации о пользователе.Другой полезной особенностью facebook connect является количество данных о пользователе, которые можно получить. Обычно пользователи оставляют на сайтах немного информации о себе, connect позволяет быстро получить дополнительную информацию о пользователе, например пол, местоположение, возраст, аватарку и т.д. Важно помнить, что facebook запрещает хранить персональную информацию пользователей, если пользователь не дал на то явного согласия. С другой стороны можно пользоваться этими данными, не храня их у себя (просто запрашивать у facebook, когда необходимо).
• Виральные коммуникации с использованием новостной ленты. Возможность взаимодействия с новостной лентой пользователя, приглашать друзей или публиковать что-либо на стенах друзей позволяет вебсайту использовать весь виральный потенциал facebook. Любой сайт с социальным уклоном может получить реальную выгоду от этих возможностей, до тех пор пока публикуемая информация имеет социальное значение и может заинтересовать друзей и друзей друзей.
• Преимущества уже существующей социальной сети. Для вебсайтов, которые зависят от социальной сети (типа сети друзей или знакомых), цена построения первого коммьюнити с достаточным числом связей между пользователями, как правило, очень высока. Предоставляя простой доступ к списку друзей пользователя, facebook connect значительно снижает эту цену, устраняя необходимость искать друзей пользователей.

Настройка первого проекта, с использованием sfFacebookConnectPlugin

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

Для начала нужен аккаунт на facebook, с установленным приложением Developer. Для того чтобы создать приложение, достаточно указать его имя.

Установка и настройка sfFacebookConnectPlugin

Следующим шагом будет связка пользователей facebook с пользователями sfGuard. Это основное свойство sfFacebookConnectPlugin. После установки плагина его обязательно нужно сконфигурировать, но это не сложно. API key, application secret и application ID должны быть определены в файле app.yml:

# default values
all:
  facebook:
    api_key: xxx
    api_secret: xxx
    api_id: xxx
    redirect_after_connect: false
    redirect_after_connect_url: ''
    connect_signin_url: 'sfFacebookConnectAuth/signin'
    app_url: '/my-app'
    guard_adapter: ~
    js_framework: none # none, jQuery or prototype.

  sf_guard_plugin:
    profile_class: sfGuardUserProfile
    profile_field_name: user_id
    profile_facebook_uid_name: facebook_uid # WARNING this column must be of type varchar! 100000398093902 is a valid uid for example!
    profile_email_name: email
    profile_email_hash_name: email_hash

  facebook_connect:
    load_routing:     true
    user_permissions: []

Для более ранних версий symfony (<1.3), необходимо установить опцию load_routing в false, так как она используется новой системой маршрутизации.

Настройка facebook приложения

Если ваш проект это facebook приложение (а не connect’ed сайт), тогда есть только один необходимый параметр, который вам нужно указать – этот параметр app_url, который указывает относительный путь к приложению на facebook. Например, для приложения http://apps.facebook.com/my-app, значением app_url будет /my-app

Настройка facebook connect сайта

Если ваш проект – это сайт с facebook connect, следующие конфигурационные параметры могут быть оставлены со значениями по-умолчанию в большинстве случаев:

• redirect_after_connect – позволяет изменить поведение сайта после клика на кнопку “connect with facebook”. По умолчанию, плагин воспроизводит поведение sfGuardPlugin после регистрации.
• js_framework – может быть использован для указания js фреймворка, который вы будете использовать. Очень рекомендуем воспользоваться этой возможностью и остановить выбор каком либо из фреймворков типа jQuery, так как JavaScript в Facebook Connect очень тяжел и может вызывать фатальные сбои (!) в IE6 будучи не загруженным в нужный момент.
• user_permissions – массив прав доступа, которые будут присвоены новому facebook пользователю.

Коннектим sfGuard с Facebook

Связь между пользователем facebook осуществляется благодаря использованию колонки facebook_uid в таблице Profile. Плагин полагает что связь между sfGuardUser и его профайлом с использованием метода getProfile(). Это поведение по-умолчанию для sfPropelGuardPlugin, но для sfDoctrineGuardPlugin потребуется немного танцев с бубном донастроить. Вот возможная схема для Propel:

# schema.yml
sf_guard_user_profile:
  _attributes: { phpName: UserProfile }
  id:
  user_id:            { type: integer, foreignTable: sf_guard_user, foreignReference: id, onDelete: cascade }
  first_name:         { type: varchar, size: 30 }
  last_name:          { type: varchar, size: 30 }
  facebook_uid:       { type: varchar, size: 20 }
  email:              { type: varchar, size: 255 }
  email_hash:         { type: varchar, size: 255 }
  _uniques:
    facebook_uid_index: [facebook_uid]
    email_index:        [email]
    email_hash_index:   [email_hash]

А вот для Doctrine:

sfGuardUserProfile:
  tableName:     sf_guard_user_profile
  columns:
    user_id:          { type: integer(4), notnull: true }
    first_name:       { type: string(30) }
    last_name:        { type: string(30) }
    facebook_uid:     { type: string(20) }
    email:            { type: string(255) }
    email_hash:       { type: string(255) }
  indexes:
    facebook_uid_index:
      fields: [facebook_uid]
      unique: true
    email_index:
      fields: [email]
      unique: true
    email_hash_index:
      fields: [email_hash]
      unique: true
  relations:
    sfGuardUser:
      type: one
      foreignType: one
      class: sfGuardUser
      local: user_id
      foreign: id
      onDelete: cascade
      foreignAlias: Profile

А что делать если проект использует Doctrine и foreignAlias не Profile? В этом случае плагин работать не будет. Но простой метод getProfile() в классе sfGuardUser.class.php, который ссылается на таблицу Profile – решит эту проблему!

Имейте в виду, что колонка facebook_uid должна быть VARCHAR, так как новые профайлы facebook имеют uids свыше 10^15. Лучше жить спокойно с индексированным VARCHAR, чем пытаться заставить работать BIGINT с различными ORM.

Другие две колонки менее важны: email и email_hash нужны только для случая facebook connect сайта с уже существующими пользователями. В этом случае facebook предоставляет сложный процесс сопоставления существующих аккаунтов с новыми аккаунтами facebook connect с использованием хэша email. Мы постарались упростить этот процесс при помощи CLI таска, который поставляется вместе с sfFacebookConnectPlugin. Этот таск будет описан в конце статьи.

Выбор между FBML и XFBML разрешен в пользу symfony ))

Теперь, когда все настроено, мы можем начать кодировать собственно приложение. Facebook предоставляет много специальных тагов, которые отвечают за рендеринг всего функционала, например форму “invite friends”, или полнофункциональную систему комментирования. Эти таги называются FBML или XFBML тагами. FBML и XFBML таги в целом похожи, но от выбора между ними зависит, будет ли приложение рендериться внутри facebook или нет. Если проект – это сайт с Facebook connect, ваш выбор только XFBML. Если же это Facebook приложение, есть две возможности:

• Встроить приложение в IFrame внутри страницы facebook-приложения и использовать XFBML внутри IFrame/
• Встроить приложение “прозрачно” и использовать FBML.

Facebook поощряет разработчиков в использовании их “прозрачного встраивания” или, как его чаще называют, “FBML applicaton”. В самом деле, такие приложения предоставляют ряд интересных особенностей:

• Никаких IFrame’ов, которые всегда усложняют управление
• FBML таги автоматически интерпретируются на стороне facebook и позволяют отображать данные пользователя без необходимости заранее получать их от facebook
• Нет необходимости явно передавать facebook сессию со страницы на страницу

Тем не менее, FBML имеет и недостатки:

• Любой JavaScript должен быть определен непосредственно внутри страницы, что делает невозможным использование сторонних библиотек типа googlemaps, jquery или системы сбора статистики, отличной от Google Analytics, которая официально поддерживается facebook (к слову сказать, в версии FBJS2 обещают добавить поддержку сторонних JS библиотек в FBML приложения // прим. пер.)
• Считается, что FBML таги позволяют ускорить работу приложения, по сравнению с тем, если бы вы пользовались вызовами API. Тем не менее, если приложение не сложное, хостинг на своем сервере будет быстрее.
• FBML приложения сложнее отлаживать, в том числе 500я ошибка перехватывается faceook’ом и заменяется на стандартную.

Согласен с тем что отладка FBML приложения более сложная. Тем не менее, недавно я переводил 30 лучших практик для symfony, там в частности рекомендовалось использовать логгеры вместо привычных многим PHP-разработчикам echo & var_dump. Тут я могу порекомендовать то же самое. Это работает, не зависимо от того, пишите вы на symfony или же на каком-то самописном решении. А вот с JavaScript-отладкой готовьте матюгальник. Без шуток. Даже firebug почти не помогает. Все embedded скрипты парсятся и модифицируются на стороне facebook перед показом. В общем-то вы очень ограничены в выборе клиентских средств (см. FBJS). // hudson

Итак, что же выбрать? Хорошая новость! Symfony и sfFacebookConnectPlugin не требуют от вас подобного выбора. Вы можете писать приложение независимо от его типа и переключаться с IFrame на FBML или на сайт с Facebook Connect имея в основе тот же код. Это возможно, так как технически основное различие между этими типами приложений в их шаблоне (layout), которые очень просто переключать в symfony. Вот вам примеры двух различных шаблонов:

Шаблон для FBML приложения:

<?php sfConfig::set('sf_web_debug', false); ?>
<fb:title><?php echo sfContext::getInstance()->getResponse()->getTitle() ?></fb:title>
<?php echo $sf_content ?>

Шаблон для IFrame/Facebook Connect сайта

<?php use_helper('sfFacebookConnect')?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xmlns:fb="http://www.facebook.com/2008/fbml">
  <head>
    <?php include_http_metas() ?>
    <?php include_metas() ?>
    <?php include_title() ?>
    <script type="text/javascript" src="/sfFacebookConnectPlugin/js/animation/animation.js"></script>
  </head>
  <body>
    <?php echo $sf_content ?>
    <?php echo include_facebook_connect_script() ?>
  </body>
</html>

Для автоматического переключения между ними, просто добавьте следующий код в actions.class.php:

public function preExecute()
{
  if (sfFacebook::isInsideFacebook())
  {
    $this->setLayout('layout_fbml');
  }
  else
  {
    $this->setLayout('layout_connect');
  }
}

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

[html]
 <fb:profile-pic uid="12345" size="normal" width="400" />

на

[html]
 <fb:profile-pic uid="12345" size="normal" width="400"></fb:profile-pic>

Конечно, для того чтобы проделывать эти манипуляции, приложение должно быть настроено также и для Facebook Connect в настройках, даже если оно задумывалось лишь как FBML. Но огромная польза от этого заключается в возможности тестировать приложение локально!

Если вы создаете приложение для facebook и планируете использовать FBML таги, которых по большому счету не миновать по тем или иным причинам, елинственный способ протестировать приложение заключается в размещении кода онлайн и тестировать непосредственно на facebook. К счастью, благодаря Facebook Connect, XFBML таги могут рендериться вне facebook.com. И, как уже было сказано, единственное их отличие в layout’ах. Таким образом, это решение позволяет локально рендерить FBML таги, коль сокоро на локальной машине есть выход в интернет (с facebook так или иначе коннектиться придется).

К тому же, если ваша девелоперская среда доступна через интернет, сервер ли это или у вас домашний компьютер с белым IP и вебсервером на 80м порту, система аутентификации будет работать на facebook.com, благодаря Facebook Connect.

Простейшее приложение

При помощи нижеследующего кода в шаблоне мы закончим разработку нашего приложения “Hello you!”:

<?php $sfGuardUser = sfFacebook::getSfGuardUserByFacebookSession(); ?>
Hello <fb:name uid="<?php echo $sfGuardUser?$sfGuardUser->getProfile()->getFacebookUid():'' ?>"></fb:name>

sfFacebookConnectPlugin автоматически конвертирует пользователя facebook в пользователя sfGuard. Это позволяет быструю интеграцию существующего кода, основанного на sfGuardPlugin.

Продолжение следует! ))
P.S. Если вы прочитали статью до этого места – поставьте пожалуйста оценку. Или даже обоснуйте ее в комментарии. Вам не сложно, а мне приятно и наука на будущее ))