documentation/manual/pl/tutorials/quickstart-create-project.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!-- EN-Revision: 21826 -->
   3 <!-- Reviewed: yes -->
   4 <sect1 id="learning.quickstart.create-project">
   5     <title>Utworzenie projektu</title>
   6
   7     <para>
   8         Aby utworzyć nowy projekt należy wcześniej pobrać i rozpakować Zend Framework.
   9     </para>
  10
  11     <sect2 id="learning.quickstart.create-project.install-zf">
  12         <title>Instalacja Zend Framework</title>
  13
  14         <para>
  15             Najprostszym sposobem pobrania Zend Framework razem z całym środowiskiem
  16             <acronym>PHP</acronym> jest zainstalowanie
  17             <ulink url="http://www.zend.com/en/products/server-ce/downloads">Zend Server</ulink>.
  18             Zend Server zawiera instalatory dla Mac OS X, Windows, Fedora Core oraz Ubuntu.
  19             Oprócz tego dostępna jest uniwersalna paczka instalacyjna kompatybilna z większością
  20             dystrybucji Linux.
  21         </para>
  22
  23         <para>
  24             Po zainstalowaniu Zend Server, pliki frameworka są dostępne w katalogu
  25             <filename>/usr/local/zend/share/ZendFramework</filename> dla Mac OS X oraz Linux,
  26             lub <filename>C:\Program Files\Zend\ZendServer\share\ZendFramework</filename> dla
  27             Windows. Zmienna <constant>include_path</constant> będzie automatycznie ustawiona
  28             tak aby obejmowała Zend Framework.
  29         </para>
  30
  31         <para>
  32             Alternatywnie można <ulink url="http://framework.zend.com/download/latest">pobrać
  33             najnowszą wersję Zend Framework</ulink> i rozpakować zawartość do dowolnego katalogu;
  34             należy zapamiętać wybraną lokalizację instalacji.
  35         </para>
  36
  37         <para>
  38             Opcjonalnie w pliku <filename>php.ini</filename> można umieścić w
  39             zmiennej <constant>include_path</constant> ścieżkę do
  40             podkatalogu <filename>library/</filename> znajdującego się w pobranym archiwum.
  41         </para>
  42
  43         <para>
  44             Instalacja zakończona! Zend Framework jest zainstalowany i gotowy do użycia.
  45         </para>
  46     </sect2>
  47
  48     <sect2 id="learning.quickstart.create-project.create-project">
  49         <title>Tworzenie projektu</title>
  50
  51         <note>
  52             <title>Narzędzie wiersza poleceń zf</title>
  53
  54             <para>
  55                 W katalogu instalacji Zend Framework znajduje się podkatalog
  56                 <filename>bin/</filename>.
  57                 Zawiera on skrypty <filename>zf.sh</filename> oraz <filename>zf.bat</filename>
  58                 odpowiednio dla użytkowników Unix oraz Windows. Należy zapamiętać ścieżkę dostępu
  59                 do tych skryptów.
  60             </para>
  61
  62             <para>
  63                 Jeśli w dokumentacji pojawią się odniesienia do komendy <command>zf</command>,
  64                 proszę pamiętać o zastąpieniu ich pełną ścieżką dostępu do odpowiedniego skryptu.
  65                 Dla systemów Unix można skorzystać z polecenia alias:
  66                 <command>alias zf.sh=path/to/ZendFramework/bin/zf.sh</command>.
  67             </para>
  68
  69             <para>
  70                 W przypadku problemów z konfiguracją narzędzia wiersza poleceń proszę zapoznać się
  71                 z <link linkend="zend.tool.framework.clitool.setup-general">jego instrukcją</link>.
  72             </para>
  73         </note>
  74
  75         <para>
  76             Aby utworzyć nowy projekt należy otworzyć terminal (dla Windows - wiersz polecenia
  77             <command>Start -> Run</command> i polecenie <command>cmd</command>). Należy przejść do
  78             katalogu nowego projektu. Następnie, używając ścieżki do odpowiedniego skryptu, należy
  79             wywołać następujące polecenie:
  80         </para>
  81
  82         <programlisting language="shell"><![CDATA[
  83 % zf create project quickstart
  84 ]]></programlisting>
  85
  86         <para>
  87             Wywołanie tego polecenia spowoduje utworzenie podstawowej struktury katalogów, razem
  88             z początkowymi kontrolerami i widokami. Drzewo katalogów powinno wyglądać podobnie do
  89             poniższego:
  90         </para>
  91
  92         <programlisting language="text"><![CDATA[
  93 quickstart
  94 |-- application
  95 |   |-- Bootstrap.php
  96 |   |-- configs
  97 |   |   `-- application.ini
  98 |   |-- controllers
  99 |   |   |-- ErrorController.php
 100 |   |   `-- IndexController.php
 101 |   |-- models
 102 |   `-- views
 103 |       |-- helpers
 104 |       `-- scripts
 105 |           |-- error
 106 |           |   `-- error.phtml
 107 |           `-- index
 108 |               `-- index.phtml
 109 |-- library
 110 |-- public
 111 |   |-- .htaccess
 112 |   `-- index.php
 113 `-- tests
 114     |-- application
 115     |   `-- bootstrap.php
 116     |-- library
 117     |   `-- bootstrap.php
 118     `-- phpunit.xml
 119 ]]></programlisting>
 120
 121         <para>
 122             W tym momencie, jeśli Zend Framework nie jest umieszczony w zmiennej
 123             <constant>include_path</constant>, zaleca się skopiowanie lub umieszczenie
 124             linku symbolicznego do podkatalogu <filename>library/</filename> projektu.
 125             Najistotniejsze jest aby zawartość katalogu <filename>library/Zend/</filename>
 126             instalacji Zend Framework była dostępna w katalogu <filename>library/</filename>
 127             projektu. Na systemach Unix można tego dokonać za pomocą następujących poleceń:
 128         </para>
 129
 130         <programlisting language="shell"><![CDATA[
 131 # Symlink:
 132 % cd library; ln -s path/to/ZendFramework/library/Zend .
 133
 134 # Kopia:
 135 % cd library; cp -r path/to/ZendFramework/library/Zend .
 136 ]]></programlisting>
 137
 138         <para>
 139             W systemach Windows najprostszym rozwiązaniem będzie wykonanie tego z poziomu Explorera.
 140         </para>
 141
 142         <para>
 143             Teraz, kiedy nowy projekt jest utworzony należy zapoznać się z podstawowymi założeniami:
 144             bootstrapem, konfiguracją, kontrolerami oraz widokami.
 145         </para>
 146     </sect2>
 147
 148     <sect2 id="learning.quickstart.create-project.bootstrap">
 149         <title>Bootstrap</title>
 150
 151         <para>
 152             Klasa <classname>Bootstrap</classname> definiuje zasoby i komponenty do inicjalizacji.
 153             Domyślnie uruchamiany jest <link linkend="zend.controller.front">kontroler frontowy</link>
 154             ze standardowym katalogiem w którym szukane są kontrolery akcji (o których mowa później)
 155             ustawionym na <filename>application/controllers/</filename>. Klasa przedstawia się
 156             następująco:
 157         </para>
 158
 159         <programlisting language="php"><![CDATA[
 160 // application/Bootstrap.php
 161
 162 class Bootstrap extends Zend_Application_Bootstrap_Bootstrap
 163 {
 164 }
 165 ]]></programlisting>
 166
 167         <para>
 168             Jak widać, na początek wymagane jest niewiele.
 169         </para>
 170     </sect2>
 171
 172     <sect2 id="learning.quickstart.create-project.configuration">
 173         <title>Konfiguracja</title>
 174
 175         <para>
 176             Sam Zend Framework nie wymaga konfiguracji ale tworzona aplikacja - najczęściej tak.
 177             Standardowo plik konfiguracyjny umieszczony jest w
 178             <filename>application/configs/application.ini</filename>. Zawiera on podstawowe
 179             instrukcje ustawienia środowiska <acronym>PHP</acronym>
 180             (np. włączanie/wyłączanie raportowania błędów),
 181             wskazanie ścieżki i klasy <classname>Bootstrap</classname> oraz ścieżkę do katalogu
 182             kontrolerów akcji. Domyślny plik wygląda następująco:
 183         </para>
 184
 185         <programlisting language="ini"><![CDATA[
 186 ; application/configs/application.ini
 187
 188 [production]
 189 phpSettings.display_startup_errors = 0
 190 phpSettings.display_errors = 0
 191 includePaths.library = APPLICATION_PATH "/../library"
 192 bootstrap.path = APPLICATION_PATH "/Bootstrap.php"
 193 bootstrap.class = "Bootstrap"
 194 appnamespace = "Application"
 195 resources.frontController.controllerDirectory = APPLICATION_PATH "/controllers"
 196 resources.frontController.params.displayExceptions = 0
 197
 198 [staging : production]
 199
 200 [testing : production]
 201 phpSettings.display_startup_errors = 1
 202 phpSettings.display_errors = 1
 203
 204 [development : production]
 205 phpSettings.display_startup_errors = 1
 206 phpSettings.display_errors = 1
 207 ]]></programlisting>
 208
 209         <para>
 210             Należy zwrócić uwagę na kilka cech tego pliku. Po pierwsze, używając konfiguracji
 211             w pliku <acronym>INI</acronym>, można bezpośrednio używać stałych;
 212             <constant>APPLICATION_PATH</constant> to stała PHP (opisana później).
 213             Dodatkowo, zdefiniowane zostały oddzielne sekcje:
 214             production, staging, testing oraz development. Ostatnie trzy dziedziczą ustawienia ze
 215             środowiska produkcyjnego (production). Podany sposób stanowi użyteczny przykład
 216             organizacji konfiguracji, dzięki której odpowiednie ustawienia są dostępne w
 217             odpowiednim momencie cyklu rozwoju oprogramowania.
 218         </para>
 219     </sect2>
 220
 221     <sect2 id="learning.quickstart.create-project.action-controllers">
 222         <title>Kontrolery akcji (action controllers)</title>
 223
 224         <para>
 225             Zawarte w aplikacji <emphasis>kontrolery akcji</emphasis> przechowują ścieżki
 226             działania programu i odwzorowują żądania na odpowiednie modele i widoki.
 227         </para>
 228
 229         <para>
 230             Kontroler akcji powinien posiadać co najmniej jedną metodę o nazwie zakończonej na
 231             "Action". Te metody stają się dostępne dla użytkowników. Domyślnie URLe w Zend
 232             Framework stosują schemat <constant>/kontroler/akcja</constant>, gdzie
 233             "kontroler" jest odwzorowany na nazwę kontrolera akcji
 234             (z pominięciem sufiksu "Controller")
 235             a "akcja" jest odwzorowana na metodę w tym kontrolerze
 236             (z pominięciem sufiksu "Action").
 237         </para>
 238
 239         <para>
 240             W typowym projekcie niezbędny jest kontroler <classname>IndexController</classname>,
 241             który jest początkowym punktem odniesienia i stanowi stronę początkową aplikacji,
 242             oraz <classname>ErrorController</classname> czyli kontroler obsługujący błędy
 243             <acronym>HTTP</acronym> 404 (brak kontrolera i/lub akcji) lub
 244             <acronym>HTTP</acronym> 500 (błąd aplikacji).
 245         </para>
 246
 247         <para>
 248             Domyślnie <classname>IndexController</classname> wygląda następująco:
 249         </para>
 250
 251         <programlisting language="php"><![CDATA[
 252 // application/controllers/IndexController.php
 253
 254 class IndexController extends Zend_Controller_Action
 255 {
 256
 257     public function init()
 258     {
 259         /* Inicjalizacja kontrolera akcji */
 260     }
 261
 262     public function indexAction()
 263     {
 264         // ciało akcji
 265     }
 266 }
 267 ]]></programlisting>
 268
 269         <para>
 270             Domyślny <classname>ErrorController</classname> przedstawia się jak poniżej:
 271         </para>
 272
 273         <programlisting language="php"><![CDATA[
 274 // application/controllers/ErrorController.php
 275
 276 class ErrorController extends Zend_Controller_Action
 277 {
 278
 279     public function errorAction()
 280     {
 281         $errors = $this->_getParam('error_handler');
 282
 283         switch ($errors->type) {
 284             case Zend_Controller_Plugin_ErrorHandler::EXCEPTION_NO_ROUTE:
 285             case Zend_Controller_Plugin_ErrorHandler::EXCEPTION_NO_CONTROLLER:
 286             case Zend_Controller_Plugin_ErrorHandler::EXCEPTION_NO_ACTION:
 287
 288                 // błąd 404 -- brak kontrolera i/lub akcji
 289                 $this->getResponse()->setHttpResponseCode(404);
 290                 $this->view->message = 'Page not found';
 291                 break;
 292             default:
 293                 // błąd aplikacji
 294                 $this->getResponse()->setHttpResponseCode(500);
 295                 $this->view->message = 'Application error';
 296                 break;
 297         }
 298
 299         $this->view->exception = $errors->exception;
 300         $this->view->request   = $errors->request;
 301     }
 302 }
 303 ]]></programlisting>
 304
 305         <para>
 306             Należy zwrócić uwagę, iż <classname>IndexController</classname> nie zawiera żadnego
 307             kodu oraz <classname>ErrorController</classname> odnosi się do właściwości "view". To
 308             prowadzi do następnego tematu.
 309         </para>
 310     </sect2>
 311
 312     <sect2 id="learning.quickstart.create-project.views">
 313         <title>Widoki (views)</title>
 314
 315         <para>
 316             Widoki (view scripts) w Zend Framework są napisane w starym dobrym
 317             <acronym>PHP</acronym>. Domyślnie
 318             znajdują się w <filename>application/views/scripts/</filename>, gdzie są w dalszym
 319             stopniu dzielone wg kontrolerów do których należą. W obecnym przypadku istnieją
 320             dwa kontrolery: <classname>IndexController</classname> oraz
 321             <classname>ErrorController</classname>. Oznacza to, że w katalogu widoków powinny się
 322             znaleźć dwa podkatalogi: <filename>index/</filename> oraz <filename>error/</filename>.
 323             W nich należy umieścić skrypty widoków odpowiednie dla każdej z akcji danego kontrolera.
 324             Domyślnie tworzone są skrypty <filename>index/index.phtml</filename> oraz
 325             <filename>error/error.phtml</filename>.
 326         </para>
 327
 328         <para>
 329             Skrypty widoków mogą zawierać dowolny kod <acronym>HTML</acronym>
 330             i używać <code>&lt;?php</code> jako tagów
 331             otwarcia i <code>?&gt;</code> jako tagów zamknięcia dla poleceń <acronym>PHP</acronym>.
 332         </para>
 333
 334         <para>
 335             Domyślnie skrypt <filename>index/index.phtml</filename> zawiera następującą zawartość:
 336         </para>
 337
 338         <programlisting language="php"><![CDATA[
 339 <!-- application/views/scripts/index/index.phtml -->
 340 <style>
 341
 342     a:link,
 343     a:visited
 344     {
 345         color: #0398CA;
 346     }
 347
 348     span#zf-name
 349     {
 350         color: #91BE3F;
 351     }
 352
 353     div#welcome
 354     {
 355         color: #FFFFFF;
 356         background-image: url(http://framework.zend.com/images/bkg_header.jpg);
 357         width:  600px;
 358         height: 400px;
 359         border: 2px solid #444444;
 360         overflow: hidden;
 361         text-align: center;
 362     }
 363
 364     div#more-information
 365     {
 366         background-image: url(http://framework.zend.com/images/bkg_body-bottom.gif);
 367         height: 100%;
 368     }
 369
 370 </style>
 371 <div id="welcome">
 372     <h1>Welcome to the <span id="zf-name">Zend Framework!</span><h1 />
 373     <h3>This is your project's main page<h3 />
 374     <div id="more-information">
 375         <p>
 376             <img src="http://framework.zend.com/images/PoweredBy_ZF_4LightBG.png" />
 377         </p>
 378
 379         <p>
 380             Helpful Links: <br />
 381             <a href="http://framework.zend.com/">Zend Framework Website</a> |
 382             <a href="http://framework.zend.com/manual/en/">Zend Framework
 383                 Manual</a>
 384         </p>
 385     </div>
 386 </div>
 387 ]]></programlisting>
 388
 389         <para>
 390             Skrypt <filename>error/error.phtml</filename> jest nieco bardziej interesujący - używa
 391             instrukcji warunkowych <acronym>PHP</acronym>:
 392         </para>
 393
 394         <programlisting language="php"><![CDATA[
 395 <!-- application/views/scripts/error/error.phtml -->
 396 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN";
 397     "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd>
 398 <html xmlns="http://www.w3.org/1999/xhtml">
 399 <head>
 400   <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
 401   <title>Zend Framework Default Application</title>
 402 </head>
 403 <body>
 404   <h1>An error occurred</h1>
 405   <h2><?php echo $this->message ?></h2>
 406
 407   <?php if ('development' == $this->env): ?>
 408
 409   <h3>Exception information:</h3>
 410   <p>
 411       <b>Message:</b> <?php echo $this->exception->getMessage() ?>
 412   </p>
 413
 414   <h3>Stack trace:</h3>
 415   <pre><?php echo $this->exception->getTraceAsString() ?>
 416   </pre>
 417
 418   <h3>Request Parameters:</h3>
 419   <pre><?php echo var_export($this->request->getParams(), 1) ?>
 420   </pre>
 421   <?php endif ?>
 422
 423 </body>
 424 </html>
 425 ]]></programlisting>
 426     </sect2>
 427
 428     <sect2 id="learning.quickstart.create-project.vhost">
 429         <title>Utworzenie wirtualnego hosta</title>
 430
 431         <para>
 432             Na potrzeby tego wprowadzenia, założono użycie <ulink url="http://httpd.apache.org/">
 433             web serwera Apache</ulink>. Zend Framework działa równie dobrze z innymi
 434             serwerami - włączając Microsoft Internet Information Services, lighttpd, nginx i
 435             wiele innych. Większość programistów jednak jest najbardziej zaznajomiona z Apache, który
 436             ułatwia zrozumienie struktury katalogów Zend Framework i posiada szerokie możliwości
 437             przepisywania linków (mod_rewrite).
 438         </para>
 439
 440         <para>
 441             Aby utworzyć wirtualnego hosta należy odnaleźć plik <filename>httpd.conf</filename> oraz
 442             ewentualne pozostałe pliki konfiguracyjne serwera. Popularne katalogi:
 443         </para>
 444
 445         <itemizedlist>
 446             <listitem>
 447                 <para>
 448                     <filename>/etc/httpd/httpd.conf</filename> (Fedora, RHEL i inne)
 449                 </para>
 450             </listitem>
 451
 452             <listitem>
 453                 <para>
 454                     <filename>/etc/apache2/httpd.conf</filename> (Debian, Ubuntu i inne)
 455                 </para>
 456             </listitem>
 457
 458             <listitem>
 459                 <para>
 460                     <filename>/usr/local/zend/etc/httpd.conf</filename> (Zend Server
 461                     na maszynach *nix)
 462                 </para>
 463             </listitem>
 464
 465             <listitem>
 466                 <para>
 467                     <filename>C:\Program Files\Zend\Apache2\conf</filename> (Zend Server
 468                     na maszynach Windows)
 469                 </para>
 470             </listitem>
 471         </itemizedlist>
 472
 473         <para>
 474             W pliku <filename>httpd.conf</filename> (lub <filename>httpd-vhosts.conf</filename>
 475             dla niektórych systemów) należy dokonać dwóch zmian. Po pierwsze - upewnić się, że
 476             jest zainicjowana zmienna <varname>NameVirtualHost</varname>; Typowe ustawienie to
 477             "*:80". Po drugie - zdefiniować wirtualnego hosta:
 478         </para>
 479
 480         <programlisting language="apache"><![CDATA[
 481 <VirtualHost *:80>
 482     ServerName quickstart.local
 483     DocumentRoot /sciezka/do/quickstart/public
 484
 485     SetEnv APPLICATION_ENV "development"
 486
 487     <Directory /sciezka/do/quickstart/public>
 488         DirectoryIndex index.php
 489         AllowOverride All
 490         Order allow,deny
 491         Allow from all
 492     </Directory>
 493 </VirtualHost>
 494 ]]></programlisting>
 495
 496         <para>
 497             Należy zwrócić uwagę na kilka szczegółów. Po pierwsze, <varname>DocumentRoot</varname>
 498             wskazuje na podkatalog projektu o nazwie <filename>public</filename>. To oznacza, że
 499             jedynie pliki znajdujące się w tym podkatalogu mogą być zwracane przez serwer
 500             bezpośrednio. Po drugie, instrukcje <varname>AllowOverride</varname>,
 501             <varname>Order</varname> oraz <varname>Allow</varname> umożliwiają stosowanie plików
 502             <filename>htacess</filename> w projekcie. W środowisku programistycznym (development)
 503             jest to uznawane za dobrą praktykę ponieważ eliminuje potrzebę resetowania
 504             serwera po każdej zmianie instrukcji konfiguracyjnych. Jednak w środowisku produkcyjnym
 505             (production), zalecane jest przeniesienie zawartości pliku <filename>htaccess</filename>
 506             do głównego pliku konfiguracyjnego serwera oraz wyłączenie obsługi
 507             <filename>htaccess</filename>. Po trzecie, instrukcja
 508             <varname>SetEnv</varname> pozwala zainicjować zmienną środowiskową oraz
 509             przekazać ją do PHP i <filename>index.php</filename>.
 510             Dzięki temu stanie się ona podstawą stałej
 511             <constant>APPLICATION_ENV</constant> aplikacji Zend Framework.
 512             W środowisku produkcyjnym można ją ustawić na "production" lub zrezygnować
 513             z tej instrukcji ("production" jest domyślną wartością stałej
 514             <constant>APPLICATION_ENV</constant>).
 515         </para>
 516
 517         <para>
 518             Na koniec należy dodać wpis w pliku <filename>hosts</filename> odnoszący się do wartości
 519             <varname>ServerName</varname>. Na systemach *nix jest to zazwyczaj
 520             <filename>/etc/hosts</filename>. Na maszynach Windows typową lokalizacją jest
 521             <filename>C:\WINDOWS\system32\drivers\etc</filename>. Wpis powinien być podobny do:
 522         </para>
 523
 524         <programlisting language="text"><![CDATA[
 525 127.0.0.1 quickstart.local
 526 ]]></programlisting>
 527
 528         <para>
 529             Po uruchomieniu webserwera (lub restarcie) projekt powinien być gotowy do użytku.
 530         </para>
 531     </sect2>
 532
 533     <sect2 id="learning.quickstart.create-project.checkpoint">
 534         <title>Punkt kontrolny</title>
 535
 536         <para>
 537             W tym momencie aplikacja Zend Framework jest gotowa do uruchomienia. Po wpisaniu
 538             w przeglądarce nazwy serwera (ustalonej w poprzednim punkcie) powinna się pojawić
 539             strona powitalna.
 540         </para>
 541     </sect2>
 542 </sect1>