Использование PHP в командной строке

Начиная с версии 4.3.0, PHP поддерживает новый вид SAPI (интерфейс разработки серверных приложений) под названием CLI, что означает интерфейс командной строки. Как видно из названия, этот вид SAPI предназначен для разработки консольных (или даже десктопных) приложений на PHP. Имеется несколько несущественных различий между CLI SAPI и другими видами SAPI, которые будут рассмотрены в этой главе. Будет полезно заметить, что CLI и CGI - различные SAPI-интерфейсы, хотя в их поведении много общего.

Впервые в качестве эксперимента CLI SAPI был включен в релиз PHP 4.2.0, и при запуске скрипта ./configure необходимо было явно указывать опцию --enable-cli. Начиная с PHP 4.3.0, CLI SAPI не является экспериментальным, и опция сборки --enable-cli присутствует по умолчанию. Вы можете отключить CLI SAPI при помощи опции --disable-cli.

Что касается PHP 4.3.0, имя, расположение и существование бинарных модулей CLI/CGI зависит от того, как именно установлен PHP. По умолчанию при выполнении make создается как CGI, так и CLI модуль, в каталогах sapi/cgi/php и sapi/cli/php соответственно, внутри директории с исходными кодами PHP. Cледует заметить, что оба файла имеют одинаковое название: PHP. Что произойдет при выполнении make install, зависит от того, какие опции вы указали на стадии конфигурирования. В случае, если вы отдали предпочтение такому модулю SAPI как apxs, либо указали опцию --disable-cgi, модуль CLI будет скопирован в {PREFIX}/bin/php при выполнении make install, в противном случае будет скопирован CGI-модуль. Например, если при запуске скрипта ./configure вы указали опцию --with--apxs, CLI-версия будет скопирована в {PREFIX}/bin/php при выполнении make install. Если вы хотите перекрыть установленный CGI-модуль, используйте make install-cli после выполнения make install. В качестве альтернативы вы могли бы указать опцию --disable-cgi при выполнении скрипта ./configure.

Замечание: Поскольку обе опции, --enable-cli и --enable-cgi, присутствуют по умолчанию, одного присутствия строки --enable-cli при выполнении скрипта ./configure недостаточно для того, чтобы CLI-версия была установлена в {PREFIX}/bin/php при выполнении make install.

Дистрибутивы для Windows между версиями PHP 4.2.0 и PHP 4.2.3 включают в себя CLI-модуль как php-cli.exe, расположенный в той же директории, что и CGI-модуль php.exe. Начиная с PHP 4.3.0 дистрибутив для Windows влючает в себя CLI-модуль php.exe, расположенный в отдельной директории cli, полное имя - cli/php.exe. Начиная с PHP 5, CLI-модуль расположен в основной директории и называется php.exe. CGI-модуль также включен в дистрибутив под названием php-cgi.exe.

Начиная с PHP 5, в дистрибутив для Windows входит новый файл php-win.exe. Он полностью эквивалентен CLI, за исключением того, что php-win абсолютно ничего не выводит, что приводит к отстутствию консоли (окно DOS не появляется на экране). Это поведение похоже на php-gtk. При сборке из исходных кодов вам необходимо указать опцию --enable-cli-win32.

Замечание: Какой из вариантов SAPI установлен?
Выполните из командной строки php -v для получения информации о том, какой из двух модулей PHP установлен: CGI или CLI. Также вы можете использовать для этого функцию php_sapi_name() или константу PHP_SAPI.

Замечание: Соответствующая страница руководства Unix была добавлена в PHP 4.3.2. Вы можете увидеть ее, выполнив в консоли man php.

Основные отличия CLI SAPI от остальных реализаций SAPI:

• В отличие от CGI SAPI заголовки не пишутся в поток вывода.

  Несмотря на то, что в CGI SAPI есть способ подавить HTTP-заголовки, в CLI SAPI нет возможности их включить.

  CLI по умолчанию запускается в режиме с подавлением сообщений, тем не менее, ключи -q и --no-header сохранены для обратной совместимости, что позволяет использовать написанные ранее CGI-скрипты.

  Текущая директория не изменяется на рабочую директорию скрипта. (Ключи -C и --no-chdir сохранены для обратной совместимости)

  Сообщения об ошибках выдаются в текстовом режиме (без HTML-форматирования).

