Dokumentacja projektu Coyote

Copyright ? 2003-2006 Adam Boduch, Qyon

1 Dokumentacja projektu <i>Coyote</i>
2 Informacje dla deweloperów
     2.1 Autorzy
          2.1.1 Kontakt
     2.2 Zasady pracy grupowej
          2.2.2 Nowe funkcje, błędy
          2.2.3 Wersjonowanie aplikacji
               2.2.3.1 Wersje rozwojowe i stabilne
               2.2.3.2 Przechodzenie z wersji rozwojowej do stabilnej - wersje pre i rc
          2.2.4 TODO
          2.2.5 CVS
               2.2.5.3 Obsługa CVS
               2.2.5.4 Tagi CVS
               2.2.5.5 Gałęzie CVS
                    2.2.5.5.1 Obsługa gałęzi w WinCVS
                    2.2.5.5.2 Scalanie
          2.2.6 Pisanie dokumentacji
          2.2.7 Jak możesz pomóc?
          2.2.8 Styl kodowania
               2.2.8.6 Kodowanie PHP
                    2.2.8.6.3 Nazewnictwo
                    2.2.8.6.4 Wcięcia
                    2.2.8.6.5 Struktury kontrolne
                    2.2.8.6.6 Deklaracja funkcji
                    2.2.8.6.7 Komentarze
                    2.2.8.6.8 ChangeLog
                    2.2.8.6.9 Stałe
                    2.2.8.6.10 Zmienne
               2.2.8.7 Zapisywanie instrukcji SQL
          2.2.9 BugTracker
     2.3 Architektura systemu
     2.4 Pliki systemu
          2.4.10 root/extension.inc
          2.4.11 root/config.php
          2.4.12 root/common.php
          2.4.13 root/include/cache.php
3 Poradnik użytkownika
     3.5 Licencja
     3.6 Instalacja
          3.6.14 Wymagania
          3.6.15 Instalacja automatyczna
          3.6.16 Możliwe problemy
               3.6.16.8 Błąd Could not find language directory
               3.6.16.9 Błąd Nie można usunąc pliku config.php
               3.6.16.10 Sprawdzenie nie zostało zakończone poprawnie. Przejrzyj listę nieprawidłowości
               3.6.16.11 File does not exists
               3.6.16.12 System nie mógł zapisać danych konfiguracyjnych do pliku config.php
               3.6.16.13 Błędne zapytanie SQL lub inny bład PHP
          3.6.17 Konfiguracja
               3.6.17.14 Cron
                    3.6.17.14.11 Wymagania
                    3.6.17.14.12 Konfiguracja crona
          3.6.18 Uaktualnianie do wyższych wersji
          3.6.19 Problemy przy użytkowaniu
               3.6.19.15 Logowanie nie działa

Pomysł na stworzenie projektu przypadł na okres zimy roku 2003. Założeniem projektu było stworzenie oprogramowania (systemu) obsługującego serwis 4programmers.net. Można więc powiedzieć, że Coyote to system vortalowy. Obecna wersja ({{VERSION}}) jest wersją testową. Założeniem projektu jest stworzenie elastycznego programu do obsługi większych stron WWW. Sterownie stroną powinno odbywać się poprzez panel administracyjny, chociaż grupą docelową do której skierowany jest program dotyczy stron o programowaniu, webmasteringu - czyli prawdopodobnie dla ludzi, którzy "siedzą" w tym temacie.

Informacje dla deweloperów

Część pierwsza niniejszego poradnika przeznaczona jest przede wszystkim dla deweloperów projektu oraz dla ludzi ciekawych budowy całego systemu. Zamierzamy opisać tutaj informacje związane ze stylem kodowania obsługą CVS, czy systemem pracy nad projektem.

Autorzy

Osoby, które miały dotychczas wkład w projekt:

• Adam Boduch
• Marooned
• LF
• Detox
• LKS
• Piechnat
• roSzi
• Vogel
• Dryobates
• Embraced
• Qyon
• nav

Chcesz pomóc w budowie systemu? Czytaj dalej.

Kontakt

W sprawach technicznych związanych z funkcjonowaniem systemu (propozycje, uwagi) prosimy pisać na forum dyskusyjnym serwisu 4programmers.net. Będziemy wdzięczni za wszelkie uwagi dotyczące działania projektu Coyote.

System Coyote posiada już BugListę, do której można zgłaszać wszelkie błędy związane z działaniem projektu. Adres BugListy to: http://4programmers.net/coyote/bug.php

Jeżeli wykryłeś poważny bład w zabezpieczeniach systemu prosimy o bezpośredni kontakt e-mailowy do administratorów serwisu 4programmers.net, pod adresem support@4programmers.net. Podana skrzynka e-mail jest aktualnie obsługiwana przez administratorów: Marooned oraz Adam Boduch.

Zasady pracy grupowej

W niniejszej sekcji postaram się wyjaśnić zasady pracy grupowej jakie obowiązują w projekcie Coyote. Opiszemy tutaj zasady tworzenia dokumentacji, organizację pracy, system kontroli wersji oraz wersjonowanie plików.

Nowe funkcje, błędy

Dyskusja na temat nowych funkcji, błędów odbywa się na 4programmers.net/Forum, w dziale Coyote. Jeżeli ktoś napisał temat, w którym zgłasza błąd wskazane jest aby zająć się nim jak najszybciej (zależy to także od priorytetu tego błędu). Jeżeli deweloper czytający ów post znajdzie czas na poprawę błędu, lokalizuje go, poprawia, a następnie poprawiony plik wysyła na serwer CVS. Informuje także w poście, iż błąd został poprawiony oraz dopisuje się do pliku ChangeLog.

