Routing Symfony w skryptach JavaScript

FOSJsRoutingBundle to paczka, która rozwiązuje problem odwoływania się do aplikacji Symfony z poziomu skryptów JavaScript, np. przy definiowaniu akcji AJAX-owych. Problem może nie jest wielki, bo oczywiście można URL-e zapisać na sztywno, ale w takim wypadku nie można korzystać z dobrodziejstw środowiska dev.

Dzięki wspomnianej paczce URL do akcji w Symfony można wygenerować podobnie jak w PHP:

var url = Routing.generate('my_route_to_expose', { id: 10, foo: "bar" });

FOSJsRoutingBundle umożliwia zarówno dynamiczne jak i statyczne generowanie tras. W tym pierwszym wypadku aplikacja Symfony jest dynamicznie odpytywana o trasy, dzięki czemu zmiany w aplikacji od razu są widoczne w JavaScriptcie. Ten tryb warto wybrać w czasie developmentu albo w zastosowaniach, gdzie nieco mniejsza wydajność nie będzie problemem. W trybie statycznym należy poleceniem z konsoli wygenerować plik zawierający definicję routingu dla JS.

Poniżej opiszę instalację paczki w Symfony i konfigurację w trybie statycznym.

Tradycyjnie zacząłem od instalacji paczki composerem:

composer require friendsofsymfony/jsrouting-bundle

Po zainstalowaniu paczki dodałem ją do app/AppKernel.php:

public function registerBundles()
{
    $bundles = array(
        // ...
        new FOS\JsRoutingBundle\FOSJsRoutingBundle()
    );
}

Kolejnym krokiem jest skopiowanie statycznych plików do katalogu web:

app/console assets:install

Połączenie pomiędzy Symfony i JavaScriptem stanowią dwa skrypty, które dodałem do podstawowego szablonu strony:

<script src="{{ asset('bundles/fosjsrouting/js/router.js') }}"></script>
<script src="{{ asset('js/fos_js_routes.js') }}"></script>

Następnie należy w definicji routingu wskazać, które trasy mają być dostępne w JavaScriptcie. Dokumentacja pokazuje konfigurację YAML-ową, ja zaś używam annotacji:

/**
 * @Route("/sugeruj-produkt", name="suggest_product", options={"expose": true})
 */

Ostatnim krokiem jest wygenerowanie pliku z routingiem:

app/console fos:js-routing:dump

Teraz wszystko będzie grać i buczeć.

Testowe adresy email

Dzisiaj kilka słów o mailach w kontekście programowania (lub testowania) aplikacji internetowych. Najprościej rzecz ujmując, warto mieć pod ręką duuużo adresów email, co przydaje się przy np. testowaniu rejestracji albo mailingu. Skąd je wziąć?

W Internecie jest całe mnóstwo darmowych kont pocztowych, ale zakładanie dziesiątek kont, pamiętanie do nich haseł i logowanie się na każde z nich byłoby uciążliwe. Na szczęście Dobrzy Ludzie stworzyli różne usługi i narzędzia, które ten problem rozwiązują.

Tymczasowe konta

Najprostsze w użyciu są usługi w rodzaju niepodam.pl i migmail.pl. Wystarczy podać dowolny adres w domenie niepodam.pl albo migmail.pl, np. michal@niepodam.pl, a następnie wejść na taką stronę, wpisać wybrany login i już można czytać maile wysłane na ten adres.

migmail

Ponieważ takich adresów nie trzeba rejestrować można je równie dobrze generować automatycznie, co przydaje się np. przy testowaniu mailingu. Ja najczęściej korzystam z nich w środowiskach, które wysyłają „prawdziwe” maile np. UAT i produkcyjnym.

Wadą tych rozwiązań jest to, że wyświetlanie wiadomości w formacie HTML nie zawsze działa jak powinno, np. linki są obcięte albo nieklikalne, a elementy graficzne źle rozmieszczone. Dlatego słabo nadają się do testowania wyglądu maili.

