Aplikacje konsolowe

Aplikacje konsolowe używane są głównie przez aplikacje webowe do wykonywania zadań w trybie online, takich jak generowanie kodu, kompilacja indeksu wyszukiwania, wysyłanie maili, itp. Yii dostarcza frameworku do pisania aplikacji konsolowych w sposób systematyczny i obiektowo zorientowany. Yii udostępnia aplikacji konsolowej zasoby (np. połączenia z bazą danych), które używane są przez aplikację sieciową w trybie online.

Przegląd

Yii reprezentuje każde zadanie konsolowe pod pojęciem polecenia. Polecenia konsolowe zostały napisane jako klasy dziedziczące z CConsoleCommand.

Jeśli używamy narzędzia yiic webapp w celu utworzenia początkowego szkieletu aplikacji Yii, znajdujemy dwa następujące pliki w katalogu protected:

• yiic: jest skrypt wykonywalny na systemie Linux/Unix;
• yiic.bat: jest to wykonywalny plik wsadowy używany w systemie Windows.

W oknie konsoli, możemy wprowadzić następujące polecenia:

cd protected
yiic help

Spowoduje to wyświetlenie listy dostępnych poleceń konsolowych. Domyślnie, dostepne polecenia zawierają te dostarczone przez framework Yii (nazywane poleceniami systemowymi) oraz te utworzone przez użytkownika dla poszczególnych aplikacji (nazywanych poleceniami użytkownika).

Aby zobaczyć jak używać poleceń, możemy wywołać

yiic help <nazwa-polecenia>

Aby wywołać polecenie, używamy następującego formatu poleceń:

yiic <nazwa-polecenia> [parametry...]

1. Tworzenie poleceń ¶

Polecenia konsolowe zapisane są w plikach, z klasami, w katalogu określonym poprzez parametr CConsoleApplication::commandPath. Domyślnie wskazuje on na protected/commands.

Klasa polecenia konsolowego musi dziedziczyć po CConsoleCommand. Nazwa klasy powinna posiadać format XyzCommand, gdzie Xyz oznacza nazwę polecenia, którego nazwa rozpoczyna się dużą literą. Np, polecenie sitemap musi używać klasy o nazwie SitemapCommand. Wielkość liter poleceń konsolowych ma znaczenie.

Wskazówka: Poprzez skonfigurowanie CConsoleApplication::commandMap można posiadać również klasy poleceń spełniające inne konwencje nazewnictwa oraz znajdujące się w innych katalogach.

Aby utworzyć nowe polecenie, nierzadko trzeba nadpisać metodę CConsoleCommand::run() lub też stworzyć jedną bądź też kilka akcji poleceń (zostanie to wyjaśnione w dalszej części).

Podczas wykonywania polecenia konsolowego, metoda CConsoleCommand::run() zostanie wywołana przez aplikację konsolową. Każdy parametr konsoli poleceń zostanie przekazany do metody, zgodnie z następującą sygnaturą metody:

public function run($args) { ... }

gdzie $args wskazuje na dodatkowe parametry podane w linii poleceń.

W konsoli poleceń możemy używać Yii::app() w celu dostępu do instancji aplikacji konsolowej za pomocą której możemy również uzyskać dostęp do połączeń bazodanowych (np. Yii::app()->db). Można powiedzieć, że użyteczność jest bardzo podobna do tego, co możemy zrobić w aplikacji sieciowej.

Info: Poczynając od wersji 1.1.1, możemy również tworzyć globalne polecenia, które są współdzielone przez wszystkie aplikacje Yii znajdujące się na tej samej maszynie. W tym celu zdefiniuj gobalną zmienną o nazwie YII_CONSOLE_COMMANDS, wskazującą na istniejący katalog. Możemy umieścić nasze globalne polecenia w tym katalogu.

2. Akcje poleceń konsolowych ¶

Uwaga: Funkcjonalność poleceń konsolowych został udostępniona od wersji 1.1.5.

Polecenie konsolowe często potrzebuje operować różnymi parametrami linii poleceń, zarówno wymaganymi jak i opcjonalnymi. Polecenie konsolowe może również dostarczać kilku pod-poleceń do obsługi różnych podzadań. Czynność może zostać uproszczona poprzez używanie akcji konsoli poleceń.

Akcja poleceń konsolowych jest metodą w klasie polecenia konsolowego. Nazwa metody musi posiadać format actionXyz, gdzie Xyz określa nazwę akcji, której pierwsza litera nazwy zapisana jest za pomocą dużej litery. Na przykład, metoda actionIndex określa akcję o nazwie index.