W przypadku nowych funkcji w systemie, sprawę należy przedyskutować. Jeżeli na forum pojawia się pomysł dodania nowej funkcji, zazwyczaj pojawia się dyskusja odnośnie pomysłu. Jeżeli nie ma większych przeciwskazań ze strony deweloperów, musi stać się rzecz najważniejsza: musi się znaleźć człowiek, który zeche wcielić pomysł w życie.

Wersjonowanie aplikacji

W przypadku CVS'a numerowanie wersji dla konkretnych plików odbywa się automatycznie. Jednak w przypadku pakietów (kolejnych paczek z kodem :)), pozwolę sobie przytoczyć słowa Vogela: Osobiście rozpoznaję 2 rodzaje numerowania wersji programu czy pliku źródłowego. Pierwszy z nich dotyczy programów komercyjnych takich firm jak Microsoft czy Borland. Wersje typu 1.x czy 2.x są możliwie często wprowadzane, wraz z każdą zmianą kilku opcji projektu. Drugi sposób znany ze środowiska Open-Source jest o wiele bardziej skromny. Najpierw w założeniach projektu jest przedstawiana docelowa funkcjonalność, w miarę rozwoju dopisywane są do niej kolejne punkty. Programiści pracują w celu osiągnięcia wyznaczonego celu, a magiczny numerek 1.0.0 otrzymuje dopiero gotowy do użycia program. W przypadku Mozilli trwało to pięć lat, zanim autorzy uznali, że program godzien jest określenia 'stabilny'.

Wersje rozwojowe i stabilne

Wersje rozwojowe, jak sama nazwa wskazuje służą rozwojowi projektu. Dostają one numerki 0.x (1.x, 2.x) gdzie x to liczba nieparzysta. Przykłady:

0.1
0.1.1
0.1.14

Trzeci numer jest numerem wprowadzonej zmiany. Wersje stabilne powstają z wersji rozwojowych po usunięciu możliwie największej liczby błędów. Numerowane są parzyście:

0.2
0.2.1

Przechodzenie z wersji rozwojowej do stabilnej - wersje pre i rc

Dla danej wersji ustalane jest deadline rozwoju, po którym następuje zamrożenie rozszerzania funkcjonalności. Powstaje wersja niestabilna (nieparzysta) pre, w której minimalizujemy dodawanie nowych, znaczących funkcji, a skupiamy się na poprawianiu starych błędów. Po wydaniu jednej lub kilku wersji pre wydaje się wersje rc (release candidate) w której jest już możliwie najmniej błędów. Z wersji rc tworzymy naszą wersję stabilną.

0.1 - początek tworzenia danego pliku
0.1.12 - plik po poprawkach
0.2-pre - zamrożony plik 0.1.12
0.2-rc - plik po usunięciu błędów
0.2 - ostateczna wersja stabilna 0.2 powstała z 0.1

Jeżeli chodzi o projekt Coyote to obecna jego wersja to {{VERSION}}. Pomimo tego, iż projekt wystartował w lutym 2003 r. czyli ma już prawie trzy lata, wciąż nie została wydana wersja stabilna 1.0. Jest to związane z wolnym rozwojem projektu. Obecnie (styczeń 2006) trwają prace nad wersją 0-9-3rc1.

TODO

Jeżeli propozycja nowej funkcji została przyjęta, aby o niej nie zapomnieć, krótką notkę umieszcza się w pliku o nazwie TODO. Przed umieszczeniem stosownej notki w tym pliku, należy także zastanowić się w jakiej wersji systemu dana funkcja powinna się znaleźć.

CVS

Ważnym czynnikiem pracy grupowej jest odpowiedni system odpowiadający za przechowywanie plików źródłowych projektu. Owszem, możnaby przechowywać pliki na zwykłym serwerze FTP lub HTTP, ale znacznie utrudniłoby to pracę. Trudno byłoby nam się domyśleć, kto ostatnio pracował nad plikiem, co w nim zmienił. W przypadku projektów grupowych (tak jak Coyote) szybko doszłoby do bałaganu.

Dlatego na serwerze http://cvs.4programmers.net zainstalowany jest system kontroli wersji o nazwie CVS. Nie będziemy tutaj opisywać zasad działania samego programu CVS; tego możesz dowiedzieć się z licznych manuali, podręczników i kursów.

Strona domowa CVS to www.cvshome.org

Powiemy pokrótce i w dużym uproszczeniu. CVS jest systemem kontroli wersji. Dzięki niemu każdy deweloper biorący udział w projekcie może wysłać na serwer plik, który przed chwilą poprawił. CVS notuje datę wysłania oraz nazwę użytkownika. Później, inni programiści mogą ściągnąć poprawiony plik z serwera - wiedzą dzięki temu kto i kiedy oraz co zmienił w danym pliku. Znacznie ułatwia to prace: poszczególne wersje danego pliku są stale przechowywane na serwerze, w prosty sposób można sprawdzić jakie zmiany zostały dokonywane w poszczególnych wersjach.
Notatka

CVS via WWW projektu Coyote dostępny jest pod adresem http://cvs.4programmers.net

Obsługa CVS

Standardowo CVS jest programem uruchamianym z linii poleceń w konsoli. My polecamy edytory, nakładki graficzne dzięki czemu obsługa CVS jest jeszcze prostsza. Jednym z takich aplikacji pod system Windows jest WinCVS.

Zakładamy, że umiesz posługiwać się CVS w stopniu conajmniej podstawowym. Aby korzystać z CVS należy się najpierw zalogować. Zalogować można się w trybie anonimowym, lecz wówczas Twoje uprawnienia ograniczają się jedynie do pobierania źródeł na dysk. NIE możesz wysyłać na serwer poprawek. Polecenie, dzięki któremu można zalogować się na serwer wygląda tak:

