Propel – porady jak rozwiązać podstawowe problemy

Propel, najbardziej popularny system mapowania relacyjno-obiektowego w PHP skraca cykl produkcyjny aplikacji internetowej. Poradnik zawiera zestawienie popularnych problemów, z którymi borykają się początkujący użytkownicy Propela.

Porada 1: Kodowanie znaków

Klasy dostępu do bazy danych mogą stosować dowolne kodowanie znaków, niezależne od ustawień serwera.

Przed uruchomieniem generatora Propel (tj. skryptu propel-gen.bat) w pliku {stala}runtime-conf.xml{/stala} ustalamy kodowanie znaków dla połączenia:

  ...
  utf8

Wygenerowane klasy będą stosowały podane kodowanie. Rozwiązanie takie ma dwie zalety:

• skrypty PHP korzystające z klas nie muszą zawierać żadnych instrukcji ustalających kodowanie,
• konfiguracja kodowania znaków serwera MySQL nie ma wpływu na skrypty.

Porada 2: Korzystanie z kilku baz danych

Skrypt PHP może – za pośrednictwem propelowych obiektów – łączyć się z wieloma bazami danych.

Przed uruchomieniem generatora klas (tj. skryptu {stala}propel-gen.bat{/stala}) w pliku {stala}runtime-conf.xml{/stala} należy wymienić wszystkie bazy danych:

  
    mysql
    
      mysqli
      localhost
      osoby
      osobyadm
      osobypass
      utf8                    
    
  
  
    mysql
    
      mysqli
      localhost
      wyrazy
      wyrazyadm
      wyrazypass
      utf8                    
    
              

Dla każdego wymienionego źródła danych przygotowujemy osobny plik XML z opisem struktury bazy, np.:

wyrazy-schema.xml
osoby-schema.xml

Tak skonfigurowany Propel wygeneruje plik konfiguracyjny -conf.php, umożliwiający łączenie się obiektów z wieloma bazami, przy czym wszystkie wygenerowane klasy trafią do jednego folderu.

Jeśli w pliku build.properties dodamy wpis:

propel.packageObjectModel = true

zaś w plikach {stala}-schema.xml{/stala} umieścimy atrybut package:

to generowane klasy zostaną umieszczone w osobnych folderach. Atrybut package zawierający kropkę:

package=\"core.system\"

spowoduje dalszy podział generowanych folderów na podfoldery:

core/system

W skrypcie PHP, który korzysta z kilku połączeń, należy najpierw wywołać metodę init():