• Некоторые настройки php.ini переопределены в CLI SAPI, поскольку они не имеют особого смысла при работе в командной строке:

  Переопределяемые директивы php.ini

  Директива	Значение по умолчанию в CLI SAPI	Комментарий
  html_errors	FALSE	Бывает достаточно сложно прочитать в консоли сообщение об ошибке, когда оно наполнено бессмысленными HTML-тегами, поэтому значение по умолчанию данной опции всегда FALSE.
  implicit_flush	TRUE	Желательно, чтобы любой вывод print(), echo(), а также аналогичных функций немедлено отправлялся в стандартный поток вывода, а не попадал в буфер. Хотя вы все еще можете использовать буферизацию вывода, если хотите задержать вывод или манипулировать им.
  max_execution_time	0 (без ограничений)	Из-за неограниченных возможностей использования PHP в командной строке максимальное время выполнения скрипта не ограничено. В то время, как приложения, написанные для веб, выполняются достаточно быстро, консольные приложения могут выполняться в течении длительного времени.
  register_argc_argv	TRUE	Благодаря значению TRUE в CLI SAPI вам всегда доступны переменные argc (количество аргументов при запуске приложения) и argv (массив текущих аргументов). Начиная с PHP 4.3.0, при использовании CLI SAPI переменные $argc и and $argv зарегистрированы и заполнены соответствующими значениями. В более ранних версиях создание этих переменных, так же, как и для CGI или модуля веб-сервера, требует значение on директивы register_globals. Независимо от версии PHP или статуса опции register_global они всегда доступны как элементы массива $_SERVER или $HTTP_SERVER_VARS. Например: $_SERVER['argv']

  Замечание: Эти директивы не могут быть инициализированы другими значениями из конфигурационного файла php.ini или любого другого (в случае, если он указан). Это является ограничением, поскольку указанные выше значения по умолчанию применяются после обработки конфигурационных файлов. Тем не менее, эти значения могут быть изменены во время работы скрипта (хотя это не имеет особого смысла для указанных директив, например, для register_argc_argv).
  

• Облегчена работа с консолью, благодаря следующим определенным константам:

  Специфические CLI-константы

  Константа	Описание
  STDIN	Уже открытый поток stdin. Константа хранит результат <?php $stdin = fopen('php://stdin', 'r'); ?> Если вам необходимо прочитать строку из потока stdin, вы можете сделать это следующим образом: <?php    $line = trim(fgets(STDIN)); // читаем строку из STDIN    fscanf(STDIN, "%d\n", $number); // читаем число из STDIN    ?>
  STDOUT	Уже открытый поток stdout. Константа хранит результат <?php $stdout = fopen('php://stdout', 'w'); ?>
  STDERR	Уже открытый поток stderr. Константа хранит результат <?php $stderr = fopen('php://stderr', 'w'); ?>

  Имея все это, вы не должны самостоятельно открывать, например, поток для stderr, а просто используйте константу вместо дескриптора потока:

  php -r 'fwrite(STDERR, "stderr\n");'

  Также вам не надо закрывать эти потоки, PHP автоматически закрывает их после завершения скрипта.

• CLI SAPI не изменяет текущую директорию на директорию исполняемого скрипта!

  Пример, демонстрирующий отличие CGI SAPI:

  <?php
// Простейший тестовый скрипт под названием test.php
echo getcwd(), "\n";
?>

  В случае, если используется CGI версия, результат работы будет следующим:

  $ pwd
  /tmp
  
  $ php -q another_directory/test.php
  /tmp/another_directory
  

  Это наглядно демонстрирует тот факт, что PHP изменяет текущую директорию на директорию исполняемого скрипта.

  Использование CLI SAPI дает другой результат:

  $ pwd
  /tmp
  
  $ php -f another_directory/test.php
  /tmp
  

  Это позволяет писать более гибкие консольные скрипты на PHP.

  Замечание: CGI SAPI позволяет получить аналогичное CLI SAPI поведение в случае использования ключа -C при запуске из командной строки.
  