cvs -d:pserver:anoncvs@cvs.4programmers.net:/usr/cvs login
Tymczasowo, repozytorium cvs zmieniło lokację. Tzn. trzeba logowa się poleceniem
cvs -d:pserver:anoncvs@cvs.4programmers.net:/var/cvs login

Jeżeli jesteś osobą, która posiada konto na naszym serwerze CVS, w miejsce anoncvs należy wpisać swój login. W naszym repozytorium CVS znajdują się dwa katalogi: roadrunner oraz coyote. Jeżeli chcesz pobrać na swój dysk oba foldery, musisz wykonać następujące polecenie:

cvs checkout .

W tym momencie kody źródłowe zostaną ściągnięte na Twój dysk. Jeżeli interesuje Cię jedynie projekt Coyote, to polecenie ściągające kody jedynie tego projektu, wygląda tak:

cvs checkout coyote

W tym momencie na Twój dysk zostaną pobrane aktualne, najnowsze wersje plików. Oczywiście jeżeli mówimy o wersjach najnowszych, to naturalną rzeczą będzie, gdy będą one posiadały błędy. Aby tego uniknąć, możesz ściągnąć ostatnie wersje źródeł, które zostały w jakimś stopniu sprawdzone i nie powinny posiadać błędów. O tym możesz przeczytać w sekcji Tagi CVS.

WAŻNE
Polecenie checkout wykonujemy tylko raz, gdy chcemy pobrać całe repozytorium na dysk. Jeżeli chcemy sprawdzić, czy na serwerze znajdują się jakieś poprawki wykonujemy polecenie cvs update, które uaktualni pliki zmienione przez innych programistów.

Tagi CVS

Wyobraź sobie, że do pliku o nazwie functions.php dodałeś funkcję validate_url() i tym samym w module zawarłeś wszystkie funkcje, które chciałeś zawrzeć. Możesz teraz jakoś specjalnie odznaczyc ten plik nadając im tzw. tag. Inna sytuacja: uznaliśmy (jako zespół programistów), że obecne kody źródłowe na CVS są dość stabilne, aby wydać wersje 1.1 projektu Coyote. Teraz na każdy plik w repozytorium CVS można nałożyć tag - przykładowo - Coyote-1-1. Ok, mamy wersje 1.1. możemy przejść do dodawania nowych funkcji w projekcie. Jeżeli jednak użytkownik będzie chciał ściągnąć wersje stabilną 1.1 może posłużyć się tagiem wydając takie polecenie:

cvs checkout -r Coyote-1-1 coyote

Takie polecenie ściągnie na dysk pliki jedynie w wersji stabilnej (czyli takie na które nałożony jest tag Coyote-1-1. System Coyote posiada następujące tagi:

• coyote-0-9-2-stable
• coyote-0-9-1-pre2
• coyote-0-9-1-rc1
• coyote-0-9-1-rc2

Gałęzie CVS

Wyobraź sobie sytuację, w której wydano wersje projektu, opatrzoną numerkiem 0.9.1-rc2. Na pliki tej wersji nałożono tagi; można dalej rozwijać projekt. Wyobraź sobie, że chcemy do systemu wprowadzić znaczące poprawki, których wdrożenie może potrwać i obejmują one kilka plików. W miare postępu prac, efekty naszych działań możemy umieszczać na CVS. Wyobraźmy teraz sobie, co się stanie jeżeli w edytowanym przez nas pliku (w którym wprowadzone są znaczące zmiany, jeszcze nie przetestowane) znaleziono poważny błąd. Błąd należy naprawić, ale ponieważ w pliku namieszaliśmy już wystarczająco dużo, trzeba wycofać wszystkie wprowadzone przez nas zmiany, poprawić błąd i poprawiony plik wysłać na FTP.

Na serwerze CVS oprócz głównego trzonu istnieją następujące gałęzie:

• coyote-0-9-1

Należy przy tym wyjaśnić główne pojęcia jakimi będziemy się posługiwać:

• gałąź - ang. branch; odrębna linia produkcyjna aplikacji
• trunk - ang. trzon; główna linia produkcyjna
• scalanie - ang. merge; włączenie gałęzi do głównej linii produkcyjnej

Obecną strukturę gałęzi na serwerze CVS prezentuje poniższy rynek:

                      ---------- 0.9.1 ---------               ----------- 0.9.2 ------- 
                     /                                        / 
                    /                                        /
 0.9.1-rc1 ----- 0.9.1-rc2 ------- 0.9.2 ------------------ /----------- 1.0 --------
                                                  |
				               0.9.2-rc1		   

Na tym przykładzie możesz zaobserwować, iż od wersji 0.9.1-rc2 nastąpił podział projektu na dwie linie produkcyjne: główną (trunk) oraz gałąź 0.9.1 (branch). Obie wersje kodu źródłowego mogą być rozwijane równocześnie. Programiści, którzy dotychczas rozwijają projekt mogą nadal pracować nad wersją stabilną. Natomiast programiści wprowadzający nowe funkcje do systemu mogą pracować nad wersją rozwojową (w tym wypadku, główna linia produkcyjna).

Jeżeli zespół programistów uzna, iż w gałęzi rozwojowej zrealizowano wszystkie punkty z TODO można wydać wersję 0.9.2-pre1 i wysłać pliki na serwer FTP serwisu 4programmers.net, aby sprawdzić jak projekt sprawuje się w "boju". Jeżeli wersja będzie na tyle stabilna żeby wydać wersję rc1, zakładamy tag i zamrażamy rozszerzanie funkcjonalności. Od tej pory tworzymy nową gałąź stabilną Coyote-0.9.2 i nie wprowadzamy już w tej wersji nowych funkcji - jedynie poprawiamy błędy, tak, aby zminimalizować ilość błędów. Jednocześnie w tym momencie zaczynają się pracę nad nową wersją aplikacji - 1.0 (tak jak to przedstawiono na rysunku powyżej).

Obsługa gałęzi w WinCVS

Pytanie: jak zorganizować sobie pracę nad danymi gałęziami? Opisze to na swoim przykładzie. Przede wszystkim należy przygotować sobie katalog roboczy, do którego sciągnięte zostaną pliki projektu. W moim wypadku wyglada to tak: na dysku C: posiadam katalog usr w którym znajduje się:

      - Apache (serwer HTTP)
      - php4 
      - mysql
      - src (katalog główny serwera)

W katalogu src posiadam foldery:

      - coyote (plik źrodłowe projektu Coyote)
      - roadrunner (pliki źródłowe projektu RoadRunne)	  

W Apacheu mam ustawione kilka wirtualnych hostów, ale aktualnie nie ma to znaczenia. Powiem tyle, że host 127.0.0.1 wskazuje na katalog coyote, a 127.0.0.3 wskazuje na katalog roadrunner. Czyli po wpisaniu w przeglądarce http://127.0.0.1 wyswietla mi się zawartość katalogu coyote. Tak więc pliki z CVS można ściągnąć do katalogu coyote i tym samym pod hostem 127.0.0.1 będzie nam działał Coyote. Jak to zrobić?

#. z menu Create wybieramy Checkout module
#. w polu Enter the module and name... wpisujemy coyote
#. w polu Local folder... wpisujemy C:\usr\src
#. na zakladce General w polu CVSROOT wpisujemy: anoncvs@cvs.4programmers.net:/usr/cvs
#. na zakladce Checkout options w polu By revision/tag... podajemy coyote-0-9-1-rc2
#. naciskamy OK, pliki zostają pobrane.

Jeżeli posiadasz konto na CVS, w miejsce anoncv wpisz swój login. Dzięki temu będziesz mógł na serwerze CVS dokonywać także zmian.

Ja mam jednak nieco inaczej. Otóż pliki z wersji 0.9.1-rc2 znajdują się u mnie w katalogu C:\usr\src\coyote\stable tak więc jeżeli chcę pracować na wersji stabilnej wchodzę poprzez adres http://127.0.0.1/stable. W folderze coyote mam także katalog dev w którym znajdują się wersje rozwojowe (dostęp do nich uzyskam poprzez adres http://127.0.0.1/dev/).

Jak to zrobiłem? Pobrałem źródła do katalogu C:\usr\src\coyote, co spowodowało iż CVS utworzył kolejny folder coyote tak więc zródła byłyby pod adresem C:\usr\src\coyote\coyote. Nazwę folderu coyote zmieniłem na stable i teraz mam kody pod katalogiem C:\usr\src\coyote\stable.

WAŻNE
W wersji stabilnej dokonujemy jedynie poprawek błędów oraz małych zmian. Takie poprawki można od razu umieścić na serwerze FTP (jeżeli masz do niego dostęp) 4programmers.net lub przekazać administratorowi lub osobie która ma dostęp do serwera FTP i może wrzucić poprawkę. Jeżeli chcesz dodać nową funkcję do systemu, wprowadzaj ją do wersji rozwojowej. Jeżeli nie jesteś pewien, lepiej zawsze spytać :-)

