Agavi - Wprowadzenie | Strzałek’s devblog

Agavi - Wprowadzenie

May 16, 2008
Komentarzy: 7
Kategoria: PHP
Tags: agavi, framework, mvc, PHP

Agavi jest frameworkiem MVC napisanym w PHP5. Jest on stosunkowo słabo znany w środowisku programistów PHP. Przyczyną tego jest to iż dopiero od niedawna dostępne jest Agavi oznaczone wersją 0.11, które ma zamrożone API. Jednak przede wszystkim framework ten nadal nie posiada dokumentacji, co właściwie go dyskwalifikuje. Developerzy Agavi obiecują że dokumentacja się wreszcie pojawi, ja tymczasem postaram się częściowo załatać dziurę serią artykułów o tym świetnym frameworku.

Model View Controller

Tak jak pisałem we wstępie - Agavi jest frameworkiem którego działanie opiera się na wzorcu projektowym - MVC - Model View Controller.

Wg. tego wzorca aplikacja dzieli się na 3 części. Nie zagłębiając się w szczegóły odpowiednie warstwy odpowiadają za

Model - pozyskiwanie danych (Baza danych, Web Services etc.)
View (Widok) - przedstawienie pozyskanych danych użytkownikowi (zwrócenie html, xml, pdf etc.)
Controller (Kontroler) - analiza żądania użytkownika i uruchomienie odpowiedniego modelu i widoku.

W Agavi znajdują się dodatkowo akcje które to są wywoływane przez kontroler. Akcja natomiast może posiadać kilka widoków.

Instalacja

Zacznijmy od utworzenia struktury folderów na naszym serwerze. Składać się na nią będą:

/agavi_application
- /app - nasza aplikacja
- /dev - narzędzia które będą pomoce w momencie tworzenia aplikacji
- /libs - biblioteki (agavi, doctrine, smarty etc.)
- /pub - publiczny folder

Możemy ściągnąć najnowszą wersję Agavi ze strony frameworka. W momencie pisania artykuły najnowszą wersją jest 0.11.1. Po ściągnięciu, należy rozpakować paczkę, zmienić nazwę folderu na “agavi” i przenieść go do folderu libs.

Następnie przygotujmy sobie generatora. Skrypt ten używa phing’a, aby go zainstalować należy wykonać następujące komendy w konsoli (musisz mieć skonfigurowany pear).

[Show Plain Code]:

$ pear channel-discover pear.phing.info
$ pear install phing/phing

Skopiujmy skrypt agavi.bat-dist, który znajduje się w /libs/agavi/etc, do /dev zmieniając jego nazwę na agavi.bat. Używając naszego ulubionego edytora tekstowego zmieńmy ścieżki znajdujące się w skrypcie:

[Show Plain Code]:

set PHING_COMMAND=C:\Server\php\phing.bat
set AGAVI_INSTALLATION=C:\Server\www\agavi_application\libs\agavi\src

Tak wyglądają ścieżki w moim przypadku. Pierwsza wskazuje plik skryptu phing, druga źródła agavi.

Mając już gotowe narzędzie możemy uruchomić konsole i wykonać skrypt agavi.bat:

[Show Plain Code]:

C:\Server\www\agavi_application> dev\agavi.bat project

Skrypt będzie nas pytał o różne ciekawe rzeczy. My grzecznie za każdym razem wciskamy enter. Po ok 45 sek. generator powinien poinformować nas że zakończył swoją pracę sukcesem, natomiast my po uruchomieniu aplikacji - http://localhost/agavi_application/pub/ powinniśmy zobaczyć logo agavi. Oznaczać to będzie że wszystko generator stworzył za nas pierwszą aplikację opierającą się na Agavi.

Budowa aplikacji