W celu wywołania określonej akcji, używamy następującego formatu dla polecenia konsolowego

yiic <nazwa-polecenia> <nazwa-akcji> --opcja1=wartość --opcja2=wartość2 ...

Dodatkowe pary opcja-wartość zostaną przekazane jako nazwane parametry do metody akcji. Wartość opcji xyz zostanie przekazana do parametru $xyz metody akcji. Na przykład, jeśli zdefiniujemy następująco klasę poleceń:

class SitemapCommand extends CConsoleCommand
{
    public function actionIndex($type, $limit=5) { ... }
    public function actionInit() { ... }
}

W następstwie, wynikiem wszystkich kolejnych poleceń konsolowych będzie wywołanie actionIndex('News', 5):

yiic sitemap index --type=News --limit=5

// $limit przyjmuje wartość domyślną
yiic sitemap index --type=News

// $limit  przyjmuje wartość domyślną
// ponieważ 'index' jest akcją domyślną, możemy pominąć nazwę akcji 
yiic sitemap --type=News

// kolejność opcji nie ma znaczenia 
yiic sitemap index --limit=5 --type=News

Jeśli opcja podana została bez wartości (np. --type zamiast --type=News), to odpowiadająca mu wartość parametru akcji zostanie przyjęta jako true.

Uwaga: Nie wspieramy alternatywnego formatu opcji, takich jak: --type News, -t News.

Parametr może przyjmować wartości tablicowe jeśli zadeklarujemy go poprzez podpowiadanie typów:

public function actionIndex(array $types) { ... }

Aby wypełnić tablicę wartościami, po prostu powtarzamy tę samą opcje kilka razy w linii poleceń:

yiic sitemap index --types=News --types=Article

Powyższe polecenie wywoła ostatecznie actionIndex(array('News', 'Article')).

Poczynając od wersji 1.1.6, Yii wspiera używanie anonimowych parametrów akcji oraz opcji globalnych.

Anonimowe parametry odnoszą się do tych parametrów linii poleceń, które nie są podawane w formie opcji. Na przykład, w poleceniu yiic sitemap index --limit=5 News, mamy anonimowy parametr, którego wartością jest News, gdy zaś nazwany parametr limit przyjmuje wartość 5.

Aby móc używać anonimowych parametrów, akcja polecenia musi deklarować parametr o nazwie $args. Na przykład:

public function actionIndex($limit=10, $args=array()) {...}

Tablica $args będzie przechowywać wszystkie wartości dostępnych anonimowych parametrów.

Globalne opcje odnoszą się do tych opcji linii polecań, które są dzielone przez wszystkie akcje w poleceniu. Na przykład, w poleceniu, które dostarcza kilka akcji, możemy chcieć aby każda akcja rozpoznawała opcje nazwaną verbose (z ang. gadatliwy, wielomówny). Chociaż możemy zadeklarować parametr $verbose w każdej metodzie akcji, lepszym sposobem jest zadelarować ją jako publiczną zmienną klasy polecenia, która zamieni verbose w globalną opcję:

class SitemapCommand extends CConsoleCommand
{
    public $verbose=false;
    public function actionIndex($type) {...}
}

Powyższy kod pozwoli wykonać nam polecenie z opcją verbose:

yiic sitemap index --verbose=1 --type=News

3. Dostosowywanie aplikacji konsolowej ¶

Jeśli aplikacja została utworzona za pomocą narzędzia yiic webapp, domyślnie, konfiguracja aplikacji konsolowej będzie się znajdować w protected/config/console.php. Tak jak i plik konfiguracyjny aplikacji sieciowej, plik ten jest skryptem PHP, który zwraca tablicę reprezentującą inicjalne wartości właściwości instancji aplikacji konsolowej. W rezultacie, każda publiczna właściwość CConsoleApplication może zostać skonfigurowana w tym pliku.

Ponieważ polecenia konsoli często służą aplikacji sieciowej, potrzebuję dostępu do używanych przez nią zasobów (takich jak połączenie z bazą danych). Możemy go zagwarantować w następujący sposób poprzez plik konfiguracji aplikacji:

return array(
    ......
    'components'=>array(
        'db'=>array(
            ......
        ),
    ),
);

Jak widzimy, format konfiguracji jest bardzo podobny do tego z aplikacji sieciowej. Dzieje się tak gdyż zarówno CConsoleApplication jak i CWebApplication dziedziczą po tej samej klasie bazowej.