Scalanie

Wyobraź sobie, że w wersji rozwojowej poprawiasz błąd, który istnieje także w tym samym pliku, w wersji stabilnej. Tym samym musisz poprawić ten sam błąd w dwóch wersjach. Jest to troche uciążliwe stąd opcja merge która umożliwia właczenie poprawek z pliku z gałęzi do pliku z człona (trunk).

Ta sekcja wymaga aktualizacji. Jeżeli możesz rozbuduj ją o stosowny opis

Pisanie dokumentacji

(w budowie)

Jak możesz pomóc?

Zespół projektu Coyote potrzebuje Twojej pomocy. Jeżeli masz chęci, trochę wolnego czasu możesz pomóc nam w rozwojou systemu. Potrzebujemy pomocy zarówno w rozwijaniu dokumentacji, kodu źródłowego jak i skórek. Pytanie brzmi: co zrobić, aby nie zaszkodzić. Na początek, póki nie poznasz działania całego systemu, możesz ograniczyć swój wkład w projekt, prostymi zmianami, poprawianiem błędów. Co prawda na początku nie otrzymasz swojego własnego konta do CVS, poprawki będziesz musiał nadsyłać osobie, która ma odpowiednie uprawnienia.

W zrozumieniu działania projektu, pomocny może okazać się ten manual oraz forum dyskusyjne na którym omawiane są ważne sprawy związane z projektem. Jeżeli ktoś zgłosi błąd, możesz go znaleźć, poprawić, następnie poprawiony plik wysłać do dewelopera, który posiada dostęp do serwera CVS. Będziemy Ci bardzo wdzięczni, dzięki temu sprawisz, że zarówno serwis jak i system będą bardziej wydajne.

Jeżeli masz wątpliwości co do zmiany, nie wiesz, czy na pewno jej dokonać, najlepiej jest spytać kogoś z deweloperów. Najlepszą formą jest IRC: kanał #4programmers, serwer: krakow.ircnet.pl.

WAŻNE
Na CVS, w katalogu /docs/ANNOUNCEMENT znajdują się ogłoszenia dla deweloperów oraz prośby o pomoc. Prosimy o przeczytanie tego pliku.

Styl kodowania

Bardzo ważną rzeczą w programowaniu zespołowym jest standard kodowania, czyli mówiąc inaczej - standard zapisu składni języka programowania. Chodzi tutaj o wytyczne jakimi powinni kierować się programiści piszący kod w Coyote. Ponieważ Coyote jest pisany w języku PHP oraz SQL, zasady przedstawione w niniejszym podręczniku tyczą się jedynie zasad zapisywania kodu w tych językach. Nie będziemy tutaj opisywać zasad zapisywania kodu HTML czy CSS.