Aplikacje pisane na Agavi mają budowę modularną. Każdy moduł składa się z akcji. Akcja może mieć kilka widoków, widok natomiast może używać różnych szablonów. Przykładowo: moduł News, posiada akcję Add, która posiada widoki Input (formularz dodawania newsa) oraz Success (wiadomość o dodaniu newsa).

Tak w dużym skrócie wyglądają moduły. Moduły dodatkowo mogą posiadać własną konfigurację, pliki validatora, lub inne biblioteki które są używane przez moduł.

Stwórzmy sobie przykładowy moduł Notes, który będzie modułem notek bloga. Wygenerujmy sobie ten moduł używając generatora agavi:

[Show Plain Code]:

$ dev\agavi.bat module

Generator będzie pytał nas o:

Nazwa modułu: Notes
Akcje: Index,ShowOne,Add
Widoki dla akcji Index,ShowOne: Success (obie akcje tylko po 1 widoku), dla akcji Add: Success,Input
Modele: Notes

Generator powinien stworzyć za nas wszystkie foldery, pliki z szablonami klas, oraz puste pliki szablonów. Pozostaje nam teraz dopisać logikę aplikacji.

Konfiguracja

Agavi jest frameworkiem który w dużym stopniu opiera się na konfiguracji. Konfiguracja znajduje się w plikach XML, składa się na nią 13 podstawowych plików oraz dodatkowe pliki które może posiadać każdy z modułów. Ilość plików na początku może przerażać, jednak zapewniam że gdy dobrze poznamy ten framework, konfiguracja stanie się bardzo prosta i intuicyjna. Generator stworzył nam domyślną konfigurację i na niej będziemy się opierać. Zmienimy jedynie 4 pliki.

settings.xml

Ustawiamy akcję Index modułu Notes jako domyślną.

XML [Show Plain Code]:

<system_action name="default">
                                <module>Notes</module>
                                <action>Index</action>
                        </system_action> 

oraz włączamy komponent bazy danych:

XML [Show Plain Code]:

<setting name="use_database">true</setting> 

databases.xml

Deklarujemy driver którego będziemy używać (w naszym przypadku PDO ale nic nie stoi na przeszkodzie abyś użył Propela, Doctrine lub cokolwiek innego) oraz dane potrzebne do nawiązania połączenia z bazą danych.

XML [Show Plain Code]:

< ?xml version="1.0" encoding="UTF-8"?>
<configurations xmlns="http://agavi.org/agavi/1.0/config">      
        <configuration>
                <databases default="pdo_mysql">   
                        <database name="pdo_mysql" class="AgaviPdoDatabase">
                                <parameter name="dsn">mysql:host=localhost;dbname=agavi_application</parameter>
                                <parameter name="username">root</parameter>
                                <parameter name="password">pass</parameter>
                        </database>               
                </databases>
        </configuration>
</configurations> 

routing.xml

Plik z drogami. Zadeklarowaliśmy 3 scieżki. Pierwsza zostanie wybrana, gdy adres będzie wyglądał np. tak:
http://strona.pl/notes/123/html. Wykonana zostanie wtedy akcję ShowOne modułu Notes, przekazując parametr id o wartości 123. Druga pokaże nam formularz dodawania notki, a trzecia domyślną akcję.

XML [Show Plain Code]:

< ?xml version="1.0" encoding="UTF-8"?>
<configurations xmlns="http://agavi.org/agavi/1.0/config">
        <configuration>
                <routes>                        
                        <route name="note_one" pattern="^/note/(id:\d+).html$" module="Notes" action="ShowOne" />
                        <route name="note_add" pattern="^/add.html$" module="Notes" action="Add" />
                        <route pattern="^/$" module="%actions.default_module%" action="%actions.default_action%" />
                </routes>
        </configuration>
</configurations> 

output_types.xml

W sekcji layouts, dodajemy jedną warstwę. Dekorator, czyli nasz “główny” szablon.

XML [Show Plain Code]:

<layer name="decorator">
      <parameter name="template">%core.app_dir%/templates/Master</parameter>
