Przyszedł czas na drugie spojrzenie na Phing – czym on jest napisałem w skrócie w poprzednim wpisie.

Parametry uruchomienia

To narzędzie konsolowe, więc jest uruchamiane za pomocą wywołania phing [opcje] [cel] w konsoli (najlepiej w katalogu zawierającym plik build.xml). W wywołaniu można umieścić parametry/opcje:

• [nazwa celu] – nazwa celu, który ma zostać wywołany; jeżeli się nie pojawi zostanie uruchomiony cel domyślny projektu (<project ... default="domyslny_cel"/>);
• -h / -help – wyświetlenie ogólnej pomocy aplikacji;
• -l / -list – wyświetlenie listy celów zdefiniowanych w build.xml;
• -f [plik] / -buildfile [plik] – nazwa pliku skryptu, jeżeli inna niż build.xml;
• -D[właściwość]=[wartość] – przekazanie do skryptu właściwości o podanej wartości;
• -propertyfile [plik] – wczytanie podanego pliku z deklaracjami właściwości;

Cele

W poprzedniej sekcji wspomniałem o parametrze pozwalającym wyświetlić listę dostępnych celów. Jednak nie każdy cel powinien być uruchamiany „samodzielnie” – czasem jest potrzebny tylko do spełnienia jakichś podstawowych wymagań dla innego celu, który wykonuje faktyczne operacje. Przykładem może być cel, który wczytuje/ustala odpowiednie właściwości konfiguracyjne (np. ścieżki do katalogów, dane FTP etc.), wywołanie takiego celu samodzielnie do niczego nie doprowadzi. Dlatego takie „prywatne” cele można ukryć na liście za pomocą atrybutu <target ... hidden="true"/>.

Kolejną i chyba nabardziej przydatną możliwością celów jest ustalanie dla nich zależności – na przykład, żeby wykonać cel „deploy” (który wgrywa pliki na serwer), należy najpierw te pliki/katalogi przygotować (np. usunąć pliki tymczasowe). W skrypcie Phing nie trzeba deklarować dodatkowo wywołań celów, od których zależy wykonanie bieżącego lub samemu wywoływać ręcznie cele w odpowiedniej kolejności. W tym celu wykorzystuje się atrybut <target ... depends="cel1,cel2,cel3"/>

Są jeszcze dwa pomocne atrybuty celów – if, unless. Pierwszy uruchamia cel tylko w momencie, kiedy zmienna o podanej nazwie jest zadeklarowana. Drugi ma działanie odwrotnie. Poniżej przykład:

<?xml version="1.0" encoding="UTF-8"?>

<project name="HelloWorld" default="hello">

    <property name="uruchomione" value="" />

    <target name="hello" depends="cel1,cel2">
        <echo>Hello</echo>
    </target>

    <target name="cel1" if="uruchomione">
        <echo>cel 1</echo>
    </target>

    <target name="cel2" unless="uruchomione">
        <echo>cel 2</echo>
    </target>

</project>