WAŻNE
Każdy programista piszący kod w projekcie Coyote ma obowiązek trzymania się reguł przedstawionych w tym rozdziale.

Pytanie, po co ustalać reguły zapisywania składni? Wszystko po to, aby zwiększyć czytelność kodu, która jest bardzo istotna w projektach zespołowych. Nie wystarczy bowiem, aby kod był poprawny i nie zawierał błędów. Istotne jest to, aby kod był zapisany elegancko i wyraźnie, tak, aby inni nie mieli problemów z jego "rozczytaniem".

Kodowanie PHP

Nazewnictwo

Zarówno w przypadku nazw funkcji, zmiennych czy stałych oraz klas stosujemy nazewnictwo angielskie. Np. Templates(), sql_query(), $topic_id. Nie deklaruj danych w ten sposób: Szablony(), zapytanie_sql(), $id_tematu.

Wcięcia

Stosujemy zasadę, że wcięcia powinny wynosić 4 (cztery) spację; niedozwolone jest używanie tabulatorów.

<?
    if ( $db->sql_query($sql) )
    {
        do_something();
    }
?> 

Tak więc podstawowe wcięcie o którego zaczynamy pierwszy blok instrukcji ma wcięcie w wielkości 4 spacji.

Struktury kontrolne

Do struktur kontrolnych zaliczamy instrukcję if(), while(), for() itp. Zalecane jest, aby w strukturach kontrolnych znalazla się jedna spacja po i przed nawiasem. Przykład:

if ( ( empty($cookie) ) && ( $id != 0 ) )
{
    // jakieś zadanie
}
else
if ( empty($cookie) )
{
    // zrób coś innego
}

Prosimy też o wpisywanie nawiasów klamrowych nawet wówczas, gdy nie są one potrzebne (np. gdy występuje jedynie jedna instrukcja). Zwiększa to czytelność kodu oraz eliminuje ew. błędy. Nie zapominamy oczywiście o czterech spacji wcięcia. Niedopuszczalna jest np. taka konstrukcja:

if ($x > 0) // coś tam
if ( $y > 1)
  // coś tam    

Deklaracja funkcji

Nie ma żadnych żelaznych reguł regulujących sposób definicji funkcji. Zaleca się jednak, aby funkcje były pisane małymi literami bez stosowania 'stylu wielbłądziego'. Dopuszczalne jest użycie znaku _ - np.

function do_something()
{
// dobrze
}

function DoSomething()
{
// zle
}

Komentarze

Jest jedna zasada: im więcej komentarzy tym lepiej. Dodatkowo każdy plik PHP powinien mieć na górze nagłówek wyglądający mniej więcej tak:

/*************************************************************************
**   Coyote Project
**
**   $Id: manual.html,v 1.2 2005/08/16 15:45:29 adam Exp $
**
**   File name :   login.php
**   Started   :   07.06.2004 r.
**   License   :   GPL
**************************************************************************
*/

Na samej górze zostanie wstawiona informacje na temat wersji, użytkownika który wysłał plik. Informacja dodawana jest automatycznie przez CVS. Jeżeli chodzi o komentowanie kodu to używaj komentarzy w stylu C ( /* */ ) oraz //. Oba są OK - nie używaj natomiast standardu komentowania Perla (#). Komentarze piszemy w języku polskim.

ChangeLog

Bardzo istotnym elementem w zbiorowych projektach jest naniesienie informacji o zmianach dokonanych przez danego dewelopera. W tym celu w projekcie obowiązuje tzw. plik ChangeLog, który jest umieszczony w głównym katalogu z kodami źródłowymi. Każda zmiana dokonana przez dewelopera powinna zostać opisana w tym pliku, tak, aby pozostali wiedzieli co zostało zmienione w danym dniu. Plik ChangeLog powinien mieć taką postać:

-------------------------
Coyote ChangeLog
-------------------------

$Id: manual.html,v 1.2 2005/08/16 15:45:29 adam Exp $
$Source: /usr/cvs/coyote/docs/manual.html,v $

16.08.2004 <adam@boduch.net>

  * poprawilem blad w plik db.php (nie zliczal ilosci zapytan kierowanych do bazy)

Zasada jest więc prosta. Najświeższe aktualności powinny być wpisywane na samej górze. Należy w tym miejscu dopisać datę poprawki, oraz w nawiasie - adres e-mail programisty. Następnie w wypunktowaniu należy umieścić krótki opis określający co i gdzie zostało zmienione. Miejscem do szerszego opisu poprawionego błędu jest skrypt (opis w formie komentarza) lub dziennik danego pliku (przy wysyłaniu poprawki pliku CVS prosi o wpisanie informacji dotyczącej danej wersji pliku).

Stałe

W przypadku deklaracji stałych, prosimy używać jedynie wielkich liter - pozwoli to na wyróżnienie stałych od zmiennych.

Zmienne

Zaleca się deklarowanie zmiennych, które były by najbardziej opisowe - np. $topic_id (ID tematu), $post_id (ID postu). Nie deklaruj zmiennych jednoznakowych - np. $x, $y, $z. Zmienne jednoznakowe mogą mieć zastosowanie jedynie w przypadku pętli for() i zmiennej pomocniczej.

Zapisywanie instrukcji SQL

W sprawie komend SQL kierujemy się zasadą, że nie należy oszczędzać linijek na to, aby w dłuższych zapytaniach były one czytelniejsze. Czyli: niech zapytania zajmują kilka linijek jeżeli jest to potrzebne - przykład:

$sql = 'SELECT *
        FROM ' . TOPIC . ' 
        WHERE topic_id = ' . $_GET['id'];      