</layer> 

Model

Pisanie aplikacji zaczniemy od modelu. Zaimplementujemy w nim metody które będą potrzebne dla akcji/widoków. Będą to metody: getRecent (zwrócenie ostatnich kilku notek), getById (zwrócenie notki o danym id) oraz save (zapis):

PHP [Show Plain Code]:

< ?php
 
class Notes_NotesModel extends ProjectBaseModel
{
  public $dbLayer = null;
 
        public function initialize(AgaviContext $context, array $parameters = array())
        {
                parent::initialize($context, $parameters);            
                $this -> dbLayer = $this -> getContext() -> getDatabaseConnection();
                $this -> dbLayer -> exec("SET NAMES utf8");
        }
        
        public function getById($id)
        {
                $stmt = $this -> dbLayer -> prepare("SELECT * FROM notes WHERE id = :id");
                $stmt -> bindParam("id", $id, PDO::PARAM_INT);
                $stmt -> setFetchMode(PDO::FETCH_OBJ);
                $stmt -> execute();
        
                return $stmt -> fetch();
        }
        
        public function getRecent()
        {
                $stmt = $this -> dbLayer -> prepare("SELECT * FROM notes ORDER BY date DESC LIMIT 10");
                $stmt -> setFetchMode(PDO::FETCH_OBJ);
                $stmt -> execute();
        
                return $stmt -> fetchAll();
        }
        
        public function save(array $data)
        {
                $stmt = $this -> dbLayer -> prepare("INSERT INTO notes VALUES(NULL, :title, :intro, :text, NOW(), :author)");
                $stmt -> execute($data);
        }
}
 
?> 

Tak wygląda nasz model. Myślę że zbytnio nie ma co się rozpisywać, są to podstawowe operacje na baze danych używając PDO.

Akcje

Wygenerowane akcje mają obszerny komentarza. Warto go przeczytać i zapamiętać wskazówki w nim zawarte. Oprócz komentarza (po przeczytaniu możemy go wywalić ;) mamy jedną metodę: getDefaultViewName, zwraca ona domyślny widok który ma być wykonany jeżeli nie wskazano innego.

Najważniejszymi metodami akcji są metody executeRead oraz executeWrite. Są one wykonywane odpowiednio gdy wysłane są dane metodą GET i POST. Można zaimplementować jedną metodę - execute - w której ręcznie sprawdzali byśmy sobie skąd otrzymujemy dane. Nie jest to zalecane rozwiązanie jednak może zaistnieć sytuacja kiedy będziemy musieli z tej możliwości skorzystać. Wszystkie z tych 3 metod muszą zwrócić nazwę widoku który ma być wykonany. W przeciwnym wypadku nie zostanie wykonany żaden widok.

Jeżeli chodzi o naszą małą aplikację, a właściwie nasz jeden mały moduł to interesuje nas jedynie akcja Add. Inne akcje nie będą posiadały żadnej logiki. Będą jedynie zwracać widok, ten natomiast będzie prezentował dane pobrane od modelu.

Akcja Add domyślnie będzie uruchamiać widok Input, który będzie zawierał formularz. Jeżeli jednak zostaną przesłane jakieś dane metodą POST to zostanie wywołana metoda executeWrite.

Oto jak będzie wyglądać nasza akcja:

PHP [Show Plain Code]:

< ?php
 
class Notes_AddAction extends ProjectBaseAction
{
        public function executeWrite(AgaviRequestDataHolder $rd)
        {
                $model = $this -> getContext() -> getModel("Notes", "Notes");
                $model -> save($rd -> getParameter("note"));
                
                return ‘Success’;
        }
        public function getDefaultViewName()
        {
                return ‘Input’;
        }
}
 
?> 

Kod bardzo prosty. Pobranie modelu, następnie wywołanie metody save, podając jako argument tablicę z danymi z formularza ($rd jest obiektem typu AgaviRequestDataHolder, są tam przechowywane dane z requestu)