Poniżej wynik uruchomienia (pojawiają się nagłówki wszystkich wywołanych celów, ale kod cel2 nie został wykonany ze względu na warunek zawarty w atrybucie unless.

cim@cim-k52:~/public_html/Phing$ phing 
Buildfile: /home/cim/public_html/Phing/build.xml

HelloWorld > cel1:

     [echo] cel 1

HelloWorld > cel2:


HelloWorld > hello:

     [echo] Hello

BUILD FINISHED

Total time: 0.0581 seconds

Właściwości

Właściwości są swego rodzaju zmiennymi dla skryptu Phing i zostały już użyte w poprzednich przykładach. Warto pamiętać, że odwołania do właściwości mają budowę ${nazwaWlasciwosci}, np. <echo>Wartość zmiennej: ${nazwa}</echo>. Przydatne jest używanie kropek dla budowania hierarchii – ${aplikacja.baza.host}% – można w ten sposób grupować właściwości co mocno zwiększa czytelność.

Do tej pory w przykładach pojawiały się właściwości z wartościami zadeklarowanymi w pliku build.xml, jednak to nie jedyne możliwe źródła danych:

• <property name="nazwa" value="wartosc" /> – pokazywany wcześniej sposób deklarowania zmiennej, w deklaracjach można odwoływać się do innych zmiennych (np. do jakiejś ścieżki dodać nazwe kolejnego katalogu);
• <property file="plik.properties" /> – wczytuje do skryptu właściwości zdefiniowane w podanym pliku; można użyć również dodatkowego atrybutu <property file="plik.properties" prefix="zPliku" /> co spowoduje dodanie prefiksu do wszystkich nazw właściwości znajdujących się w pliku;
• <echo>${env.PATH}</echo> – odwołania z prefiksem env. pozwalają na dostęp do zmiennych środowiskowych (zależne od systemu);

W przypadku zdublowania nazw właściwości Phing będzie zwracał pierwszą wartość właściwości, żeby zmienić to zachowanie trzeba dodać do drugiej deklaracji atrybut <property ... override="yes" />.

Podczas tworzenia ścieżek lub operacji plikowych pomocny może okazać się dostęp do ścieżki do katalogu projektu (zadeklarowanej w tagu <project ... basedir="/var/www/Projekt"> lub domyśnie ustawianej przez Phing). Ścieżka jest dostępna pod nazwą ${project.basedir}.

FileSet

Ponieważ Phing ma ułatwiać wdrożenia projektu posiada wsparcie do operowania na zbiorach plików – FileSet. Jeżeli na jakichś plikach mają zostać wykonane operacje można je wskazać bardzo dokładnie:

<target name="copy">
    <copy todir="kopia">
        <fileset dir=".">
            <exclude name="*.xml" />
            <include name="*.properties" />
            <include name="*.php" />
        </fileset>
    </copy>
</target>

Powyższa definicja przedstawia cel kopiujący pliki do katalogu „kopia” za pomocą polecenia copy. Natomiast miejsce z którego pliki są kopiowane („.” – czyli bieżący katalog) oraz deklaracje, które pliki (w tym wypadku według rozszerzeń) mają być kopiowane lub pomijane definiuje typ FileSet.

Definiowanie dołączeń/wykluczeń jest elastyczne:

• można wykorzystywać atrybuty: <fileset ... includes="..."/> i <fileset ... excludes="..."/> z wykorzystaniem przecinków lub spacji podawać wzorce, jednak powyżej kilku wzorców ta metoda sprawia, że skrypt jest mniej czytelny;
• można wykorzystać atrybuty: <fileset ... includesfile="..."/> i <fileset ... excludesfile="..."/> podając ścieżki do plików, w których każda linijka zawiera jeden wzorzec; jednak wymaga to utrzymywania dodatkowych plików oprócz niezbędnego build.xml;
• można użyć tagów <include/> i <exclude/> w tagu FileSet tak jak w przykładzie powyżej; chociaż przy wielu operacjach powtarzanie tego samego zestawu dołączeń/wykluczeń i późniejsze ich utrzymywanie różnież może być kłopotliwe;
• można użyć typu PatternSet.

Deklarowanie wzroców dopasowań nazw plików opiera się na gwiazkach („*” lub „**”). Jedna gwiazka pozwala na dopasowanie nazwy pliku/katalogu jednak w ramach tego dopasowania mogą się znajdować tylko pliki/katalogi bezpośrednio w danym katalogu. Natomiast dwie gwiazdki pozwalają na dopasowania również z uwzględnieniem zawartości podkatalogów. Przykłady z opisem są w oficjalnej dokumentacji.

PatternSet

W poprzenim akapicie wymieniłem kilka możliwości definiowania dołączeń/wykluczeń dla typu FileSet wraz z ich niedogodnościami. Ostatnią opcją jest typ PatternSet, który najprościej można opisać jako zbiór wzorców dla FileSet. Poniżej zmodyfikowany kod celu kopiującego pliki:

<patternset id="ogolne">
    <exclude name="*.xml" />
    <include name="*.properties" />
    <include name="*.php" />
</patternset>

<target name="copy">
    <copy todir="kopia">
        <fileset dir=".">
            <patternset refid="ogolne" />
        </fileset>
    </copy>
</target>

Wynik wykonania celu przedstawionego powyżej i z poprzedniego przykładu są identyczne. Różnia polega na tym, że wykorzystanie PatternSet ułatwia zapanowanie nad definicjami warunków – można je zdefiniować globalnie i tylko odwoływać się w razie potrzeby, a zmiany ograniczają się do jednego miejsca. Warto też zauważyć, że PatternSet w przeciwieństwie do FileSet jest niezależny od katalogu. Można zdefiniować warunki takie jak dołączanie plików PHP, HTML, TPL, pomijanie plików logów, plików tymczasowych etc. i używać ich w kontekście różnych katalogów. Sposoby definiowania warunków w PatternSet są takie same jak w FileSet z wyjątkiem możliwości odwoływania się do typu PatternSet.

Przydatne linki:

• Phing, czyli zautomatyzuj swoje zadania #1
• Phing – oficjalna dokumentacja