Słowa kluczowe SQL muszą być napisane wielkimi literami (SELECT, UPDATE, WHERE itp) natomiast nazwy kolumn małymi. Przyjęło się aby całe zapytanie ujmować jedynie w pojedyncze apostrofy. Jak widzisz w powyższym przykładzie w przypadku wstawienia stałej lub zmiennej "rozdzielamy" łańcuch. Jeżeli natomiast chodzi o kolumny typu char() to należy używać apostrofów podwójnych:

$sql = 'UPDATE ' . TOPIC . ' 
        SET topic_subject = "' . $_POST['topic_subject'] . '"';

Oto inne przykłady:

$sql = 'SELECT topic_subject, topic_user, user_name 
        FROM ' . TOPIC . ', ' . USERS . ' 
        WHERE topic_id = ' . $_GET['id'] . '
            AND user_id = topic_id
            AND topic_id > 100';          

Zwróć uwagę na zapis słów kluczowych AND oraz OR - zostały one zapisane z wcięciem w wielkości czterech spacji.

BugTracker

Wszelkie błędy projektu Coyote proszę zgłaszać do BugTrackera, który znajduje się pod adresem http://4programmers.net/coyote/bug.php. Przed zgłoszeniem błedu proszę sprawdzić, czy podobny bład nie został już wcześniej zgłoszony. Można do tego celu użyć wyszukiwarki, która znajduje się na głównej stronie listy z błędami.

Architektura systemu

Na system Coyote składa się wiele komponentów. W nieniejszym rozdziale pragnę omówic parę podstawowych zagadnień związanych z systemem. Przede wszystkim przypatrz się poniższemu rysunkowi:

           Obsługa błędów
	         |
		 |
	   Obsługa danych
	         |
		 |
	   Obsługa sesji
	         |
		 |
           Obsługa szablonów
	    /          \
	   /            \
        skrypty        skrypty		

Prezentuje on zależność pomiędzy poszczególnymi modułami systemu.