Warto też pamiętać, że są to tymczasowe konta i wiadomości są usuwane automatycznie po kilku godzinach lub dniach.

GMail

Każde konto GMail ma dwie cechy, które przydają się przy mnożeniu aliasów:

  • Wszystkie występujące w nazwie użytkownika kropki są ignorowane.
  • Po nazwie użytkownika można postawić znak „plus” i wpisać dowolny tekst, który także zostanie zignorowany.

W efekcie dysponując kontem imienazwisko@gmail.com możemy generować unikalne adresy do woli, np. imie.nazwisko@gmail.com, i.m.i.e.nazwisko@gmail.com, imienazwisko+test1@gmail.com, imie.nazwisko+test2@gmail.com itd.

MailCatcher

MailCatcher to prosty demon SMTP, który całą korespondecję, która przez niego przechodzi pozwala przeglądać za pomocą prostego interfejsu webowego. Demon nie sprawdza poprawności adresów, więc można używać dowolnych loginów i domen, np. qwerty@aplikacja.dev. Najlepiej spisuje się w środowisku deweloperskim, które niekoniecznie ma wyjście do Internetu.

MailCatcher jest napisany w Ruby, więc o ile to środowisko uruchomieniowe tego języka nie jest zainstalowane na serwerze trzeba wykonać następujące polecenie:

aptitude install ruby ruby-dev libsqlite3-dev build-essential

Kiedy Ruby już działa to można zainstalować MailCatchera:

gem install mailcatcher

Uruchomienie MailCatchera z konsoli:

mailcatcher --foreground --http-ip=0.0.0.0

Domyślnie SMTP nasłuchuje na porcie 1025, a interfejs webowy jest dostępny na porcie 1080. Oczywiście takie niestandardowe parametry SMTP należy podać w konfiguracji PHP albo aplikacji.

W Symfony2 wystarczy dodać parametr port w konfiguracji SwiftMailera (w standardowej konfiguracji go nie ma). W pliku app/config/config.yml dodajemy:

swiftmailer:
    transport: "%mailer_transport%"
    host:      "%mailer_host%"
    username:  "%mailer_user%"
    password:  "%mailer_password%"
    port:      "%mailer_port%"

Zaś w app/config/parameters.yml:

parameters:
    # ...
    mailer_transport: smtp
    mailer_host: 127.0.0.1
    mailer_user: null
    mailer_password: null
    mailer_port: 1025
    # ...

Twig Extensions w aplikacji Symfony2

Twig sam z siebie ma sporo wygodnych funkcji, ale kilka bardzo przydatnych udogodnień nie trafiło do głównej biblioteki lecz do osobnej paczki Twig Extensions. W wypadku standardowej aplikacji Symfony2 te rozszerzenia już są uwzględnione w composer.json, ale jeśli nie to można jest zainstalować poleceniem:

composer require twig/extensions ~1.1.0

Trzeba je także włączyć w konfiguracji aplikacji, tak jak każde inne rozszerzenie Twiga:

services:
    twig.extension.intl:
        class: Twig_Extensions_Extension_Intl
        tags:
            - { name: twig.extension }

Powyższy przykład dodaje rozszerzenie Intl, które podobnie jak biblioteka Intl ułatwia formatowanie danych zgodnie z ustawieniami lokalizacji. Obecnie w Twig Extensions dostępne są następujące klasy:

  • Twig_Extensions_Extension_Array
  • Twig_Extensions_Extension_Date
  • Twig_Extensions_Extension_I18n
  • Twig_Extensions_Extension_Intl
  • Twig_Extensions_Extension_Text

Przy założeniu, że aplikacja ma ustawione polską lokalizację to wyświetlenie daty w postaci „13 listopada 2014” wygląda tak:

{{ meeting.date|localizeddate('long', 'none') }}