Widoki

Została nam ostania warstwa aplikacji, warstwa prezentacyjna czyli widok. W tym przypadku pomijamy widoku akcji Add, ponieważ nie potrzebujemy wciągać żadnych danych. Pokażemy jedynie formularz (Input) lub wiadomość o tym że dodano wiadomość (Success). Tak będą natomiast będą wyglądać widoki:

IndexSuccessView

PHP [Show Plain Code]:

< ?php
 
class Notes_IndexSuccessView extends ProjectBaseView
{
        public function executeHtml(AgaviRequestDataHolder $rd)
        {
                parent::setupHtml($rd);
                
                $model = $this -> getContext() -> getModel("Notes", "Notes");
                $this->setAttribute("notes", $model -> getRecent());
        }
}
 
?> 

ShowOneSuccessView

PHP [Show Plain Code]:

< ?php
 
class Notes_ShowOneSuccessView extends ProjectBaseView
{
        public function executeHtml(AgaviRequestDataHolder $rd)
        {
                parent::setupHtml($rd);
 
                $model = $this -> getContext() -> getModel("Notes", "Notes");      
                $this->setAttribute("note", $model -> getById($rd -> getParameter("id")));
        }
}
 
?> 

Są one prawie takie same. Różnią się one jedynie metodą modelu którą wykonujemy. W widoku ShowOne pobieramy z modelu jedną notkę o id którego wartość bierzemy z requestu, tam natomiast trafiło z routera, czyli z adresu url :)

Pozostało nam już tylko napisanie szablonów. Zacznijmy od głównego szablonu, czyli Master.php który musimy utworzyć w app/templates:

app/templates/Master.php

HTML [Show Plain Code]:

< !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" xml:lang="pl">
<head>
 
 <title>Notki</title>
  
 <meta http-equiv="content-type" content="text/html; charset=utf-8" />
 <meta http-equiv="content-language" content="pl" /> 
 
 <base href="<?php echo $ro->getBaseHref(); ?>" />
 
</base></head>
<body>
        < ?php echo $inner; ?>
</body>
</html> 

Ustawiając Master.php jako dekorator, wszystko co zwróci widok dane akcji (html), będzie później dostępne poprzez zmienną $inner. Szkielet strony wtedy trzymamy w Master.php a w miejscu, gdzie treść będzie sie zmieniać wyświetlamy zawartość $inner.

IndexSuccess.php

HTML [Show Plain Code]:

<div>
        <h1>Notki</h1>
        <p><a href="<?php echo $ro -> gen("note_add"); ?>">Dodaj</a></p>
                <ul>
                < ?php foreach($template['notes'] as $note){ ?>
                        <li>
                                <div><a href="<?php $ro -> gen("note_one", array("id" => $note -> id)); ?>">< ?php echo $note -> title; ?></a></div>
                                <p>< ?php echo $note -> intro; ?></p></li></ul></div>
                        
                < ?php } ?> 

ShowOneSuccess.php

HTML [Show Plain Code]:

< ?php $note = $template[‘note’]; ?>
        <h2>< ?php echo $note -> title; ?></h2>
        <div>   
                <p>< ?php echo $note -> intro; ?></p>
                <p>< ?php echo $note -> text; ?></p>
                <p>< ?php echo $note -> author; ?> / < ?php echo $note -> date; ?></p>    
        </div> 

AddInput.php

HTML [Show Plain Code]:

<h2>Dodaj notkę</h2>
        <form action="<?php echo $ro -> gen("note_add"); ?>" method="post">
          <div>
                <label for="title">Tytuł</label>
                <input type="text" name="note[title]" id="title" />
          </div> 
          
          <div>
                <label for="intro">Wstęp</label>
                <textarea name="note[intro]" id="intro"></textarea>
          </div> 
          
          <div>
                <label for="text">Treść</label>
                <textarea name="note[text]" id="text"></textarea>
          </div>
          
          <div>
                <label for="author">Autor</label>
                <input type="text" name="note[author]" id="author" />
          </div>
          
          <div>
                <input type="submit" value="Dodaj" />
          </div>
        </form> 

