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

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!-- EN-Revision: 21740 -->
   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 INI, można bezpośrednio używać stałych; <constant>APPLICATION_PATH</constant>
 212             to stała PHP (opisana później). Dodatkowo, zdefiniowane zostały oddzielne sekcje:
 213             production, staging, testing oraz development. Ostatnie trzy dziedziczą ustawienia ze
 214             środowiska produkcyjnego (production). Podany sposób stanowi użyteczny przykład
 215             organizacji konfiguracji, dzięki której odpowiednie ustawienia są dostępne w
 216             odpowiednim momencie cyklu rozwoju oprogramowania.
 217         </para>
 218     </sect2>
 219
 220     <sect2 id="learning.quickstart.create-project.action-controllers">
 221         <title>Kontrolery akcji (action controllers)</title>
 222
 223         <para>
 224             Zawarte w aplikacji <emphasis>kontrolery akcji</emphasis> przechowują ścieżki
 225             działania programu i odwzorowują żądania na odpowiednie modele i widoki.
 226         </para>
 227
 228         <para>
 229             Kontroler akcji powinien posiadać co najmniej jedną metodę o nazwie zakończonej na
 230             "Action". Te metody stają się dostępne dla użytkowników. Domyślnie URLe w Zend
 231             Framework stosują schemat <constant>/kontroler/akcja</constant>, gdzie
 232             "kontroler" jest odwzorowany na nazwę kontrolera akcji
 233             (z pominięciem sufiksu "Controller")
 234             a "akcja" jest odwzorowana na metodę w tym kontrolerze
 235             (z pominięciem sufiksu "Action").
 236         </para>
 237
 238         <para>
 239             W typowym projekcie niezbędny jest kontroler <classname>IndexController</classname>,
 240             który jest początkowym punktem odniesienia i stanowi stronę początkową aplikacji,
 241             oraz <classname>ErrorController</classname> czyli kontroler obsługujący błędy HTTP 404
 242             (brak kontrolera i/lub akcji) lub HTTP 500 (błąd aplikacji).
 243         </para>
 244
 245         <para>
 246             Domyślnie <classname>IndexController</classname> wygląda następująco:
 247         </para>
 248
 249         <programlisting language="php"><![CDATA[
 250 // application/controllers/IndexController.php
 251
 252 class IndexController extends Zend_Controller_Action
 253 {
 254
 255     public function init()
 256     {
 257         /* Inicjalizacja kontrolera akcji */
 258     }
 259
 260     public function indexAction()
 261     {
 262         // ciało akcji
 263     }
 264 }
 265 ]]></programlisting>
 266
 267         <para>
 268             Domyślny <classname>ErrorController</classname> przedstawia się jak poniżej:
 269         </para>
 270
 271         <programlisting language="php"><![CDATA[
 272 // application/controllers/ErrorController.php
 273
 274 class ErrorController extends Zend_Controller_Action
 275 {
 276
 277     public function errorAction()
 278     {
 279         $errors = $this->_getParam('error_handler');
 280
 281         switch ($errors->type) {
 282             case Zend_Controller_Plugin_ErrorHandler::EXCEPTION_NO_ROUTE:
 283             case Zend_Controller_Plugin_ErrorHandler::EXCEPTION_NO_CONTROLLER:
 284             case Zend_Controller_Plugin_ErrorHandler::EXCEPTION_NO_ACTION:
 285
 286                 // błąd 404 -- brak kontrolera i/lub akcji
 287                 $this->getResponse()->setHttpResponseCode(404);
 288                 $this->view->message = 'Page not found';
 289                 break;
 290             default:
 291                 // błąd aplikacji
 292                 $this->getResponse()->setHttpResponseCode(500);
 293                 $this->view->message = 'Application error';
 294                 break;
 295         }
 296
 297         $this->view->exception = $errors->exception;
 298         $this->view->request   = $errors->request;
 299     }
 300 }
 301 ]]></programlisting>
 302
 303         <para>
 304             Należy zwrócić uwagę, iż <classname>IndexController</classname> nie zawiera żadnego
 305             kodu oraz <classname>ErrorController</classname> odnosi się do właściwości "view". To
 306             prowadzi do następnego tematu.
 307         </para>
 308     </sect2>
 309
 310     <sect2 id="learning.quickstart.create-project.views">
 311         <title>Widoki (views)</title>
 312
 313         <para>
 314             Widoki (view scripts) w Zend Framework są napisane w starym dobrym
 315             <acronym>PHP</acronym>. Domyślnie
 316             znajdują się w <filename>application/views/scripts/</filename>, gdzie są w dalszym
 317             stopniu dzielone wg kontrolerów do których należą. W obecnym przypadku istnieją
 318             dwa kontrolery: <classname>IndexController</classname> oraz
 319             <classname>ErrorController</classname>. Oznacza to, że w katalogu widoków powinny się
 320             znaleźć dwa podkatalogi: <filename>index/</filename> oraz <filename>error/</filename>.
 321             W nich należy umieścić skrypty widoków odpowiednie dla każdej z akcji danego kontrolera.
 322             Domyślnie tworzone są skrypty <filename>index/index.phtml</filename> oraz
 323             <filename>error/error.phtml</filename>.
 324         </para>
 325
 326         <para>
 327             Skrypty widoków mogą zawierać dowolny kod <acronym>HTML</acronym>
 328             i używać <code>&lt;?php</code> jako tagów
 329             otwarcia i <code>?&gt;</code> jako tagów zamknięcia dla poleceń <acronym>PHP</acronym>.
 330         </para>
 331
 332         <para>
 333             Domyślnie skrypt <filename>index/index.phtml</filename> zawiera następującą zawartość:
 334         </para>
 335
 336         <programlisting language="php"><![CDATA[
 337 <!-- application/views/scripts/index/index.phtml -->
 338 <style>
 339
 340     a:link,
 341     a:visited
 342     {
 343         color: #0398CA;
 344     }
 345
 346     span#zf-name
 347     {
 348         color: #91BE3F;
 349     }
 350
 351     div#welcome
 352     {
 353         color: #FFFFFF;
 354         background-image: url(http://framework.zend.com/images/bkg_header.jpg);
 355         width:  600px;
 356         height: 400px;
 357         border: 2px solid #444444;
 358         overflow: hidden;
 359         text-align: center;
 360     }
 361
 362     div#more-information
 363     {
 364         background-image: url(http://framework.zend.com/images/bkg_body-bottom.gif);
 365         height: 100%;
 366     }
 367
 368 </style>
 369 <div id="welcome">
 370     <h1>Welcome to the <span id="zf-name">Zend Framework!</span><h1 />
 371     <h3>This is your project's main page<h3 />
 372     <div id="more-information">
 373         <p>
 374             <img src="http://framework.zend.com/images/PoweredBy_ZF_4LightBG.png" />
 375         </p>
 376
 377         <p>
 378             Helpful Links: <br />
 379             <a href="http://framework.zend.com/">Zend Framework Website</a> |
 380             <a href="http://framework.zend.com/manual/en/">Zend Framework
 381                 Manual</a>
 382         </p>
 383     </div>
 384 </div>
 385 ]]></programlisting>
 386
 387         <para>
 388             Skrypt <filename>error/error.phtml</filename> jest nieco bardziej interesujący - używa
 389             instrukcji warunkowych <acronym>PHP</acronym>:
 390         </para>
 391
 392         <programlisting language="php"><![CDATA[
 393 <!-- application/views/scripts/error/error.phtml -->
 394 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN";
 395     "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd>
 396 <html xmlns="http://www.w3.org/1999/xhtml">
 397 <head>
 398   <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
 399   <title>Zend Framework Default Application</title>
 400 </head>
 401 <body>
 402   <h1>An error occurred</h1>
 403   <h2><?php echo $this->message ?></h2>
 404
 405   <?php if ('development' == $this->env): ?>
 406
 407   <h3>Exception information:</h3>
 408   <p>
 409       <b>Message:</b> <?php echo $this->exception->getMessage() ?>
 410   </p>
 411
 412   <h3>Stack trace:</h3>
 413   <pre><?php echo $this->exception->getTraceAsString() ?>
 414   </pre>
 415
 416   <h3>Request Parameters:</h3>
 417   <pre><?php echo var_export($this->request->getParams(), 1) ?>
 418   </pre>
 419   <?php endif ?>
 420
 421 </body>
 422 </html>
 423 ]]></programlisting>
 424     </sect2>
 425
 426     <sect2 id="learning.quickstart.create-project.vhost">
 427         <title>Utworzenie wirtualnego hosta</title>
 428
 429         <para>
 430             Na potrzeby tego wprowadzenia, założono użycie <ulink url="http://httpd.apache.org/">
 431             web serwera Apache</ulink>. Zend Framework działa równie dobrze z innymi
 432             serwerami - włączając Microsoft Internet Information Services, lighttpd, nginx i
 433             wiele innych. Większość programistów jednak jest najbardziej zaznajomiona z Apache, który
 434             ułatwia zrozumienie struktury katalogów Zend Framework i posiada szerokie możliwości
 435             przepisywania linków (mod_rewrite).
 436         </para>
 437
 438         <para>
 439             Aby utworzyć wirtualnego hosta należy odnaleźć plik <filename>httpd.conf</filename> oraz
 440             ewentualne pozostałe pliki konfiguracyjne serwera. Popularne katalogi:
 441         </para>
 442
 443         <itemizedlist>
 444             <listitem>
 445                 <para>
 446                     <filename>/etc/httpd/httpd.conf</filename> (Fedora, RHEL i inne)
 447                 </para>
 448             </listitem>
 449
 450             <listitem>
 451                 <para>
 452                     <filename>/etc/apache2/httpd.conf</filename> (Debian, Ubuntu i inne)
 453                 </para>
 454             </listitem>
 455
 456             <listitem>
 457                 <para>
 458                     <filename>/usr/local/zend/etc/httpd.conf</filename> (Zend Server
 459                     na maszynach *nix)
 460                 </para>
 461             </listitem>
 462
 463             <listitem>
 464                 <para>
 465                     <filename>C:\Program Files\Zend\Apache2\conf</filename> (Zend Server
 466                     na maszynach Windows)
 467                 </para>
 468             </listitem>
 469         </itemizedlist>
 470
 471         <para>
 472             W pliku <filename>httpd.conf</filename> (lub <filename>httpd-vhosts.conf</filename>
 473             dla niektórych systemów) należy dokonać dwóch zmian. Po pierwsze - upewnić się, że
 474             jest zainicjowana zmienna <varname>NameVirtualHost</varname>; Typowe ustawienie to
 475             "*:80". Po drugie - zdefiniować wirtualnego hosta:
 476         </para>
 477
 478         <programlisting language="apache"><![CDATA[
 479 <VirtualHost *:80>
 480     ServerName quickstart.local
 481     DocumentRoot /sciezka/do/quickstart/public
 482
 483     SetEnv APPLICATION_ENV "development"
 484
 485     <Directory /sciezka/do/quickstart/public>
 486         DirectoryIndex index.php
 487         AllowOverride All
 488         Order allow,deny
 489         Allow from all
 490     </Directory>
 491 </VirtualHost>
 492 ]]></programlisting>
 493
 494         <para>
 495             Należy zwrócić uwagę na kilka szczegółów. Po pierwsze, <varname>DocumentRoot</varname>
 496             wskazuje na podkatalog projektu o nazwie <filename>public</filename>. To oznacza, że
 497             jedynie pliki znajdujące się w tym podkatalogu mogą być zwracane przez serwer
 498             bezpośrednio. Po drugie, instrukcje <varname>AllowOverride</varname>,
 499             <varname>Order</varname> oraz <varname>Allow</varname> umożliwiają stosowanie plików
 500             <filename>htacess</filename> w projekcie. W środowisku programistycznym (development)
 501             jest to uznawane za dobrą praktykę ponieważ eliminuje potrzebę resetowania
 502             serwera po każdej zmianie instrukcji konfiguracyjnych. Jednak w środowisku produkcyjnym
 503             (production), zalecane jest przeniesienie zawartości pliku <filename>htaccess</filename>
 504             do głównego pliku konfiguracyjnego serwera oraz wyłączenie obsługi
 505             <filename>htaccess</filename>. Po trzecie, instrukcja
 506             <varname>SetEnv</varname> pozwala zainicjować zmienną środowiskową oraz
 507             przekazać ją do PHP i <filename>index.php</filename>.
 508             Dzięki temu stanie się ona podstawą stałej
 509             <constant>APPLICATION_ENV</constant> aplikacji Zend Framework.
 510             W środowisku produkcyjnym można ją ustawić na "production" lub zrezygnować
 511             z tej instrukcji ("production" jest domyślną wartością stałej
 512             <constant>APPLICATION_ENV</constant>).
 513         </para>
 514
 515         <para>
 516             Na koniec należy dodać wpis w pliku <filename>hosts</filename> odnoszący się do wartości
 517             <varname>ServerName</varname>. Na systemach *nix jest to zazwyczaj
 518             <filename>/etc/hosts</filename>. Na maszynach Windows typową lokalizacją jest
 519             <filename>C:\WINDOWS\system32\drivers\etc</filename>. Wpis powinien być podobny do:
 520         </para>
 521
 522         <programlisting language="text"><![CDATA[
 523 127.0.0.1 quickstart.local
 524 ]]></programlisting>
 525
 526         <para>
 527             Po uruchomieniu webserwera (lub restarcie) projekt powinien być gotowy do użytku.
 528         </para>
 529     </sect2>
 530
 531     <sect2 id="learning.quickstart.create-project.checkpoint">
 532         <title>Punkt kontrolny</title>
 533
 534         <para>
 535             W tym momencie aplikacja Zend Framework jest gotowa do uruchomienia. Po wpisaniu
 536             w przeglądarce nazwy serwera (ustalonej w poprzednim punkcie) powinna się pojawić
 537             strona powitalna.
 538         </para>
 539     </sect2>
 540 </sect1>