Wyświetlenie liczby z częścią dziesiętną:

{{ player.power|round(2)|localizednumber }}

Przy korzystaniu z filtra localizednumber tylko liczby z częścią ułamkową będą wyświetlane z przecinkiem, a liczby całkowite są wyświetlane bez przecinka.

Checkbox kontra NOT NULL

W encji mamy pole legal1 typu boolean, które nie może być NULL-em.

    /**
     * @var boolean
     *
     * @ORM\Column(name="legal1", type="boolean", columnDefinition="TINYINT(1)")
     */
    private $legal1;

W formularzu pole jest prezentowane jako checkbox. Niby wszystko powinno działać, a jednak jeśli wyślemy formularz bez zaznaczania checkboxa to na encji nie jest wywoływana metoda setLegal1(), a w rezultacie Doctrine próbuje zapisać NULL jako wartość pola legal1, co oczywiście kończy się wyjątkiem.

Można kombinować na samej encji (np. zwracać z getLegal1() 0 jeśli wartość to NULL), ale chyba najbardziej eleganckim rozwiązaniem będzie zastosowanie transformera, który będzie tłumaczył wartości pomiędzy encją a formularzem. Prościutki transformer realizujący takie zadanie może wyglądać tak.

namespace MDurys\CommonBundle\Lib\DataTransformer;

use Symfony\Component\Form\DataTransformerInterface;

class BoolTransformer implements DataTransformerInterface
{
    public function transform($input)
    {
        return boolval($input);
    }

    public function reverseTransform($input)
    {
        return intval($input);
    }
}

W formularzu należy go zastosować jako model transfomer:

    $builder
        ->add(
            $builder->create('legal1', 'checkbox')->addModelTransformer(new BoolTransformer())
            )

Jego działanie polega na tym, że podczas tworzenia formularza zostanie wywołana metoda transform(), która wartość z bazy danych (0 lub 1) rzutuje na wartość boolowską. Z kolei podczas zapisywania formularza zostanie wywołana metoda reverseTransform(), która rzutuje wartość z formularza na liczbę całkowitą. Tym sposobem z NULL-a zrobi się 0.

Symfony2, Twig i SwiftMailer czyli rzecz o obrazkach w mailu

Ongiś pisanie maili w HTML-u było naruszeniem netykiety, ale obecnie zdecydowana większość odbiorców jak i nadawców woli otrzymywać maile w HTML-u. Generowanie i wysyłanie takowych w aplikacji opartej na Symfony2 jest banalnie proste dzięki Twigowi i Swift Mailerowi. Nieco mniej przyjemnie zaczyna się robić, kiedy w treści maili ma pojawić się grafika.

Możliwości są dwie i każda rodzi pewne problemy:

  1. Linkowanie do plików na zdalnym serwerze. Niestety funkcja url() w Twigu akceptuje tylko ścieżki zdefiniowane w routingu, nie można nią linkować do grafik. Z kolei znacznik image obsługiwany przez Assetica domyślnie generuje relatywne URL-e, a poza tym jest trochę nieporęczny w użyciu.
  2. Osadzenie plików w wiadomości. Tu problem natury programistycznej polega na tym, że żeby osadzić grafikę w wiadomości trzeba skorzystać z metody Swift_Message::embed(), do której nie mamy dostępu z poziomu Twiga.

Wszystkie powyższe problemy można rozwiązać tworząc rozszerzenie do Twiga.

namespace MDurys\MailBundle\Twig;

use Symfony\Component\DependencyInjection\ContainerInterface;

class MailExtension extends \Twig_Extension
{
    private $kernel;

    private $host;

    private $imageCache;

    private $messageCache;

    public function __construct(ContainerInterface $container)
    {
        $context = $container->get('router')->getContext();
        $this->host = $context->getScheme() . '://' . $context->getHost();
        $this->kernel = $container->get('kernel');
    }