AddSuccess.php

HTML [Show Plain Code]:

<p>Dodano notkę!</p> 

Nad szablonami myślę że nie ma za bardzo co się rozwodzić. Zwykły HTML, wyświetlający dane otrzymane z widoku.

Zakończenie

W kilku szybkich krokach, nie zagłębiając się w szczegóły, stworzyliśmy bardzo prostą aplikację. Coś w stylu “Jak napisać bloga w 15 minut” używając mojego kochanego frameworka ;) Notka ta miała na celu bardziej zachęcić do zainteresowania się Agavi, niż szczegółowo opisać cały framework. Wszystko w swoim czasie ;)

Polecam przejrzeć jeszcze raz kod aplikacji (teoretycznie powinna ona działać, po uruchomieniu ;) w aby lepiej zrozumieć zasadę działania. Warto również zajrzeć do przykładowej aplikacji znajdującej się w paczce Agavi w folderze samples.

Komentarze

LBO (#) 05.16.2008 22:54
Bardzo ładnie @strzałku, tylko, czy od pewnego czasu nie przyjęło się, że w layerach używa się $inner zamiast slotu?

I kosmetyka: “<base href=”getBaseHref(); ?>” />”

Pozdrawiam, Alan.
LBO (#) 05.16.2008 22:57
Hmmmm, blog uciął znacznik zamykający “base”…
splatch (#) 05.17.2008 10:25
Bardzo się cieszę, że poruszyłeś temat Agavi. Jest to framework który prezentuje nieco inne podejście niż istniejące rozwiązania, w szczególności Zend Framework czy Symfony. Z jednej strony wiele wyniósł z Mojavi, z drugiej developerzy dodali gro możliwości, które sprawiają że praca jest rzeczywiście przyjemnością. Wystarczy wspomnieć konfigurację z użyciem XLink, wsparcie dla SOAP, rozbudowane mapowanie adresów (bije na głowę każde, które znam) i na końcu - najlepsze - Form Population Filter. :)

Artykuł bardzo fajny. Tak trzymaj!

Pozdrawiam,
Łukasz
Strzałek (#) 05.17.2008 12:13
Z tym kolorowanie kodu i w ogóle wklejaniem kodu w notce i komentarzach coś jest nie tak. Jak będę miał chwile powalczę z tym.

LBO: Racja. Nie wiedziałem że tak można, a jest dostępne to już od jakiegoś czasu (ticket #655). Zmieniłem w notce. Nadal jednak można odwoływać się “po staremu” czyli używając slotów.
Whisller (#) 06.14.2008 14:50
Bardzo fajny artykuł. Szkoda że już od bardzo dawna nie miałem czasu na programowanie z użyciem tego frameworka.

Mam nadzieję że to nie ostatni artykuł na temat Agavi :)
LBO (#) 06.26.2008 10:20
Hej strzałku przyjrzałem się jeszcze raz i czy uważasz, że pobieranie danych w widoku to dobry pomysł?
Co zrobisz w przypadku błędu w modelu?
Wiem, że to tylko taka pokazówka, ale dobrze uczyć czytelników dobrych nawyków od samego poczatku.

dodatkowo: php specjalnie do zastosowania takiego jak w widoku udostepnia dodatkową notację bez klamerek.

To samo tyczy sie innych konstrukcji np. “if :”, “endif” - kod jest czytelniejszy.
LBO (#) 06.26.2008 10:22
Cholera zjadło mi kod php.

Pisałem dokładnie o tym: http://php.net.pl/manual/pl/control-structures.alternative-syntax.php

Strzalek.net - Łukasz Strzałkowski developer's blog