Список опций, доступный при запуске PHP из командной строки, может быть получен в любой момент путем запуска PHP с ключом -h:

Usage: php [options] [-f] <file> [args...]
       php [options] -r <code> [args...]
       php [options] [-- args...]
  -s               Отображает исходный код с цветной подсветкой
  -w               Отображает исходный текст без комментариев и пробелов
  -f <file>        Исполняет <file>
  -v               Выводит информацию о версии PHP
  -c <path>|<file> Ищет файл php.ini в указанной директории
  -a               Интерактивный запуск
  -d foo[=bar]     Установить конфигурационную опцию foo значением 'bar'
  -e               Генерация дополнительной информации для отладчика и профайлера
  -z <file>        Загрузить Zend-расширение <file>.
  -l               Проверить синтаксис
  -m               Показать подключенные модули
  -i               Выводит информацию о PHP
  -r <code>        Запустить PHP-код без использования <?..?>
  -h               Текущая справка

  args...          Аргументы, передаваемые скрипту. Используйте -- args в случае, если 
                   первый аргумент начинается с '-' или сам скрипт читается из потока STDIN.

CLI SAPI имеет три различных способа получения PHP-кода, который необходимо выполнить:

1. Указать PHP на исполнение конкретного файла.

   php my_script.php
   
   php -f my_script.php
   

   Оба способа (с или без использования ключа -f) исполняют указанный файл my_script.php. Вы можете выбрать любой файл - ваши PHP-скрипты не обязаны заканчиваться на .php, а могут иметь любое имя и расширение.

2. Указать PHP-код для выполнения непосредственно в командной строке.

   php -r 'print_r(get_defined_constants());'
   

   Особого внимания требует подстановка переменных окружения и использование кавычек.

   Замечание: Посмотрите внимательно на пример: в нем нет начальных и конечных тегов! При использовании ключа -r они не нужны. Использование их в данном примере приведет к синтаксической ошибке.
   

3. Предоставить PHP-код для выполнения посредством стандартного потока stdin.

   Это позволяет динамически создавать PHP-код и переадресовывать его исполняемому модулю, как показано в следующем (вымышленном) примере:

   $ some_application | some_filter | php | sort -u >final_output.txt
   

Вы не можете комбинировать эти три способа выполнения кода.

Как и в любом консольном приложении, не только PHP, но и сам скрипт может принимать аргументы командной строки. Количество передаваемых аргументов в PHP не ограничено (хотя консоль имеет некоторое ограничение на количество передаваемых символов, но на практике вы не должны с этим столкнуться). Все аргументы, переданные вашему скрипту, доступны в виде глобального массива $argv. Нулевой элемент содержит имя скрипта (которое является символом - в случае, если PHP-код читается из потока stdin или указан в командной строке при помощи ключа -r). Вторая определяемая глобальная переменная $argc содержит количество элементов массива $argv (а не количество аргументов, передаваемых при запуске).

До тех пор, пока передаваемые аргументы не начинаются с символа -, ничего особенного предпринимать не надо. Но при указании аргумента, который начинается с символа -, может возникнуть проблема, так как PHP попытается обработать их самостоятельно. Чтобы предотвратить это, используйте -- в качестве разделителя списка аргументов. Все последующие за таким разделителем аргументы будут переданы вашему скрипту без изменений.

# Приведенный пример не выполнит указанный код, а выдаст справку об использовании PHP
$ php -r 'var_dump($argv);' -h
Usage: php [options] [-f] <file> [args...]
[...]

# Аргумент '-h' будет передан скрипту, справка напечатана не будет
$ php -r 'var_dump($argv);' -- -h
array(2) {
  [0]=>
  string(1) "-"
  [1]=>
  string(2) "-h"
}