    public function getFunctions()
    {
        return array(
            new \Twig_SimpleFunction('mail_embed', array($this, 'mailEmbed')),
            new \Twig_SimpleFunction('mail_url', array($this, 'mailUrl')),
        );
    }

    public function mailEmbed(\Swift_Message $message, $file)
    {
        if (!isset($this->messageCache[$message->getId()][$file]))
        {
            if (!isset($this->imageCache[$file]))
            {
                $this->imageCache[$file] = \Swift_Image::fromPath($this->kernel->locateResource($file));
            }
            $this->messageCache[$message->getId()][$file] = $message->embed($this->imageCache[$file]);
        }
        return $this->messageCache[$message->getId()][$file];
    }

    public function mailUrl($file)
    {
        return $this->host . $file;
    }

    public function getName()
    {
        return 'mdurys_mail_extension';
    }
}

Rozszerzenie udostępnia dwie funkcje Twiga: mail_embed() i mail_url(), które odpowiednio umożliwiają osadzenie obrazka w wiadomości i wygenerowanie abosultnego URL-a do zasobu. Osadzane obrazki są cacheowane, więc jeśli dany obrazek jest wykorzystywany kilka razy w danej wiadomości to zostanie osadzony tylko raz, a jeśli obrazek zostanie osadzony w kilku wiadomościach to proces konwersji na obiekt Swift_Image zostanie wykonany tylko raz.

Aby móc z tego rozszerzenia korzystać należy je uaktywnić w services.yml bundla. Ważne jest, żeby otagować usługę jako „twig.extension”.

services:
  mdurys.twig.mail_extension:
    class: MDurys\MailBundle\Twig\MailExtension
    arguments: [ "@service_container" ]
    tags:
      - { name: twig.extension }

Jeśli chcemy osadzić obrazek w wiadomości to podczas renderowania szablonu trzeba przekazać obiekt wiadomości.

$message = \Swift_Message::newInstance();
$htmlPart = $this->renderView(
    'MailBundle:Test:email.html.twig',
    array('message' => $message)
    );
$message
    ->setFrom('mail@example.com')
    ->setTo('test@fexample.com')
    ->setSubject('Mail z obrazkami')
    ->setBody($htmlPart, 'text/html');
$this->get('mailer')->send($message);

W szablonie Twiga wystarczy wywołać funkcję mail_embed() przekazując jej jako parametry obiekt wiadomości i lokalizację pliku.

<img src="{{ mail_embed(message, '@MDurysMailBundle/Resources/public/images/smiley.gif') }}" width="16" height="16" alt=":-)" />

Linkowanie do zewnętrznych zasobów jest prostsze i sprowadza się do wywołania funkcji mail_url() w szablonie:

<img src="{{ mail_url('/bundles/mdurysmail/images/big_logo.jpg') }}" width="600" height="240" alt="Big Logo" />

Wyłączanie akcji w generatorze Symfony

Generator modułów administracyjnych w Symfony nie umożliwia wybrania akcji, które dany moduł ma wykonywać, zawsze dostajemy pełen zestaw CRUD. Czasami zachodzi potrzeba zablokowania niektórych akcji, np. w wypadku logów bezpieczeństwa sens ma jedynie index (przeglądanie listy), a jakakolwiek modyfikacja powinna być zabroniona.

Odnośniki widoczne na liście można łatwo ukryć edytując plik generator.yml, wystarczy domyślne akcje zastąpić pustymi listami.

generator:
  param:
    config:
      list:
        title:             Permission changes log
        actions:           {}
        object_actions:    {}
        batch_actions:     {}
      filter:
        display:           [agent_user_name, subject_user_name, permission_name, created_at]

Akcje można jednak dalej wykonywać ręcznie wpisując URL, dlatego należy je zablokować w kontrolerze.

class permission_logActions extends autoPermission_logActions
{
  public function preExecute()
  {
    $this->forward404If($this->getActionName() !== 'index', 'Action disabled');
    parent::preExecute();
  }
}