Najważniejszym modułem w całym systemie jest moduł common.php który jest włączany przez każdy skrypt systemu. Jest on łacznikiem pomiedzy pozostałymi modułami. Tutaj następuje odczytanie pliku konfiguracyjnego oraz sprawdzenie, czy system jest w ogóle zainstalowany (stała INSTALLED w pliku config.php. Tutaj także następuje utworzenie instancji klas ErrorHandler, user oraz db.

Pliki systemu

Niniejsza sekcja zawiera opis wszystkich plików wchodzących w skład projektu. Opis zawiera informacje o przeznaczeniu danego pliku oraz skrótowy opis klas, funkcji zawartych w danym pliku.

root/extension.inc

Standardowo pliki PHP posiadają rozszerzenie .php. Serwer Apache umożliwia zmianę tego ustawienia, dzięki czemu pliki z rozszerzeniem - np. .html, będą traktowane jako skrypty PHP. Zmienna $phpEx znajdująca się w tym pliku zawiera informacje na temat rozszerzenia plików PHP. Oczywiście domyślną wartością tej zmiennej jest php. Ten plik jest włączany w każdym skrypcie celem odczytania rozszerzenia oraz włączenia do skryptu głównej części systemu (pliku common.php).

root/config.php

Najważniejszym plikiem całego systemu jest plik config.php. Zawiera on stałe określające hasło, login oraz host do bazy danych. Plik ten powinien być ściśle chroniony, polecamy nadanie mu prawa 0400, dzięki czemu nie będzie możliwy podgląd zawartości tego pliku. Poniższa tabela zawiera opis stałych zawartych w tym pliku.

Plik config.php jest włączany do systemu z poziomu skryptu common.php

Uwaga! Treść tego skryptu jest modyfikowana w trakcie procesu instalacji przez plik install.php.

root/common.php

Plik common.php stanowi główne ogniwo systemu. Jest to plik odpowiedzialny za włączanie do projektu wszystkich modułów. Tutaj tworzony jest obiekt klasy DB i od tego momentu można korzystać z bazy danych. Plik common.php jest włączany do każdego zewnętrznego skryptu systemu. Każdy zewnętrzny skrypt (tzn. zapewniający integracje z użytkownikiem) powinien na samej górze posiadać następujące instrukcje:

<?php 
  DEFINE('COYOTE', true); 
  
  include_once('extension.inc'); 
  include_once('common.' . $phpEx);
?>

W pierwszej linii deklarujemy stałą COYOTE. Dzięki temu jest możliwe włączenie do systemu pliku common.php. Plik common.php, nie jest plikiem zewnętrznym, nie może zostać odczytany przez użytkownika z poziomu przeglądarki (w przypadku podjęcia takiej próby, powinno zakończyć się to komunikatem Hacking attempt). Zadeklarowana stała informuje plik common.php, że nie następuje próba odczytania jego zawartości z zewnątrz (przez użytkownika), tylko plik jest włączany przez inny skrypt.

W kolejnym wierszu włączamy do skryptu plik extension.inc, w którym znajduje się rozszerzenie plików PHP. Posiadając rozszerzenie, możemy do projektu włączyć główny moduł - plik common.php.

root/include/cache.php

Moduł zawiera jedynie klasę Cache obsługującą pamięć podreczną cache. Umożliwia ona buforowanie danych wszelkiego rodzaju: tablic, łańcuchów, liczb oraz typów boolowskich.

Poradnik użytkownika

Licencja

Kod źródłowy projektu Coyote oparty jest na licencji GNU GPL. Treść licencji dołączona jest do plików projektu, w katalogu /docs.

Instalacja

Niniejsza sekcja przeznaczona jest zarówno dla deweloperów jak i użytkowników systemu Coyote. Opisuje ona proces instalacji projektu na własnym serwerze bądź lokalnym komputerze.

Wymagania

System Coyote jest pisany w języku PHP z wykorzystaniem realacyjnych baz danych. Do jego działania potrzeba więc następujących komponentów:

• Serwer HTTP (np. Apache lub IIS)
• PHP w wersji większej niż 4.3
• Baza danych MySQL (zalecana wersja to 4.0.1 lub 4.1.)

Obecnie system Coyote działa wyłącznie na bazie MySQL, lecz w prosty sposób można przystosować projekt do innego systemu - np. PostgreSQL. Wystarczy napisać odpowiednią klasę obsługi w module psql.php w katalogu /include/db (klasa powinna być podobna do klasy db w module mysql.php.

Projekt Coyote w wersji 0.9.2-dev był testowany zarówno na serwerze Apache i IIS i powinien zachowywać się tak samo na systemach Windows jak i Linux.

Nie będziemy tutaj omawiać procesu instalacji powyższych komponentów, zakładamy, że użytkownik ma je już zainstalowane.

Instalacja automatyczna

Na tym etapie zakładamy, że ściągnełeś na swój dysk kody źródłowe projektu. Jeżeli nie zrób to teraz. Kody źródłowe możesz ściągnąć ze strony http://4programmers.net/coyote/download.php. Możesz pobrać albo oficjalną paczkę, w postaci pliu .zip zawierającego kody źródłowe, z możliwą, jak najmniejsza ilością błędów. Możesz także pobrać aktualne kody źródłowe z serwera CVS.

WAŻNE
Kody źródłowe z domyślnej gałęzi CVS mogą i prawdopodobnie będą zawierać błędy. Są to kody nie przeznaczone do szerszego użytku (zazwyczaj są one na stadium deweloperskim, tj. wersje takiego kodu oznaczone są frazą -dev - np. 0.9.2-dev, 1.0-dev itp). Dlatego musisz się liczyć z tym, że projekt może zawierać błędy, instalacja automatyczna może nie udać się. W takim wypadku pozostaje samodzielne skonfigurowanie projektu.

Na potrzeby projektu, w katalogu /install znajduje się skrypt instalacyjny o nazwie install.php, który powinien w prosty sposób przeprowadzić użytkownika przez proces instalacji.

Na samym początku, po uruchomieniu skryptu, system sprawdzi, czy na Twoim komputerze zainstalowane są odpowiednie, wymagane do poprawnego działania - komponenty (tj. baza danych, PHP). W razie potrzeby skrypt utworzy także wymagane foldery.

W kolejnym kroku będziesz musiał podać pewne informacje, wymagane przez skrypt (np. login oraz hasło do bazy danych czy login i hasło administratora). Po kliknięciu przycisku Instaluj na podanym przez Ciebie serwerze SQL powinny zostać utworzone tabele. Skrypt powinien także utworzyć konto administratora oraz dodać podstawowe parametry konfiguracji.

Konfiguracja projektu zawarta jest w tabeli coyote_config.

Możliwe problemy

Naturalnym jest iż kod źródłowy zawiera błędy. Szczególnie w wersji rozwojowej. W tej sekcji przedstawiamy możliwe błędy jakie mogą wyniknąć w trakcie instalacji.

Błąd Could not find language directory

Ten błąd nie powinien nigdy się pojawić. Oznacza on, iż w katalogu /lang nie ma żadnych podfolderów, które zawierają tablicę $lang, czyli tablicę z komunikatami językowymi. W katalogu /lang powinien znajdować się folder pl, en itp. Błąd możesz naprawić ściągając z serwera CVS () odpowiedni katalog.

Błąd Nie można usunąc pliku config.php

Jeżeli chcesz reinstalować projekt, należy uprzednio usunąc plik config.php. Ten błąd pojawi się jeżeli system nie będzie mógł usunąć wspomnianego pliku. Błąd może oznaczać, iż plik config.php ma nadane prawa, które nie pozwalają na usunięcie pliku. Wspomniany bład może pojawić się raczej na systemach Unix/Linux.

Sprawdzenie nie zostało zakończone poprawnie. Przejrzyj listę nieprawidłowości

Przed instalacją skrypt sprawdza, czy można kontynuować instalację. Jeżeli pojawi się powyższy komunikat, to oznacza on, iż albo: wersja PHP jest nieprawidłowa, PHP nie obsługuje żadnego systemu baz danych (lub nie obsługuje go sam projekt), albo nie można utworzyć katalogów wymaganych, do prawidłowego działania projektu. Jeżeli skrypt nie może utworzyć wybranych folderów, to zapewne związane jest to z nieprawidłowymi prawami dostępu (np. na systemach Linux/Unix).

File does not exists

Błąd pojawi się w przypadku, gdy nie można odnaleźć pliku zawierającego strukturę bazy (czyli data.sql lub mysql.sql). W takim wypadku powinieneś ściągnąc wymienione pliki ze strony.

System nie mógł zapisać danych konfiguracyjnych do pliku config.php

Błąd związany jest z nieprawidłowymi prawami katalogów (systemy Linux/Unix) wskutek których system nie mogł w głównym katalogu projektu umieścić pliku config.php. W takim wypadku wyświetlona zostanie zawartość pliku, którą powinieneś sam, ręcznie umieścić w pliku config.php.

Błędne zapytanie SQL lub inny bład PHP

W takim wypadku prosimy zgłosić błąd do deweloperów projektu na forum dyskusyjnym. Błąd zostanie poprawiony w przeciągu kilku godzin.

Konfiguracja

Pomimo, iż projekt Coyote powinien działać bezproblemowo tuż po instalacji, niniejsza sekcja pozwoli użytkownikowi na głębsze zrozumienie jego działania. Umożliwi Ci także zmodyfikowanie jego dodatkowych parametrów, czy np. prawidłowe ustawienie pliku .htaccess.

Cron

Program Cron na systemach typu Unix służy do wykonywania stałych czynności o określonych porach. System Coyote jest także przystosowany do Crona, gdyż jego funkcje są bardzo przydatne w serwisie programistycznym (o charakterze vortalowym). Przede wszystkim można go wykorzystać do wysyłania newslettera (np. raz w tygodniu w nocy z niedzieli na poniedziałek). System Coyote umożliwia przesyłanie raportu na temat pliku umieszczonego na serwerze (ilość ściągnięć, ocena). Tu także sprawdza się Cron wysyłając taki raport raz w miesiącu. Inną funkcją jest przypominanie o rejestracji w serwisie. Cron umożliwia codzienne sprawdzanie użytkowników, którzy są zarejestrowani w serwisie ale zalogowali się ostatnio pół roku temu. W takim wypadku wysyła informację na e-mail. Te wszystkie funkcje wykorzystywane są w serwisie 4programmers.net, a to wszystko dzięki aplikacji Cron.

Wymagania

Czego zatem potrzebujesz? Przede wszystkim dostępu do shella oraz możliwości korzystania z programu Cron oraz wget. Jak to działa? Cron jest programem który "budzi się" co 1 min. i sprawdza, czy nie ma żadnych zadań do wykonania. Ty możesz określić jakie zadanie i kiedy ma być wykorzystywane. Jeżeli przykładowo ustaliłeś wykonywanie zadania wysyłania newslettera o 5.00 w nocy z niedzieli na poniedziałek, to program Cron sam wywoła np. skrypt cron.php umieszczony na serwerze, który wykona tę czynność. Ponieważ na wielu serwerach możliwość wykonywania skryptów PHP z poziomu linii komend jest zablokowane należy to zrobić z poziomu programu wget - np.

wget http://4programmers.net/cron.php/remind/haslo

Możliwość wywoływania skryptu z poziomu przeglądarki stwarza możliwości iż dowolna osoba będzie mogła uruchomić ten skrypt i - wysyłać np. raport o dowolnej porze. Dlatego zastosowano tu mechanizm zabezpieczający - tzn. składnia URL jest następująca:

http://serwer.com/cron.php/funkcja_do_wykonania/haslo_crona_ustalone_w_tabeli_coyote_config

Jak widzisz URL sprawia wrażenie jakby to było odwołanie do poszczególnych katalogów. Nic bardziej mylnego. Po prostu znaki / stanowią "rozdzielnik" pomiędzy poszczególnymi parametrami przekazywanymi do skryptu. Dlaczego tak? Ponieważ program wget zapewne lepiej sobie poradzi z takim URLem niżeli zawierającym znaki ? oraz ".

W każdym bądź razie program cron wykonuje o danej godzinie skrypt, który dokonuje pewnej czynności; jeżeli nie masz crona a chcesz korzystać z możliwości wysyłania np. powiadomienia będziesz niestety zmuszony do ręcznego wywoływania tego skryptu wpisując jego URL w przeglądarce.

Konfiguracja crona

Tak więc do skorzystania z możliwości crona musisz użyć shella - zaloguj się więc na swoje konto:

ssh user@host.com

Następnie wpisz:

crontab -e

W tym momencie powinien otworzyć się domyślny edytor tekstowy - w moim przypadku Nano. Tutaj należy wpisać odpowiednie instrukcje crona - np. w moim przypadku jest to:

10 5 * * * wget http://4programmers.net/cron.php/remind/123
10 3 * * 0 wget http://4programmers.net/cron.php/report/123

Format zapisu danych jest trochę specyficzny - np. wiersz oznacza iż każdego dnia o 5.10 nad ranem zostanie wykonany skrypt http://4programmers.net/include/cron/remind/123. Więcej informacji na temat konfiguracji crona znajdziesz tutaj.

Uaktualnianie do wyższych wersji

W tabeli coyote_config znajduje się pole BUILD_DATE, które zawiera informacje o dniu, z którego pochodzi struktura bazy danych. Informacja jest zapisana w formie: YYYYMMDD, np. 20050101, czyli struktura została zmieniona w dniu 01.01.2005. Wszelkie zmiany jakie zachodzą w bazie danych są odnotowywane w pliku upgrade.php, dzięki czemu skrypt ten jest w stanie uaktaulnić strukturę bazy do obecnej wersji systemu.

Zawsze, aktulna struktura bazy danych zawarta jest w katalogu install/schema, tak więc nic nie stoi na przeszkodzie, abyś po prostu przeinstalował projekt Coyote. Zalecamy jednak używanie skryptu upgrade.php, gdyż dzięki temu nie utracisz danych, które są zapisane w bazie.

Problemy przy użytkowaniu

Logowanie nie działa

Przyczyn takiego stanu rzeczy może być wiele. Przede wszystkim sprawdź, czy Twoja przeglądarka obsługuje pliki cookie (ciastka). System Coyote od wersji 0.9.2 obsługuje prawidłowo użytkowników, których przeglądarki nie obsługują ciastek. W takim wypadku, do każdego URL dołączony jest parametr określający ID sesji (ciag 32 znakowy). Jeżeli Twoja przeglądarka nie obsługuje plików cookie, nie możesz zalogować się w systemie.

Jeżeli system Coyote działa pod kontrolą serwera IIS, musisz upewnić się czy ustawione są prawidłowe wartości kolumn w tabeli coyote_config. Sprawdź czy wartość pola COOKIE_HOST jest pusta. Jeżeli jest pusta - logowanie powinno działać prawidłowo również na serwerach IIS. Jeżeli mimo tego, logowanie nie działa skonsultuj się z deweloperami na forum: http://4programmers.net/Forum/forum.php?f=11.