Однако, существует еще один способ использования PHP для написания консольных скриптов. Вы можете написать скрипт, первая строка которого начинается с #!/usr/bin/php. Следующие строки содержат обыкновенный PHP-код, обрамленный открывающими и завершающими PHP-тегами. Также необходимо установить права на выполнение (как правило, это chmod +x test), чтобы ваш скрипт мог запускаться, как обыкновенный консольный (или perl) скрипт:

Предположив, что наш скрипт называется test и расположен в текущей директории, мы можем выполнить следующее:

$ chmod +x test
$ ./test -h -- foo
array(4) {
  [0]=>
  string(6) "./test"
  [1]=>
  string(2) "-h"
  [2]=>
  string(2) "--"
  [3]=>
  string(3) "foo"
}

Полные названия опций доступны, начиная с PHP 4.3.3.

$ php -v
PHP 4.3.0 (cli), Copyright (c) 1997-2002 The PHP Group
Zend Engine v1.3.0, Copyright (c) 1998-2002 Zend Technologies

$ php -c /custom/directory/ my_script.php

$ php -c /custom/directory/custom-file.ini my_script.php

-d configuration_directive[=value]

# Если опущено значение, то соответствующей опции будет присвоено значение "1"
$ php -d max_execution_time
        -r '$foo = ini_get("max_execution_time"); var_dump($foo);'
string(1) "1"

# Указание пустого значения инициализирует соответствующую  опцию значением ""
php -d max_execution_time=
        -r '$foo = ini_get("max_execution_time"); var_dump($foo);'
string(0) ""

# Конфигурационная переменная будет установлена любым значением, 
# указанным после символа '='

$  php -d max_execution_time=20
        -r '$foo = ini_get("max_execution_time"); var_dump($foo);'
string(2) "20"
$  php
        -d max_execution_time=doesntmakesense
        -r '$foo = ini_get("max_execution_time"); var_dump($foo);'
string(15) "doesntmakesense"

$ php -m
[PHP Modules]
xml
tokenizer
standard
session
posix
pcre
overload
mysql
mbstring
ctype

[Zend Modules]

Исполняемый PHP-файл может использоваться для запуска PHP-скриптов независимо от веб-сервера. В случае, если вы работаете в Unix-подобной системе, вам необходимо добавить ко всем скриптам специальную первую строку и сделать их исполняемыми, чтобы указать, какая из программ должна обрабатывать эти скрипты. На Windows-платформах вы можете назначить обработчик php.exe для файлов с расширениями .php либо создать пакетный (.bat) файл для запуска скриптов посредством PHP. Строка, добавляемая вначале скрипта для Unix-систем, не влияет на их работу в ОС Windows, таким образом вы можете создавать кроссплатформенные скрипты. Ниже приведен простой пример скрипта, выполняемого из командной строки:

В приведенном примере мы используем специальную первую строку для указания на то, что этот скрипт необходимо запускать при помощи PHP. Поскольку мы работаем с CLI-версией, то HTTP-заголовки выводиться не будут. При написании консольных приложений на PHP вам доступны две переменные: $argc и $argv. Первая - количество переданных аргументов плюс один (имя выполняемого скрипта). Вторая - массив переданных аргументов, начиная с имени скрипта с нулевым индексом ($argv[0]).

Также в приведенном примере мы проверяем количество переданных аргументов. В случае, если их более или менее одного, а также в случае, если переданный аргумент был --help, -help, -h или -?, мы выводим справочное сообщение, подставляя имя выполняемого скрипта динамически. В обратном случае мы просто печатаем полученный аргумент.

Если вы хотите выполнить приведенный пример в Unix-системе, вам необходимо сделать его исполняемым и просто выполнить из консоли script.php echothis или script.php -h. В Windows-системе вы можете создать для этого пакетный файл:

@c:\php\cli\php.exe script.php %1 %2 %3 %4

Предполагая, что скрипт называется script.php и полный путь к CLI php.exe совпадает с c:\php\cli\php.exe, приведенный пакетный файл запустит скрипт с переданными вами параметрами: script.bat echothis либо script.bat -h.

Вы также можете ознакомится с расширением Readline, которое может быть использовано для усовершенствования консольного PHP-скрипта.