Zapisywanie osadzonych formularzy w Symfony

Zapisywanie osadzonych formularzy w Symfony działa inaczej niż intuicyjnie zakładałem. Co ciekawsze, już raz się z tym kiedyś zetknąłem, ale było to na tyle dawno, że zapomniałem rozwiązania.

Załóżmy, że w zwykłym formularzu dziedziczącym z klasy sfForm osadzam formularz oparty na modelu z bazy danych czyli dziedziczący z sfFormDoctrine.

class OnePageCheckoutForm extends sfForm
{
  public function configure()
  {
    $this->widgetSchema['same_address'] = new sfWidgetFormInputCheckbox();
    $this->validatorSchema['same_address'] = new sfValidatorBoolean();

    $this->embedForm('customer', new CustomerForm());
    $this->embedForm('shipment_address', new AddressForm());
    $this->getWidgetSchema()->setNameFormat('checkout_form[%s]');
  }
}

W kontrolerze chcę zapisać dane z osadzonych formularzy, ale oczywiście klasa OnePageCheckoutForm nie ma metody save(). W pierwszym odruchu napisałem mniej więcej coś takiego:

public function executeCheckout(sfWebRequest $request)
{
  if (!$this->getUser()->hasCart())
  {
    return $this->redirect('@cart');
  }
  $this->cart = $this->getUser()->getCart();

  $this->form = new OnePageCheckoutForm();
  if ($request->getMethod() == 'POST')
  {
    $this->form->bind($request->getParameter($this->form->getName()), $request->getFiles($this->form->getName()));
    if ($this->form->isValid())
    {
      $values = $this->form->getValues();
      $this->form->getEmbeddedForm('customer')->save();
      $this->form->getEmbeddedForm('shipment_address')->save();

      $this->cart->setCustomerId($this->form->getEmbeddedForm('customer')->getObject()->getId());
      $this->cart->save();
      $this->redirect('@cart_payment_process');
    }
  }
}

Ku memu zaskoczeniu zobaczyłem wyjątek, z którego wynikało, że zapis formularza customer się nie powiódł, bo formularz nie zawiera danych. Dla pewności wrzuciłem w kod kilka var_dumpów:

// wynik: dane dla całego formularza łącznie z osadzonymi
var_dump($this->form->getValues());
// wynik: false
var_dump($this->form->getEmbeddedForm('customer')->isBound());
// wynik: pusta tablica
var_dump($this->form->getEmbeddedForm('customer')->getObject()->toArray());

Jak się okazało, formularz klasy sfForm nie aktualizuje obiektów w osadzonych formularzach, trzeba to wykonać samemu:

$this->form->getEmbeddedForm('customer')
  ->updateObject($this->form->getValue('customer'));

Można to zrobić w kontrolerze, ja ze względów konwencjonalno-estetycznych dopisałem do klasy OnePageCheckoutForm metody updateEmbeddedForms() i saveEmbeddedForms(), które są z grubsza kopią tak samo nazwanych metod z klasy sfFormObject.

Doctrine Query Cache w Symfony

Dzisiaj o odkrywaniu Ameryki w konserwie. Właśnie takie miałem wrażenie, gdy dłubiąc w projekcie trafiłem na rozdział na temat cache w dokumentacji Doctrine. Wcześniej tam nie trafiłem, bo całe keszowanie robiłem w Symfony – wszak do pamięci podręcznej najlepiej wrzucać efekt końcowy. Dodatkowo w dokumentacji Symfony nie rzuciło mi się w oczy nic na temat cacheowania w Doctrine.

Nie zamierzam streszczać dokumentacji Doctrine. W kontekście tej notki ważne jest, że Doctrine może zapamiętywać w cache dwa rodzaje danych:

  • skompilowane zapytania
  • wyniki zapytań