Propel::init(\'dwiebazy-conf.php\');

a następnie utworzyć zmienne umożliwiające korzystanie z połączeń:

$con_osoby = Propel::getConnection(\'osoby\');
$con_wyrazy = Propel::getConnection(\'wyrazy\');

Metody pobierające rekordy z baz danych otrzymają dodatkowy parametr ustalający połączenie:

$wyrazy = WyrazPeer::doSelect(new Criteria, $con_wyrazy);
$osoby = OsobaPeer::doSelect(new Criteria, $con_osoby);

Pierwsza z powyższych instrukcji pobiera dane z bazy o nazwie wyrazy, a druga z bazy o nazwie osoby.

Utworzone obiekty nie wymagają podawania połączenia. Korzystamy z nich identycznie jak w skryptach, które stosowały jedną bazę danych:

echo $osoby[0]->getImie()

$wyrazy[0]->setWyraz(\'Lorem\');
$wyrazy[0]->save();

Porada 3: Pobieranie tylko wybranych kolumn

Obiekty tworzone na podstawie informacji zapisanych w bazie, np. metodą retrieveByPK(), pobierają z bazy danych wszystkie kolumny. To prowadzi do dużych nieoptymalności. Wyświetlenie tytułów artykułów (np. lista nowości na stronie) będzie powodowało pobieranie kompletnych artykułów.

Kolumny, które powinny być pobrane, możemy wskazać korzystając z metod klasy Criteria(). Utworzona poniżej tablica $studenci zawiera tylko imiona studentów:

$c = new Criteria();
$c->clearSelectColumns();
$c->addSelectColumn(StudentPeer::IMIE);
$rs = StudentPeer::doSelectRS($c);
$studenci = array();
while($rs->next()) {
  $tmp = array(
    \'imie\' => $rs->get(1),
  );
  $studenci[] = $tmp;
}

Tak wygenerowane wyniki nie mogą być wykorzystane do operacji save() czy delete(), gdyż nie są obiektami, a stringami.

Kod zwracający wyłącznie wybrane kolumny dodajemy w postaci nowych metod do wygenerowanych klas. Metody te mogą przyjmować parametr klasy Criteria, który pozwoli na wskazywanie wybranych wierszy i sortowanie wyników.

Porada 4: Konwersje toArray(), fromArray()

Metody {stala}toArray(){/stala} oraz {stala}fromArray(){/stala} pozwalają na konwersje obiektów w tablice i na odwrót.

W celu przekształcenia obiektu {stala}$student{/stala}:

$c = new Criteria();
$c->clearSelectColumns();
$c->addSelectColumn(StudentPeer::IMIE);
$rs = StudentPeer::doSelectRS($c);
$studenci = array();
while($rs->next()) {
  $tmp = array(
    \'imie\' => $rs->get(1),
  );
  $studenci[] = $tmp;
}

w tablicę wywołujemy metodę {stala}toArray(){/stala}:

$student = StudentPeer::retrieveByPK(2);

Jeśli jako parametr podamy stałą TYPE_FIELDNAME, to indeksami tablicy będą nazwy kolumn w bazie danych.

Konwersję odwrotną realizuje metoda {stala}fromArray(){/stala}:

$t = $student->toArray(BasePeer::TYPE_FIELDNAME);

Metody {stala}toArray(){/stala} oraz {stala}fromArray(){/stala} możemy wykorzystać w połączeniu z klasami XML_Serializer oraz XML_Unserializer. W ten sposób możemy:

• obiekty konwertować do XML-a ({stala}toArray(){/stala}, {stala}XML_Serializer{/stala}),
• na podstawie danych XML tworzyć obiekty ({stala}XML_Unserializer, fromArray(){/stala}).

Oto, jak przebiega konwersja obiektu na XML:

$t = array(
  \'imie\' => \'Tomasz\',
  \'nazwisko\' => \'Nijaki\',    
  \'plec\' => \'M\',    
  \'wiek\' => \'33\',    
  \'numerindeksu\' => \'00000000001\',    
  \'kierunek\' => \'marketing\',    
);

$s2 = new Student();
$s2->fromArray($t, BasePeer::TYPE_FIELDNAME);
$s2->save();

Porada 5: Wydawanie zapytań SQL

Niekiedy zachodzi konieczność wykonania konkretnych zapytań SQL. W takiej sytuacji należy wykorzystać statyczną metodę {stala}getConnection(){/stala}. Obiekt zwracany przez tę metodę pozwala na wysyłanie do serwera bazy danych zapytań w języku SQL:

$s = StudentPeer::retrieveByPK(1);
$t = $s->toArray(BasePeer::TYPE_FIELDNAME);

$serializer = new XML_Serializer();
$serializer->serialize($t);

$wynik = $serializer->getSerializedData();

Podane wyżej zapytanie wyznacza wartość towaru zapisanego w bazie danych (tj. sumę iloczynów: liczba sztuk x cena jednostki). Wykonanie takiego zadania za pośrednictwem obiektów byłoby znacznie bardziej czasochłonne.

Porada 6: Zliczanie

Szczególnym przypadkiem zapytań SQL jest zliczanie rekordów. W tym celu nie musimy jednak uciekać się do języka SQL, gdyż generowane klasy zawierają metody {stala}doCount(){/stala}.

Oto w jaki sposób możemy wyznaczyć liczbę wierszy zapisanych w bazie danych:

$con = Propel::getConnection(\'produkty\');
$sql = \'SELECT SUM(ilosc * cena) as wartosc FROM produkt\';
$rs = $con->executeQuery($sql);
$rs->next();
$wartosc = $rs->getString(\'wartosc\');

Porada 7: Stronicowanie

Stronicowanie wyników wykonujemy stosując metody {stala}setLimit(){/stala} oraz {stala}setOffset(){/stala} klasy {stala}Criteria{/stala}. Pierwsza z nich ustala liczbę zwracanych rekordów, a druga numer pierwszego zwracanego rekordu:

$ile = WyrazPeer::doCount(new Criteria);

Porada 8: Pobieranie jednego rekordu

Gdy zachodzi konieczność pobrania dokładnie jednego rekordu, przydatna okazuje się metoda {stala}doSelectOne(){/stala}. Z sytuacją taką mamy do czynienia np. wtedy, gdy chcemy do bazy danych wstawić rekord, pod warunkiem że takiego rekordu nie było. Należy najpierw wyszukać rekord, a następnie użyć instrukcji if do zbadania, czy obiekt został utworzony:

$c = new Criteria();
$c->setLimit(4);
$c->setOffset(2);

$wyrazy = WyrazPeer::doSelect($c);

Porada 9: Relacja 1:n, metoda getXs()

Obiekty połączone relacją 1:n są wyposażone w metody o nazwie {stala}getXs(){/stala}, udostępniające dane stojące w relacji. Litera X w nazwie metody jest zastępowana nazwą odpowiedniej tabeli.

Jeśli tabele poeta i wiersz połączymy relacją 1:n (każdy poeta może być autorem wielu wierszy), to w klasie Poeta pojawi się metoda getWierszs(). Metoda ta będzie zwracała obiekty klasy Wiersz:

Oto skrypt drukujący tytuły wierszy poety o identyfikatorze 3:

$c = new Criteria();
$c->add(WyrazPeer::WYRAZ, \'lorem\');
$wyraz = WyrazPeer::doSelectOne($c);

if (!$wyraz) {
  $wyraz = new Wyraz();
  $wyraz->setWyraz($n);
  $wyraz->save();
}

Metoda {stala}getWierszs(){/stala} zwraca wyniki nieuporządkowane. Możemy ją nadpisać w klasie Poeta, by w rezultacie otrzymać metodę {stala}getWierszs(){/stala}, która zachowując pełną funkcjonalność, domyślnie zwraca wyniki posortowane alfabetycznie.

W drugą stronę korzystamy z odwołań kaskadowych. Oto jak ustalić nazwisko poety, który napisał wiersz o identyfikatorze 7:

$poeta = PoetaPeer::retrieveByPK(3);
foreach ($poeta->getWierszs() as $wiersz) {
  echo $wiersz->getTytul();
}

Porada 10: Relacja n:m, metody {stala}getXHasYsJoinX(){/stala}, {stala}getXHasYsJoinY(){/stala}

Obiekty stojące w relacji n:m również mają metody dostępu do skorelowanych danych. Metody te nazywają się zgodnie ze schematem

$wiersz = WierszPeer::retrieveByPK(7);
echo $wiersz->getPoeta()->getImie();

gdzie Z jest nazwą tabeli haszującej, a X oraz Y nazwami tabel połączonych relacją.

Jeśli tabele film oraz aktor połączymy relacją n:m i tabelę haszującą nazwiemy film_has_aktor, to Propel wygeneruje trzy klasy: Film, Aktor oraz FilmHasAktor. W klasie Film znajdziemy metodę {stala}getFilmHasAktorsJoinAktor(){/stala}, a w klasie Aktor metodę {stala}getFilmHasAktorsJoinFilm(){/stala}. Metody te będą zwracały obiekty tabeli {stala}film_has_aktor{/stala}.

Oto skrypt drukujący tytuły wszystkich filmów, w których wystąpił aktor o identyfikatorze 1:

getZsJoinX() (w klasie X)
getZsJoinY() (w klasie Y)

oraz skrypt, który drukuje nazwiska wszystkich aktorów grających w filmie o identyfikatorze 7:

$aktor = AktorPeer::retrieveByPK(1);
$c = new Criteria();
$objs = $aktor->getFilmHasAktorsJoinFilm($c);
foreach ($objs as $obj) {
  echo $obj->getFilm()->getTytul();
}

Korzystając z powyższych metod możemy opracować własne metody, których wyniki będą obiektami klas Film lub Aktor. Przykładem takiej metody jest {stala}getFilmsByAktor(){/stala} (nowa metoda, ręcznie dodana w klasie Aktor), której użycie upraszcza kod skryptu:

$film = FilmPeer::retrieveByPK(7);
$c = new Criteria();
$objs = $film->getFilmHasAktorsJoinAktor($c);
foreach ($objs as $obj) {
  echo $obj->getAktor()->getNazwisko();
}

Porada 14: Wyjątki

W przypadku wystąpienia błędów obiekty Propela generują wyjątki. Obsługę wyjątków realizujemy instrukcją try-catch. Metody obiektu {stala}$e{/stala} pozwalają poznać przyczynę błędu:

class Poeta extends BasePoeta {
  function __toString()
  {
    return $this->getImie() . \' \' . 
        $this->getNazwisko();
  }
}

class Wiersz extends BaseWiersz {
  function __toString()
  {
    return $this->getTytul();
  }
}

Porada 15: Sortowanie wyników wg wybranych kolumn

Porządek sortowania zwracanych wyników ustalamy korzystając z metod {stala}addAscendingOrderByColumn(){/stala} oraz {stala}addDescentingOrderByColumn(){/stala} klasy {stala}Criteria{/stala}:

$wyraz = new Wyraz();
$wyraz->setWyraz(\'żółw\');

try {
  $wyraz->save();
} catch (PropelException $e) {
  $c = $e->getCause();
  $komunikat = $c->getNativeError();
  echo $komunikat;
}

Uruchamianie przykładowych rozwiązań

Każda z powyższych porad jest zilustrowana przykładami. Pojedynczy przykład składa się ze skryptów tworzących bazę danych (pliki .sql i .bat) oraz ze skryptów PHP, które pobierają dane z bazy i prezentują je w postaci strony WWW.

Uruchamianie każdego przykładu należy rozpocząć od utworzenia bazy danych. Następnie przeglądarką odwiedzamy stronę skrypt.php.

Oto jak przebiega uruchomienie przykładu jedenastego. W folderze 11-cala-zawartosc/ znajdziemy dwa podfoldery, a w nich pliki:

$c = new Criteria();
$c->addAscendingOrderByColumn(StudentPeer::NAZWISKO);
$c->addDescendingOrderByColumn(StudentPeer::IMIE);
$studenci = StudentPeer::doSelect($c);

W pliku {stala}tworz-baze-cpp.bat{/stala}, w miejsce napisu AX1BY2CZ3 umieszczamy hasło administratora serwera MySQL:

11-cala-zawartosc/
    1-zrzut-db/
        tworz-baze-cpp.bat
        baza-cpp.sql
    2-skrypt/
        skrypt.php

Następnie uruchamiamy skrypt tworz-baze-cpp.bat, po czym – wykorzystując aplikację phpMyAdmin – sprawdzamy, czy baza danych o nazwie cpp została utworzona. Nazwę tworzonej bazy danych znajdziemy w skrypcie {stala}baza-cpp.sql{/stala}:

c:\mysql\bin\mysql -uroot -pAX1BY2CZ3 < baza-cpp.sql

Porada 11: Pobieranie zawartości całej bazy danych

Ciekawym efektem ubocznym metod {stala}getXs(){/stala} oraz {stala}getZsJoinX(){/stala} jest to, że jeden obiekt może dać dostęp do całej bazy danych.

Umieścimy w bazie danych książki podzielone na rozdziały, które z kolei zawierają zadania. Otrzymamy trzy tabele: ksiazka, rozdzial oraz zadanie. Relacją 1:n łączymy tabele ksiazka i rozdzial (każda książka zawiera wiele rozdziałów) oraz rozdzial i zadanie (każdy rozdział zawiera wiele zadań). Propel wygeneruje klasy:

$aktor = AktorPeer::retrieveByPK(1);
$c = new Criteria;
$filmy = $aktor->getFilmsByAktor($c);
foreach ($filmy as $film) {
  ...
}

Jeśli w bazie danych znajduje się jeden rekord o identyfikatorze 1 (zbiór zadań z programowania w języku C++), to wywołanie:

Ksiazka
  metoda getRozdzials()
  
Rozdzial
  metoda getZadanies()
  
Zadanie

zapewni dostęp do całej bazy danych. Podwójna pętla foreach wydrukuje całą książkę (wszystkie rozdziały i wszystkie zadania):

$ksiazka = KsiazkaPeer::retrieveByPK(1);

Porada 12: Smarty i wielokrotne wywoływanie metod

Szablony Smarty domyślnie nie pozwalają na wielokrotne wywoływanie metod. Instrukcje szablonu:

PRZYKŁAD NIEPOPRAWNY

foreach ($ksiazka->getRozdzials() as $rozdzial) {
  echo $rozdzial->getTytul();
  foreach ($rozdzial->getZadanies() as $zadanie) {
    echo $zadanie->getTekst();
  }
}

będą powodowały błąd. W celu ominięcia tego problemu możemy zmodyfikować klasę Smarty_Compiler. Jeśli w pliku {stala}Smarty_Compiler.class.php{/stala} wymienimy wyrażenie regularne zawarte w linijce 155 i w miejsce:

{$wiersz->getAutor()->getImie()}

wpiszemy:

...$this->_dvar_guts_regexp . \')\';

wielokrotne wywołanie metod będzie działało poprawnie.

Powyższa niedogodność sytemu Smarty jest na tyle dokuczliwa, że rozsądnym wydaje się rezygnacja z szablonów Smarty na rzecz surowych szablonów PHP.

Porada 13: Metoda __toString()

Metoda {stala}__toString(){/stala} służy do konwersji obiektu na typ string. Jeśli wygenerowane klasy wzbogacimy o metody {stala}__toString(){/stala}, to będzie można stosować obiekty jako parametry instrukcji echo, np.:

..$this->_dvar_guts_regexp . \'(?:\(\))?)\';

Instrukcje:

$poeta = PoetaPeer::retrieveByPK(3);
echo $poeta;
foreach ($poeta->getWierszs() as $wiersz) {
    echo $wiersz;
}

będą działały poprawnie, pod warunkiem że w klasach Poeta oraz Wiersz dodamy metody {stala}__toString(){/stala}:

echo $poeta;
echo $wiersz;