Dzięki zapamiętywaniu zapytań czasochłonny proces parsowania zapytania i budowania docelowej SQL-ki jest wykonywany tylko raz, kolejne wywołania będą korzystać z danych zapamiętanych w pamięci podręcznej. Problem aktualności danych w cache nie istnieje ponieważ zmiana zapytania spowoduje automatyczne wygenerowanie nowych danych. Korzyści są niebagatelne, użycie proste jak konstrukcja cepa, a problemów nie ma. Dlatego zgodnie z dokumentacją i zdrowym rozsądkiem, pamięć podręczna zapytań powinna być zawsze włączona, nawet w środowisku testowym.

Włączenie cache dla Doctrine w projekcie Symfony jest banalne i sprowadza się do dodania króciutkiej metody w klasie config/ProjectConfiguration.class.php.

public function configureDoctrine(Doctrine_Manager $manager)
{
    $manager->setAttribute(Doctrine_Core::ATTR_QUERY_CACHE, new Doctrine_Cache_Apc());
}

Powyższy kod spowoduje, że skompilowane zapytania będą zapamiętywane w pamięci APC. Oprócz APC Doctrine może współpracować z serwerem memcached lub inną bazą danych (np. SQLite).

Cache można włączyć nie tylko na poziomie managera, równie dobrze można zrobić to w samym zapytaniu:

$q = Doctrine_Query::create()
    ->useQueryCache(new Doctrine_Cache_Apc());

Jak wspomniałem wcześniej, pamięć podręczna zapytań powinna być włączona zawsze. Na poziomie konkretnego zapytania więcej sensu ma włączanie zapamiętywania wyników:

$q = Doctrine_Query::create()
    ->useResultCache(new Doctrine_Cache_Apc());

Etykiety w YAML-u przyjacielem leniwego programisty

Sympatyczny wynalazek, jakim jest YAML, jest używany w Symfony niemal na każdym kroku. I bardzo lepiej, bo to bardzo przyjazny człowiekowi format zapisu. Dokumentacja Symfony na temat YAML-a jest jednak dość lakoniczna i nie opisuje wszystkich jego możliwości. Jednym z pominiętych zagadnień są na ten przykład etykiety, które pozwalają zredukować ilość wklepywanych danych.

Etykiety najbardziej przydają się przy definiowaniu danych statycznych aplikacji (fixtures). Załóżmy, że tworzymy katalog usług hostingowych. Usługę VPS można opisać chociażby tak:

  vps_hitme_openvz_128: &vps_hitme_openvz
    Company:            hitme
    name:               OpenVZ 128
    Virtualization:     openvz
    guaranteed_memory:  128
    burstable_memory:   256
    swap_memory:        0
    disk_space:         20
    uplink:             100
    downlink:           100
    bandwidth:          50
    ip_4_addresses:     1
    ip_6_mask:          64
    root_access:        true
    is_managed:         false
    url:                http://www.hitme.net.pl/openvz-details.php
    is_verified:        true
    is_active:          true

Kolejne pakiety różniące się od powyższego tylko nazwą, ilością dostępnej pamięci, powierzchnią dyskową i transferem można opisać o wiele krócej:

  vps_hitme_openvz_256:
    <<:                 *vps_hitme_openvz
    name:               OpenVZ 256
    guaranteed_memory:  256
    burstable_memory:   512
    disk_space:         20
    bandwidth:          100

Składnia i działanie etykiet w powyższym przykładzie są oczywiste, opiszę je jedynie dla porządku. Etykietę poprzedzamy znakiem &. Dane oznaczone etykietą włączamy używając operatora << jako klucza, którego wartością jest nazwa etykiety poprzedzona *. Spowoduje połączenie tablicy oznaczonej etykietą z bieżącą tablicą. Jeśli w obu tablicach występuje ten sam klucz to zostanie użyta wartość z bieżącej tablicy. Prawda, że przydatne?