Файлы и сети

Глава из книги “PHP 5.1. Руководство программиста”

Автор: Игорь Григин
Источник: PHP 5.1. Руководство программиста
Материал предоставил: Издательство "Питер"
Опубликовано: 21.04.2006
Версия текста: 1.0
Файловая система
Работа с директориями
Получение свойств и атрибутов файлов
Системные функции
Ввод и вывод
Работа с архивами Zlib
Сжатые файлы Bzip2
FTP
Сетевые функции
Сетевая отладка PHP
Общий низкоуровневый сетевой интерфейс
Низкоуровневый сетевой интерфейс
Библиотека CURL (Client URL Library)
Отправка почты
IMAP, POP3 и NNTP
Вспомогательные функции

Файловая система

Работа с директориями

basename. Компонент файлового имени в пути

string basename (string path)

Функция возвращает имя файла, выделенного из строки path, в которой передается путь к файлу.

В большинстве систем разделителем директорий в пути служит прямой слеш. В Windows также может использоваться обратный слеш. Пример использования функции приведен в листинге 4.1.

Листинг 4.1
$path = "/home/httpd/html/index.php3";
$file = basename ($path); // $file is set to "index.php3"

См. также dirname().

dirname. Исключение имени файла из пути

string dirname (string path)

Функция возвращает строку пути path, из которой исключено имя файла.

В большинстве систем разделителем директорий в пути служит прямой слеш. В Windows также может использоваться обратный слеш. Пример использования функции приведен в листинге 4.2.

Листинг 4.2
$path = "/etc/passwd";
$file = dirname ($path); // $file is set to "/etc"

См. также basename().

realpath. Развертывание сокращений в строке пути

string realpath (string path)

Функция заменяет все символьные ссылки и сокращения пути в строке path, которые были сделаны для улучшения его читабельности, и возвращает полученный абсолютный путь, как показано в следующем примере:

$real_path = realpath ("../../index.php");

getcwd. Текущая директория

string getcwd(void);

Функция возвращает текущую директорию, в которой и проводятся файловые операции.

chdir. Смена текущей директории

int chdir (string directory)

Функция меняет текущую директорию на ту, которая указана в параметре directory. При возникновении ошибки функция возвращает значение FALSE. В ином случае возвращается значение TRUE.

mkdir. Создание директории

int mkdir (string pathname, int mode)

Функция пытается создать новую директорию pathname с атрибутами доступа mode. Если атрибуты указываются в восьмеричной системе, первой цифрой должен быть ноль, как показано в следующем примере:

mkdir ("/path/to/my/dir", 0700);

При возникновении ошибки функция возвращает значение FALSE. В ином случае возвращается значение TRUE.

См. также rmdir().

rmdir. Удаление директории

int rmdir (string dirname)

Функция пытается удалить директорию dirname. Директория должна быть пустой, и ее атрибуты должны позволять выполнить удаление.

При возникновении ошибки функция возвращает значение FALSE. В ином случае возвращается значение TRUE.

См. также mkdir().

diskfreespace. Свободное пространство в директории

float diskfreespace (string directory)

Функция возвращает в байтах свободное пространство в директории directory. Фактически возвращается объем свободного пространства на диске, как показано в следующем примере:

$df = diskfreespace("/"); // свободное место в корневой директории "/"

dir. Класс директории

new dir (string directory)

Функция представляет собой механизм для получения списка файлов директории. При создании объекта на основе класса открывается директория, указанная в параметре directory.

После этого становятся доступны дескриптор директории handle, который может использоваться с функциями readdir(), rewinddir() и closedir(), и строка path, указывающая, какая директория в настоящий момент используется. У класса имеется три метода: read, rewind и close.

Пример использования функции приведен в листинге 4.3.

Листинг 4.3
$d = dir("/etc");
echo "Aane?eioi?: ".$d->handle."<br>\n";
echo "Ioou: ".$d->path."<br>\n";
while($entry=$d->read()) { // iineaaiaaoaeuii auaiaeou
   echo $entry."<br>\n";   // eiy ea?aiai oaeea 
}                          // a ae?aeoi?ee
$d->close();

opendir. Открытие дескриптора директории

int opendir (string path)

Функция возвращает дескриптор открытой директории path, который затем можно использовать в функциях closedir(), readdir(), rewinddir().

closedir. Закрытие открытого дескриптора директории

void closedir (int dir_handle)

В аргументе dir_handle указывается дескриптор директории, возвращенный функцией opendir().

readdir. Получение имени следующего файла в списке директории

string readdir (int dir_handle)

Функция возвращает имя следующего файла в директории. Файлы возвращаются в виде неупорядоченной последовательности. Пример использования этой функции приведен в листинге 4.4.

Листинг 4.4
<?php
$handle=opendir('.');
echo "Directory handle: $handle\n";
echo "Files:\n";
while (($file = readdir($handle))!==FALSE) {
   echo "$file\n";
}
closedir($handle); 
?>

Следует отметить, что функция также возвращает значения “.” и “..”. Если они не требуются, их можно просто исключать, как показано в листинге 4.5.

Листинг 4.5
$handle=opendir('.'); 
while (FALSE!==($file = readdir($handle))) { 
   if ($file != "." && $file != "..") { 
      echo "$file\n"; 
   }
}
closedir($handle);

rewinddir. Реинициализация дескриптора директории

void rewinddir (int dir_handle)

После вызова этой функции функция readdir() с аргументом dir_handle будет возвращать имена файлов с самого начала в списке директории.

Получение свойств и атрибутов файлов

file_exists. Проверка существования файла

bool file_exists (string filename)

Функция возвращает значение TRUE, если файл, указанный в параметре filename, существует. В ином случае возвращается значение FALSE. Функция не работает с удаленными файлами, потому что файл должен находиться в доступной для сервера файловой системе.

Результаты функции кэшируются, см. функцию clearstatcache().

is_dir. Проверка существования директории

bool is_dir (string filename)

Функция возвращает значение TRUE, если указанная директория filename существует.

Результаты функции кэшируются, см. функцию clearstatcache().

См. также is_file() и is_link().

is_executable. Проверка существования запускаемого файла

bool is_executable (string filename)

Функция возвращает значение TRUE, если исполняемый файл, указанный в параметре filename, существует.

Результаты функции кэшируются, см. функцию clearstatcache().

См. также is_file() и is_link().

is_file. Существование обычного файла

bool is_file (string filename)

Функция возвращает значение TRUE, если файл, указанный в параметре filename, существует.

Результаты функции кэшируются, см. функцию clearstatcache().

См. также is_dir() и is_link().

is_readable. Существование файла, доступного для чтения

bool is_readable (string filename)

Обычно PHP осуществляет доступ к файлу с привилегиями пользователя, запускающего веб-сервер. Эта функция проверяет, может ли файл, имя которого указано в параметре filename, быть прочитан с правами искомой учетной записи.

Результаты функции кэшируются, см. функцию clearstatcache().

См. также is_writeable().

is_writeable. Существование файла, доступного для записи

bool is_writeable (string filename)

Обычно PHP осуществляет доступ к файлу с привилегиями пользователя, запускающего веб-сервер. Эта функция проверяет, может ли файл, имя которого указано в параметре filename, быть открыт для записи с правами искомой учетной записи.

Результаты функции кэшируются, см. функцию clearstatcache().

См. также is_readable().

is_uploaded_file. Файл, загруженный методом HTTP POST

bool is_uploaded_file (string filename)

Функция возвращает значение TRUE, если файл с именем filename был загружен на сервер при помощи метода HTTP POST. Часто это помогает убедиться, что пользователи злоумышленно не пытались заставить скрипт работать с теми файлами, с которыми не следует позволять ему взаимодействовать.

См. также move_uploaded_file(), и раздел “Загрузка файлов на сервер”, с. .

filetype. Получение типа файла

string filetype (string filename)

Функция возвращает тип файла, имя которого передано в параметре filename. Список возвращаемых значений не так уж велик: fifo, char, dir, block, link, file, unknown. В случае возникновения ошибки возвращается значение FALSE.

Результаты функции кэшируются, см. функцию clearstatcache().

fileatime. Получение времени последнего доступа к файлу

int fileatime (string filename)

Функция возвращает время последнего открытия файла в формате “UNIX timestamp”. В случае возникновения ошибки возвращается значение FALSE.

Результаты функции кэшируются, см. функцию clearstatcache().

Атрибут времени последнего доступа к файлу изменяется каждый раз, когда данные файла читаются. Это сильно снижает производительность при интенсивной работе с файлами и директориями, поэтому часто изменение этого атрибута в операционных системах блокируют.

filemtime. Получение времени последней записи в файл

int filemtime (string filename)

Функция возвращает время последней записи информации в файл в формате “UNIX timestamp”. В случае возникновения ошибки возвращается значение FALSE.

Результаты функции кэшируются, см. функцию clearstatcache().

Этот атрибут файла отражает последнее изменение самих данных файла. Можно использовать функцию date() для преобразования возвращаемого значения в читабельный формат.

filectime. Получение времени последнего изменения файла

int filectime (string filename)

Функция возвращает время последнего изменения файла в формате “UNIX timestamp”. В случае возникновения ошибки возвращается значение FALSE.

Результаты функции кэшируются, см. функцию clearstatcache().

В большинстве систем изменением файла считается также изменение его атрибутов или прав доступа. См. также filemtime() и fileatime().

В некоторых системах этот атрибут неправильно рассматривается как время создания файла.

filegroup. Получение группы принадлежности файла

int filegroup (string filename)

Функция возвращает идентификатор группы владельца файла. В случае возникновения ошибки возвращается значение FALSE. Идентификатор группы возвращается в численном формате, поэтому следует использовать функцию posix_getgrgid() для преобразования идентификатора в имя группы.

Результаты функции кэшируются, см. функцию clearstatcache().

Функция не работает в системе Windows.

fileowner. Получение группы владельца файла

int fileowner (string filename)

Функция возвращает идентификатор владельца файла. В случае возникновения ошибки возвращается значение FALSE. Идентификатор владельца возвращается в численном формате, поэтому следует использовать функцию posix_getpwuid() для преобразования идентификатора в имя владельца.

Результаты функции кэшируются, см. функцию clearstatcache().

Функция не работает в системе Windows.

fileperms. Получение атрибутов доступа файла

int fileperms (string filename)

Функция возвращает целое число, содержащее права доступа к файлу. В случае возникновения ошибки возвращается значение FALSE.

Результаты функции кэшируются, см. функцию clearstatcache().

filesize. Получение размера файла

int filesize (string filename)

Функция возвращает размер файла, имя которого передано в параметре filename. В случае возникновения ошибки возвращается значение FALSE.

Результаты функции кэшируются, см. функцию clearstatcache().

fileinode. Получение файлового блока inode

int fileinode (string filename)

Функция возвращает номер блока файла в файловой системе. В случае возникновения ошибки возвращается значение FALSE.

Результаты функции кэшируются, см. функцию clearstatcache().

Функция не работает в системе Windows.

Манипулирование файлами

touch. Установка времени последней модификации файла

int touch (string filename [, int time])

Функция пытается установить для файла filename атрибут последней модификации time. Если он не указывается, то используется текущее время. Если файл не существует, то он создается, поэтому функцию часто используют для создания файла. После успешного выполнения возвращается значение TRUE. В случае возникновения ошибки возвращается значение FALSE. Пример обработки возвращаемого значения может выглядеть достаточно просто:

if (touch ($FileName)) { print "ОК";} else { print "Ошибка"; }

unlinkunlink. Удаление файла

int unlink (string filename)

Функция пытается удалить файл, имя которого передается в качестве параметра. После успешного выполнения возвращается значение TRUE. В случае возникновения ошибки возвращается значение FALSE.

Для удаления директорий следует использовать функцию rmdir().

Функция может не работать в системе Windows.

copy. Копирование файла

int copy (string source, string dest)

Функция копирует файл source в место, указанное в параметре dest. После успешного выполнения возвращается значение TRUE. В случае возникновения ошибки возвращается значение FALSE. Пример использования функции приведен в листинге 4.6.

Листинг 4.6
if (!copy($file, $file.'.bak')) {
   print ("Ошибка копирования $file...<br>\n");
}

См. также rename().

rename. Переименование или перемещение файла

int rename (string oldname, string newname)

Функция переименовывает файл oldname в newname. После успешного выполнения возвращается значение TRUE. В случае возникновения ошибки возвращается значение FALSE.

move_uploaded_filemove_uploaded_file. Перемещение загруженного файла

bool move_uploaded_file (string filename, string destination)

Функция проверяет, был ли загружен файл filename, при помощи метода HTTP POST. Если файл действительно был загружен на сервер пользователем, функция перемещает его в новое место destination. Если это нельзя сделать, возвращается значение FALSE.

См. также is_uploaded_file() и раздел “Загрузка файлов на сервер”.

tempnam. Генерация уникального имени временного файла

string tempnam (string dir, string prefix)

Функция возвращает имя несуществующего в директории dir файла, начинающегося с символьной последовательности prefix. Если аргументы не указываются, то используется временная директория системы. В системе Windows она указана в системной переменной TMP, и значение аргумента dir не используется. В системе Linux используется значение TMPDIR. В случае возникновения ошибки возвращается пустая строка.

Пример использования функции приведен в листинге 4.7.

Листинг 4.7
$tmpfname = tempnam ("/tmp", "FOO");
// a Windows 2000 выдаст, например:
//E:\DOCUME~1\9335~1\LOCALS~1\Temp\FOO9.tmp      

В версии PHP 4.0.3 поведение функции было изменено. При получении имени одновременно создавался соответствующий файл. Это было сделано для того, чтобы в промежутке между получением уникального имени и созданием такого файла другое приложение не могло создать и использовать идентичный временный файл.

См. также tmpfile().

tmpfile. Создание временного файла

int tmpfile (void)

Функция создает уникальный файл в режиме записи, возвращая его дескриптор подобно функции fopen(). Этот файл автоматически удаляется при его явном закрытии или завершении скрипта.

См. также tempnam().

chgrp. Изменение группы файла

int chgrp (string filename, mixed group)

Файл пытается сменить у файла filename группу на значение group. Только администратор может безусловно изменять этот атрибут у любого файла, иначе необходимо входить в группу владельцев файла. После успешного выполнения возвращается значение TRUE. В случае возникновения ошибки возвращается значение FALSE.

Функция не работает в системе Windows.

См. также chown() и chmod().

chmod. Изменение атрибутов доступа файла

int chmod (string filename, int mode)

Функция пытается изменить атрибуты доступа к файлу filename. Аргумент mode нужно явно задавать как восьмеричное число, а строковые аргументы не будут восприниматься. Пример использования функции приведен в листинге 4.8.

Листинг 4.8
chmod ("/somedir/somefile", 755);
// десятичное число ; возможно неверное значение 
chmod ("/somedir/somefile", "u+rwx,go+rx"); 
// строка; неверное значение 
chmod ("/somedir/somefile", 0755);  
// восьмеричное число; правильный вариант

После успешного выполнения возвращается значение TRUE. В случае возникновения ошибки возвращается значение FALSE. Функция не работает в системе Windows.

См. также chown() и chgrp().

chown. Смена владельца файла

int chown (string filename, mixed user)

Функция меняет владельца файла filename. Следует учитывать, что только администратор может изменять этот атрибут файла.

После успешного выполнения возвращается значение TRUE. В случае возникновения ошибки возвращается значение FALSE. Функция не работает в системе Windows.

См. также chown() и chmod().

umask. Изменение текущего значения umask

int umask (int mask)

Функция устанавливает значение PHP umask равным (mask & 0777) и возвращает предыдущее значение umask. При использовании PHP как серверного модуля, значение umask восстанавливается при завершении каждого запроса.

Если не указывать аргумент, то просто возвращается текущая маска.

Функция может не работать в системе Windows.

Системные функции

linkinfo. Получение информации о файловой ссылке

int linkinfo (string path)

Функция возвращает поле st_dev структуры stat UNIX C, возвращаемой системным запросом lstat, или значение FALSE при возникновении ошибки. Функция используется для проверки существования файловой ссылки с именем path. Такой же метод используется макросом S_ISLNK, определенным в файле stat.h.

Функция не работает в системе Windows.

См. также symlink(), link() и readlink().

readlink. Получение назначения символьной ссылки

string readlink (string path)

Функция возвращает путь к файлу, на который указывает ссылка path, или нулевое значение при возникновении ошибки.

Функция не работает в системе Windows.

См. также symlink(), readlink() и linkinfo().

symlink. Создание символьной ссылки на файл

int symlink (string target, string link)

Функция создает файл link, являющийся ссылкой на существующий файл target.

Функция не работает в системе Windows.

См. также link(), readlink() и linkinfo().

stat. Получение информации о файле

array stat (string filename)

Возвращает в массиве информацию о файле, имя которого передано в параметре filename. Состав массива указан в следующем списке:

  1. Номер устройства (device).
  2. Номер файлового блока (inode).
  3. Режим защиты файлового блока (inode).
  4. Число файловых связей (links).
  5. Идентификатор владельца (user id).
  6. Идентификатор группы (group id).
  7. Тип блочного устройства (inode).
  8. Размер в байтах.
  9. Время последнего доступа.
  10. Время последней модификации.
  11. Время последней записи.
  12. Размер блока для системного ввода-вывода.
  13. Количество занимаемых блоков.

Размер блока для системного ввода-вывода и тип блочного устройства можно определить только на системах, поддерживающих тип st_blksize. Для других систем, в том числе и для Windows, возвращается значение –1.

Результаты функции кэшируются, см. функцию clearstatcache().

lstat. Получение информации о файле или ссылке на файл

array lstat (string filename)

Функция аналогична stat(), но она также работает с файловыми ссылками, причем информация возвращается о самой ссылке.

clearstatcacheclearstatcache. Очистка кэша файловой информации

void clearstatcache(void)

На многих системах системный вызов stat() или lstat() требует достаточно много ресурсов для выполнения, поэтому результаты работы этих функции кэшируются и при последующем вызове извлекаются из кеша. При необходимости обновления кэшированных данных вызывается данная функция. Она воздействует на функции stat(), lstat(), file_exists(), is_writeable(), is_readable(), is_executable(), is_file(), is_dir(), is_link(), filectime(), fileatime(), filemtime(), fileinode(), filegroup(), fileowner(), filesize(), filetype() и fileperms().

ftruncateftruncate. Урезание размера файла

int ftruncate (int fp, int size)

В качестве аргумента fp принимается дескриптор файла, возвращаемый функцией fopen(). Функция возвращает значение TRUE или FALSE.

set_file_bufferset_file_buffer. Установка буферизации файловых операций

int set_file_buffer (int fp, int buffer)

Вывод в файл, осуществляемый функцией fwrite(), обычно буферизируется порциями по 8 килобайт. Это означает, что если два процесса одновременно осуществляют запись в один поток вывода, то каждый из них после записи очередной порции данных останавливается, чтобы позволить другому выполнить операцию записи.

Функция устанавливает размер буфера для операций записи в файл, имеющий дескриптор fp. Если аргумент buffer указывается с нулевым значением, то буферизация отменяется. Это приводит к тому, что все операции записи, выполненные функцией fwrite(), совершаются при ее завершении и еще до того, как другим приложениям будет разрешена запись в тот же файл.

Если запрос не может быть выполнен, то возвращается значение 0 или EOF. Пример использования функции приведен в листинге 4.9.

Листинг 4.9
$fp=fopen($file, "w");
if($fp){
  set_file_buffer($fp, 0);
  fputs($fp, $output);
  fclose($fp);
}

См. также fopen(), fwrite().

flock. Блокирование совместного доступа

bool flock (int fp, int operation [, int wouldblock])

PHP поддерживает совместимый способ блокировки файла в целом для разделения совместного доступа к нему из разных потоков. При этом все приложения, осуществляющие доступ, должны использовать этот единый способ блокировки.

Функция использует простейший метод блокировки чтения и записи, который поддерживается в большинстве систем (UNIX и Windows). В аргументах функции указывается: дескриптор открытого файла fp и способ его блокировки operation, значения которого перечислены в следующем списке:

Если в необязательном третьем аргументе указывается значение TRUE, то это позволяет выяснить, возможно ли вообще осуществление блокировки.

В случае успешной установки блокировки возвращается значение TRUE. В ином случае возвращается значение FALSE.

В большинстве операционных систем функция реализована для уровня приложения, и при ее использовании на многопоточном сервере с таким API, как ISAPI, нельзя полностью полагаться на нее для защиты от разных копий одного процесса PHP. Фактически для операционной системы потоки одного процесса неразличимы.

Ввод и вывод

fopen. Открытие файла или URL

int fopen (string filename, string mode [, int use_include_path])

Функция открывает указанный аргументом filename поток ввода-вывода (файл) в режиме mode и возвращает соответствующий дескриптор.

Чтобы можно было открывать удаленные файлы при помощи протоколов HTTP и FTP, необходимо чтобы опция конфигурации allow_url_fopen была разрешена. Эта способность PHP называется “URL fopen wrapper”. Это позволит также открывать сжатые файлы (gzip и bz2) аналогичным способом.

Если строка пути filename начинается с http:// и доступ к указанному серверу возможен, то открывается сеанс связи. После этого указатель файла настраивается на текст, получаемый в ответ на запрос. Этот механизм не обрабатывает редиректы адреса HTTP, поэтому необходимо включать завершающие слеши для директорий. Файл может быть открыт только для чтения.

Если строка пути filename начинается с ftp://, то файл запрашивается через протокол FTP. При этом сервер должен поддерживать пассивный метод передачи. Если это позволяет сервер, то файл может быть открыт либо для чтения, либо для записи.

Если в аргументе filename указывается значение php://stdin, php://stdout, или php://stderr, то открывается соответствующий стандартный поток.

В остальных случаях просто открывается соответствующий файл в локальной файловой системе. Можно указать необязательный аргумент use_include_path с единичным значением, и тогда файл будет разыскиваться не только в текущей директории, но и в установленной по умолчанию для подключаемых файлов.

Если открыть файл в заданном режиме не удается, то возвращается значение FALSE.

Значения параметра mode перечислены в следующем списке:

В аргументе mode можно также указать символ b, что бывает полезно в системах, различающих двоичные и текстовые файлы. В других системах это различие игнорируется.

В листинге 4.10 приведены примеры вызова этой функции.

Листинг 4.10
$fp = fopen ("/home/rasmus/file.txt", "r");
$fp = fopen ("/home/rasmus/file.gif", "wb");
$fp = fopen ("http://www.php.net/", "r");
$fp = fopen ("ftp://user:password@example.com/", "w");

Следует помнить, что для доступа к файлу необходимы соответствующие полномочия. В системе Windows обратные слеши должны быть двойными или заменяться на прямые, как показано в следующем вызове:

 $fp = fopen ("c:\\data\\info.txt", "r")

Пример, приведенный в листинге 4.11, открывает удаленный HTML-файл и выводит его заголовок.

Листинг 4.11
<?php
$file = fopen ("http://www.php.net/", "r");
if (!$file) {
   echo "<p>Невозможно открыть удаленный файл.\n";
   exit;
}
while (!feof ($file)) {
   $line = fgets ($file, 1024);
   /* Заголовок и его теги должны располагаться в одной строке */
   if (eregi ("<title>(.*)</title>", $line, $out)) {
      $title = $out[1];
      break;
   }
}
fclose($file);
echo $title;
?>

В листинге 4.12 демонстрируется открытие и запись в FTP-файл. Хотя для работы с FTP-файлами рекомендуется использовать отдельные функции.

Листинг 4.12
<?php
$file = fopen ("ftp://ftp.php.net/incoming/outputfile", "w");
if (!$file) {
   echo "<p> Невозможно открыть удаленный файл для записи.\n";
   exit;
}
/* Запись в файл. */
fputs ($file, "$HTTP_USER_AGENT\n");
fclose ($file);
?>

Заметьте, что запись в конец FTP-файла не поддерживается, так как файл не должен существовать, а должен создаваться. Если для FTP-доступа необходим пароль, то его можно указывать в строке адреса в виде ftp://user:password@ftp. example.com/path/file.

Такую же форму ввода пароля можно использовать и для протокола HTTP, когда требуется аутентификация типа Basic.

См. также fclose(), fsockopen(), socket_set_timeout() и popen().

fclose. Закрытие дескриптора файла

int fclose (int fp)

Функция закрывает ранее открытый файл. Дескриптор файла fp должен быть возвращен при успешном открытии файла функцией fopen() или fsockopen().

popen. Открытие дескриптора вывода процесса

int popen (string command, string mode)

Функция запускает процесс приложения command и возвращает дескриптор потока ввода/вывода в режиме mode. При ошибке возвращается значение FALSE. Дескриптор может в дальнейшем использоваться функциями fgets(), fgetss(), и fputs(). Вызов функции выглядит достаточно просто:

$fp = popen ("/bin/ls", "r")

См. также pclose().

pclose. Закрытие дескриптора процесса

int pclose (int fp)

Закрывает дескриптор процесса, который был предварительно создан функцией popen(). Функция возвращает код завершения процесса.

См. также popen().

fstat. Получение информации о файле через дескриптор

array fstat (int fp)

Функция возвращает массив с информацией о файле, как и функция stat(), но в отличие от нее эта функция принимает в качестве аргумента дескриптор успешно открытого файла, а не его имя.

fgetc. Чтение символа из файла

string fgetc (int fp)

Функция возвращает строку, содержащую один символ из файла с дескриптором fp. Если получен символ EOF (указатель конца файла), то возвращается значение FALSE.

См. также fread(), fopen(), popen(), fsockopen() и fgets().

fgets. Чтение строки из файла

string fgets (int fp, int length)

Функция возвращает строку из файла с дескриптором fp. Длина возвращаемой строки задается аргументом length. Если в строке встречается символ EOF eee \n, то возвращаются все символы до него. При ошибке возвращается значение FALSE.

Пример использования функции приведен в листинге 4.13.

Листинг 4.13
$fd = fopen ("/tmp/inputfile.txt", "r");
while (!feof ($fd)) {
   $buffer = fgets($fd, 4096);
   echo $buffer;
}
fclose ($fd);

См. также fread(), fopen(), popen(), fgetc(), fsockopen() и socket_set_timeout().

fgetss. Чтение строки из файла и удаление из нее HTML-тегов

string fgetss (int fp, int length [, string allowable_tags])

Функция идентична fgets(), за исключением того, что она также удаляет любые теги HTML и PHP из получаемого текста. В аргументе allowable_tags можно указать, какие теги не следует удалять.

См. также fgets(), fopen(), fsockopen(), popen() и strip_tags().

fgetcsv. Чтение строки файла и разделение ее на поля CSV

array fgetcsv (int fp, int length [, string delimiter])

Функция сходна с fgets(), но после чтения она разделяет полученную строку на поля согласно формату CSV и возвращает их в качестве элементов массива. Разделителем полей считается запятая либо другой символ, который можно указать в аргументе delimiter.

Аргумент fp должен быть дескриптором успешно открытого файла. Аргумент length должен быть больше, чем самая длинная строка CSV-файла, включая завершающие символы строки.

Функция возвращает значение FALSE при ошибке, которой также считается непредвиденный конец файла. Часто в CSV-файлах признаком конца файла считается пустая строка, которая будет возвращена в виде массива, содержащего один нулевой элемент.

Пример использования функции приведен в листинге 4.14.

Листинг 4.14
$row = 1;
$fp = fopen ("test.csv","r");
while ($data = fgetcsv ($fp, 1000, ",")) {
   $num = count ($data);
   print "<p> $num fields in line $row: <br>";
   $row++;
   for ($c=0; $c<$num; $c++) {
      print $data[$c] . "<br>";
   }
}
fclose ($fp);

file. Чтение всего файла в массив

array file (string filename [, int use_include_path])

Функция идентична readfile(), но строки файла возвращаются в массиве. Концом строки считается символ \n, который тоже возвращается.

Можно указать необязательный аргумент use_include_path с единичным значением, и тогда функция будет искать файл не только в текущей директории, но и в директории для подключаемых файлов.

Пример использования функции приведен в листинге 4.15.

Листинг 4.15
<?php
// прочитать веб-страницу в массив и распечатать
$fcontents = file ('http://www.php.net');
while (list ($line_num, $line) = each ($fcontents)) {
   echo "<b>Line $line_num:</b> " . 
      htmlspecialchars ($line) . "<br>\n";
}
// прочитать в одну строку
$fcontents = join ('', file ('http://www.php.net'));
?>

См. также readfile(), fopen(), fsockopen() и popen().

fread. Чтение файла

string fread (int fp, int length)

Функция возвращает строку, представляющую собой последовательность байтов длиной length, из файла с дескриптором fp. Чтение данных будет прекращено, если будет встречен символ EOF.

Пример использования функции приведен в листинге 4.16.

Листинг 4.16
$filename = "/usr/local/something.txt";
$fd = fopen ($filename, "r");
$contents = fread ($fd, filesize ($filename));
fclose ($fd);

См. также fwrite(), fopen(), fsockopen(), popen(), fgets(), fgetss(), fscanf(), file() fpassthru().

readfile. Вывод файла

int readfile (string filename [, int use_include_path])

Функция выполняет последовательно несколько операций. Она открывает файл, читает содержимое файла, выводит его в стандартный поток вывода и закрывает файл. Режим открытия файла не указывается.

Отличие этой функции от директив include() и require() заключается в том, что она возвращает количество выведенных байтов или значение FALSE при возникновении ошибки. В случае возникновения ошибки также выводится стандартное уведомление, если при вызове функции сообщения об ошибках не были заблокированы.

См. также fpassthru(), file(), fopen(), include(), require() и virtual().

fpassthru. Вывод содержимого файла

int fpassthru (int fp)

Функция читает содержимое файла с дескриптором до тех пор, пока не встретится символ EOF, и выводит содержимое в стандартный поток вывода. При ошибке возвращается значение FALSE.

Дескриптор должен быть возвращен при успешном открытии файла функцией fopen(), popen() или fsockopen(). После вывода файл автоматически закрывается, и дескриптор становится недействителен. Для простого чтения и вывода содержимого файла стоит использовать функцию readfile().

См. также readfile(), fopen(), popen() и fsockopen().

fscanf. Форматированный ввод из файла

mixed fscanf (int handle, string format [, string var1...])

Функция аналогична sscanf(), но она читает данные из файла и интерпретирует их согласно формату, который указан в аргументе format. Если в функции указываются только два аргумента, то извлеченные данные возвращаются в виде массива. В противном случае необходимо указывать ссылки на переменные, в которых следует сохранить значения, и тогда функция возвращает количество инициализированных переменных.

Пример использования функции приведен в листинге 4.17.

Листинг 4.17
$fp = fopen ("users.txt","r");
while ($userinfo = fscanf ($fp, "%s\t%s\t%s\n")) {
   list ($name, $profession, $countrycode) = $userinfo;
   //... делаем что-то со значениями
}
fclose($fp);

Содержимое файла users.txt приведено ниже:

javier  argonaut   pe
hiroshi sculptor   jp
robert  slacker    us

См. также fread(), fgets(), fgetss(), sscanf(), printf() и sprintf().

fwrite. Запись в файл

int fwrite (int fp, string string [, int length])

Функция записывает содержимое строки string в файловый поток, на который указывает дескриптор fp. При указании аргумента length производится запись только указанного количества байтов, но не больше, чем содержится в строке. Также игнорируется опция конфигурации magic_quotes_runtime, и слеши не исключаются из записываемой строки.

См. также fread(), fopen(), fsockopen(), popen() и fputs().

fputs. Синоним функции fwrite

int fputs (int fp, string str [, int length])

Аргумент длины записываемой строки length может не указываться, и тогда строка str записывается в файл целиком.

fflush. Запись стандартного вывода в файл

int fflush (int fp)

Весь буферизированный вывод записывается в открытый файл, на который указывает дескриптор fp.

feof. Проверка достижения конца файла

int feof (int fp)

Функция возвращает значение TRUE, если курсор файла указывает на символ EOF или возникает ошибка. В ином случае возвращается значение FALSE.

Аргумент fp должен быть дескриптором успешно открытого файла.

ftell. Проверка позиции курсора файла

int ftell (int fp)

Функция возвращает позицию курсора файла, на который указывает дескриптор fp. Курсор указывает смещение от начала файлового потока, позицию, в которую производится запись или с которой осуществляется чтение. При ошибке возвращается значение FALSE.

Аргумент fp должен быть дескриптором успешно открытого файла.

См. также fopen(), popen(), fseek() и rewind().

fseek. Установка позиции курсора файла

int fseek (int fp, int offset [, int whence])

Функция позволяет перемещать внутренний курсор файла. Новая позиция курсора файла указывается аргументом offset и измеряется в байтах от места, заданного аргументом whence, значения которого перечислены в следующем списке:

Если аргумент whence не указывается, то смещение вычисляется от начала файла. При ошибке возвращается значение –1, в ином случае возвращается нулевое значение. Следует помнить, что указание смещения, выводящее курсор за символ EOF, не считается ошибкой.

Дескриптор файла fp должен быть возвращен успешным вызовом функции fopen(). С файлами, открытыми через протокол HTTP или FTP, функция не работает.

См. также ftell() и rewind().

rewind. Установка курсора на начало файлового потока

int rewind (int fp)

Функция эквивалентна вызову fseek(fp, 0). При ошибке возвращается нулевое значение.

См. также fseek() и ftell().

Работа с архивами Zlib

Модуль zlib, который можно найти на веб-странице по адресу: http://www.info-zip.org/pub/infozip/zlib, позволяет производить операции файлового ввода-вывода в файлах, которые были сжаты при помощи метода gzip. В этом модуле PHP используется библиотека zlib версии 1.0.9. Модуль содержит большую часть родственных функций файловой системы (с префиксом gz), которые могут работать как с обычными, так и с архивными файлами, но не с сокетами.

Для текущей версии PHP поддержка этих функций должна быть косвенно включена в обычные функции файловой системы. Таким образом, при подключении модуля zlib файловые функции могут работать с архивными файлами, как и с FTP- файлами. Для этого в строке имени файла нужно указывать специальный префикс zlib:, подобно указанию URL для доступа к FTP-файлам. Пример использования функций из этого пакета приведен в листинге 4.18.

Листинг 4.18
<?php
$filename='C:\ZZZ.gz';
// открыть файл для записи с максимальным сжатием 
$zp = gzopen($filename, "w9");
// записать строку в файл 
$s = "Only a test, test, test, test, test, test, test, test!\n";
gzwrite($zp, $s);
gzclose($zp); // закрыть файл 
$zp = gzopen($filename, "r");  
print gzread($zp, 3);   // прочитать 3 символа 
gzpassthru($zp); // выводить содержимое до конца файла и закрыть его
// еще раз вывести содержимое файла
if (readgzfile($filename) != strlen($s)) {
   echo "Error with zlib functions!";
}
?>

gzcompress. Сжатие строки методом Gz

string gzcompress (string data [, int level])

Функция возвращает сжатую строку. При помощи аргумента level можно указать степень сжатия. Это значение может находиться в интервале от 0 до 9.

См. также gzuncompress().

gzuncompress. Распаковка gz-сжатой строки

string gzuncompress (string data [, int length])

Функция возвращает оригинальную строку данных, сжатую ранее функцией gzcompress(). В случае возникновения ошибки возвращается значение FALSE. Ошибка может возникнуть, если при распаковке размер строки увеличивается более чем в 256 раз или становится больше, чем указано в необязательном аргументе length.

См. также gzcompress().

readgzfile. Вывод gz-файла

int readgzfile (string filename [, int use_include_path])

Функция читает файл filename, распаковывает его и выводит в стандартный поток вывода. Функция может также работать с обычными файлами, но тогда распаковка не производится.

Функция возвращает количество выведенных байтов или FALSE в случае возникновения ошибки. В случае ошибки также выводится сообщение об ошибке, если вывод сообщений не был заблокирован.

Необязательный аргумент include_path можно использовать с единичным значением, чтобы поиск файла также производился в директориях, заданных опцией include_path.

См. также gzpassthru(), gzfile() и gzopen().

gzfile. Чтение всего gz-файла в массив

array gzfile (string filename [, int use_include_path])

Функция аналогична readgzfile(), но распакованные данные не выводятся, а возвращаются в массиве.

См. также readgzfile() и gzopen().

gzopen. Открытие gz-файла

int gzopen (string filename, string mode [, int use_include_path])

Функция сходна с fopen(), но она работает с файлами gzip (.gz). Аргумент mode может принимать значения, как в функции fopen(). Помимо этого в режиме может указываться цифра, задающая степень используемого сжатия, например wb9. Также может использоваться значение f для фильтруемых данных, например wb6f, и значение h для компрессии Хаффмана (wb1h).

Функция также может использоваться для открытия обычного файла, но в этом случае gzread() будет читать данные файла без декомпрессии.

Функция возвращает дескриптор открытого файла или значение FALSE при возникновении ошибки. Используя полученный дескриптор, можно осуществлять операции ввода-вывода, и тогда сжатие и распаковка данных будут осуществляться автоматически.

Необязательный аргумент include_path можно использовать с единичным значением, чтобы поиск файла также производился в директориях, установленных опцией include_path.

Вызов функции выглядит достаточно просто:

$fp = gzopen ("/tmp/file.gz", "r")

См. также gzclose().

gzclose. Закрытие gz-файла

int gzclose (int zp)

Функция закрывает gz-файл, дескриптор которого zp ранее был успешно возвращен функцией gzopen().

gzread. Чтение последовательности символов из gz-файла

string gzread (int zp, int length)

Функция читает данные из файла. Количество читаемых байтов указывается аргументом length. Дескриптор zp должен быть ранее успешно возвращен функцией gzopen(). Чтение прекращается, когда будет прочитано length распакованных байтов, или если будет обнаружен символ конца файла EOF.

Пример использования функции приведен в листинге 4.19.

Листинг 4.19
$filename = "/usr/local/something.txt.gz";
$zd = gzopen ($filename, "r");
$contents = gzread ($zd, 10000);
gzclose ($zd);

См. также gzwrite(), gzopen(), gzgets(), gzgetss(), gzfile() и gzpassthru().

gzgetc. Чтение символа из gz-файла

string gzgetc (int zp)

Функция возвращает строку, содержащую единственный распакованный символ файла, имеющего дескриптор zp. Если встречается символ EOF, то возвращается значение FALSE.

Дескриптор zp должен быть ранее успешно возвращен функцией gzopen().

См. также gzopen() и gzgets().

gzgets. Чтение строки

string gzgets (int zp, int length)

Функция возвращает распакованную строку gz-файла, имеющего дескриптор zp.

Чтение прекращается, когда будет прочитано length-1 распакованных байтов, или если будет обнаружен символ конца файла EOF, или если встретится символ конца строки. При ошибке возвращается значение FALSE.

См. также gzopen(), gzgetc(), и fgets().

gzgetss. Аналог gzgets, удаляющий теги HTML и PHP из текста

string gzgetss (int zp, int length [, string allowable_tags])

В необязательном аргументе allowable_tags можно указать, какие теги не следует удалять.

См. также gzgets(), gzopen() и strip_tags().

gzpassthru. Вывод всего содержимого gz-файла до его конца

int gzpassthru (int zp)

Функция распаковывает и читает gz-файл с дескриптором zp от текущей позиции курсора и до конца файла, после чего полученное содержимое перенаправляется в стандартный поток вывода. При ошибке возвращается значение FALSE.

После вывода файл закрывается, для чего неявно вызывается функция gzclose().

gzwrite. Запись строки в gz-файл

int gzwrite (int zp, string string [, int length])

Функция упаковывает и записывает содержимое строки string в gz-файл с дескриптором zp. Если указан аргумент length, то запись прекращается после того, как будет записано length неупакованных байтов.

Если указывается аргумент length, то опция magic_quotes_runtime игнорируется и слеши не удаляются из строки string.

См. также gzread(), gzopen() и gzputs().

gzeof. Проверка наличия символа конца файла

int gzeof (int zp)

Функция возвращает значение TRUE, если текущий символ gz-файла является символом EOF или если при операции чтения произошла ошибка. В ином случае возвращается значение FALSE.

gztell. Определение позиции курсора gz-файла

int gztell (int zp)

Функция возвращает позицию, в которую будет осуществляться запись или чтение. При ошибке возвращается значение FALSE.

См. также gzopen(), gzseek() и gzrewind().

gzseek. Перемещение курсора gz-файла

int gzseek (int zp, int offset)

Функция передвигает курсор файла на количество байтов от его начала, которое указывает параметр offset.

Если файл открыт для чтения, то функция эмулируется, и она будет выполняться крайне медленно, потому что в сжатых файлах смещение нужно вычислять. Если файл открыт для записи, то курсор можно сдвигать только вперед, и тогда в файл просто записывается последовательность нулей, вплоть до новой позиции.

В случае успешного выполнения функция возвращает нулевое значение. При возникновении ошибки возвращается значение –1. Перемещение курсора после символа EOF не считается ошибкой.

См. также gztell() и gzrewind().

gzrewind. Перемещение курсора в начало gz-файла

int gzrewind (int zp)

Функция устанавливает курсор в начало файла. При ошибке возвращается нулевое значение.

См. также gzseek() и gztell().

Сжатые файлы Bzip2

Модуль bzip2 использует библиотеку, написанную Джулианом Севардом (Julian Seward), позволяющую проводить операции файлового ввода-вывода из архивов bzip2 (.bz2). Найти ее можно по адресу: sources.redhat.com/bzip2.

Чтобы использовать функции bzip2 в PHP, надо при компиляции указать дополнительную опцию --with-bz2[=DIR]. Для этого требуется библиотека bzip2/libbzip2 версии старше, чем 1.0. Этот модуль можно также подключить динамически. Модуль разработан недавно, поэтому он может работать нестабильно. Пример использования функции приведен в листинге 4.20.

Листинг 4.20
<?php
$filename = "/tmp/testfile.bz2";
$str = "This is a test string.\n";
$bz = bzopen($filename, "w");
bzwrite($bz, $str);
bzclose($bz);
$bz = bzopen($filename, "r");
echo print bzread($bz, 10), bzread($bz);
bzclose($bz);
?>

bzcompress. Сжатие строки методом bzip2

string bzcompress (string source [, int blocksize [, int workfactor]])

Функция сжимает строку, указанную в аргументе source. В необязательном аргументе blocksize можно указать уровень сжатия от 1 до 9, где значение 9 соответствует максимальному сжатию, требующему максимума ресурсов. По умолчанию используется четвертый уровень.

Аргумент workfactor управляет сжатием данных с высокой частотностью. Возможные значения лежат в интервале от 0 до 250. По умолчанию используется значение 30.

Пример вызова этой функции приведен в листинге 4.21.

Листинг 4.21
$str = "sample data";
$bzstr = bzcompress($str, 9);
print($bzstr);

См. также bzdecompress().

bzdecompress. Распаковка строки, сжатой методом bzip2

string bzdecompress (string source [, int small])

Функция распаковывает строку source, содержимое которой ранее было сжато методом bzip2, после чего возвращает полученную строку. Если в необязательном аргументе указывается значение TRUE, то используется алгоритм, потребляющий минимальный объем памяти, но при этом функция работает значительно медленнее.

Пример вызова этой функции приведен в листинге 4.22.

Листинг 4.22
<?php
$start_str = "Это первоначальная несжатая строка";
$bzstr = bzcompress($start_str);
print( "Compressed String: $bzstr \n<br>" );
$str = bzdecompress($bzstr);
print( "Decompressed String: " . $str . "\n<br>" );
?>

См. также bzcompress().

bzopen. Открытие сжатого файла bzip2

int bzopen (string filename, string mode)

Функция возвращает дескриптор открытого файла или значение FALSE в случае возникновения ошибки. Аргумент mode принимает те же значения, что и в функции fopen(). Пример вызова этой функции приведен в листинге 4.23.

Листинг 4.23
<?php
$bz = bzopen("/tmp/foo.bz2", "r");
$decompressed_file = bzread($bz, filesize("/tmp/foo.bz2"));
bzclose($bz);
print( "The contents of /tmp/foo.bz2 are: " );
print( "\n<br>n" );
print( $decompressed_file );
?>

См. также bzclose().

bzclose. Закрытие файла bzip2

int bzclose (int bz)

Функция закрывает файл bzip2 с дескриптором bz. В случае успеха возвращается значение TRUE. При возникновении ошибки возвращается значение FALSE.

См. также bzopen().

bzread. Чтение из файла bzip2

string bzread (int bz [, int length])

Функция читает данные из файла с дескриптором bz. Количество читаемых байтов можно указать аргументом length. Если он не указывается, то читается 1024 байта. Чтение прекращается, когда будет прочитано length распакованных байтов, или если будет обнаружен символ конца файла EOF.

Пример использования этой функции приведен в листинге 4.24.

Листинг 4.24
<?php
$bz = bzopen("/tmp/foo.bz2", "r");
$str = bzread($bz, 2048);
print( $str );
?>

См. также bzwrite() и bzopen().

bzwrite. Запись в файл bzip2 данных

int bzwrite (int bz, string data [, int length])

В аргументе data указывается строка, содержащая записываемые данные. В аргументе bz указывается дескриптор открытого файла bzip2. Если указан аргумент length, то запись прекращается после того, как будет записано length неупакованных байт. Пример использования этой функции приведен в листинге 4.25.

Листинг 4.25
<?php
$str = "uncompressed data";
$bz = bzopen("/tmp/foo.bz2", "w");
bzwrite($bz, $str, strlen($str));
bzclose($bz);
?>

См. также bzread() и bzopen().

bzflush. Запись всего буферизированного вывода в файл bzip2

int bzflush (int bz)

В аргументе bz указывается дескриптор открытого файла. Потом в него записывается вся информация, подготовленная для вывода.

См. также bzread() и bzwrite().

bzerrno. Получение номера ошибки bzip2

int bzerrno (int bz)

В аргументе bz указывается дескриптор открытого файла, при операции с которым произошла ошибка. Возвращается код ошибки.

См. также bzerror() и bzerrstr().

bzerrstr. Получение описания ошибки bzip2

string bzerrstr (int bz)

В аргументе bz указывается дескриптор открытого файла, при операции с которым произошла ошибка. Функция возвращает описание ошибки.

См. также bzerrno() и bzerror().

bzerror. Получение номера и описания ошибки bzip2 в массиве

array bzerror (int bz)

Функция возвращает ассоциативный массив, содержащий два элемента. В одном указывается код ошибки, а в другом — описание ошибки. В аргументе bz указывается дескриптор открытого файла, при операции с которым произошла ошибка. Пример использования этой функции приведен в листинге 4.26.

Листинг 4.26
$error = bzerror($bz);
echo $error["errno"];
echo $error["errstr"];

См. также bzerrno() и bzerrstr().

FTP

При использовании модуля FTP им определяются две константы: FTP_ASCII и FTP_ BINARY. Функции используют дескриптор сеанса подключения, обозначенный как ftp_stream.

Простейший код, реализующий сеанс FTP, приведен в листинге 4.27.

Листинг 4.27
<?php
// открытие простого FTP сеанса
$conn_id = ftp_connect("$ftp_server"); 
// login with username and password
$login_result = ftp_login($conn_id, "$ftp_user_name", "$ftp_user_pass"); 
// проверка связи
if ((!$conn_id) || (!$login_result)) { 
   echo "Невозможно установить Ftp связь! ",
         "К серверу $ftp_server, пользователи $user"; 
   die; 
   }
else {
   echo "Подключение к серверу $ftp_server успешно!";
   }
// загрузить файл 
$upload = ftp_put($conn_id, "$destination_file", 
                     "$source_file", FTP_BINARY); 
// проверка загрузки
if (!$upload) { 
   echo "Загрузка не удалась!";
   }
else {
   echo "Файл $source_file был загружен как $destination_file";
   }
// закрыть поток FTP 
ftp_quit($conn_id);
?>

ftp_connect . Подключение к FTP-серверу

int ftp_connect (string host [, int port])

Функция создает подключение к FTP-серверу. Аргумент host указывает имя сервера, к которому осуществляется доступ, а port — используемый для подключения порт. Если порт не указан или задано нулевое значение, то используется порт 21.

Функция возвращает дескриптор потока FTP или значение FALSE при ошибке.

ftp_pasv. Переключение пассивного режима

int ftp_pasv (int ftp_stream, int pasv)

Функция переключает режим подключения в пассивный, если аргумент pasv равен TRUE. Если аргумент pasv равен FALSE, то подключение переходит в активный режим. В пассивном режиме передача данных инициируется клиентом, а не сервером.

ftp_login. Вход на сервер FTP

int ftp_login (int ftp_stream, string username, string password)

Функция позволяет передать в подключение логин username и пароль password.

ftp_quit. Завершение сеанса FTP

int ftp_quit (int ftp_stream)

Функция завершает сеанс работы с сервером FTP.

ftp_pwd. Текущая директория

string ftp_pwd (int ftp_stream)

Функция возвращает текущую директорию FTP-сервера или значение FALSE при возникновении ошибки.

ftp_cdup. Переход в корневую директорию

int ftp_cdup (int ftp_stream)

Функция пытается сделать текущей директорией корневую директорию сервера. В случае успеха возвращается значение TRUE. При возникновении ошибки возвращается значение FALSE.

ftp_chdir. Переход в директорию

int ftp_chdir (int ftp_stream, string directory)

Функция пытается сделать текущей директорией именно ту, имя которой передано в параметре directory. В случае успеха возвращается значение TRUE. При возникновении ошибки возвращается значение FALSE.

ftp_mkdir. Создание директории

string ftp_mkdir (int ftp_stream, string directory)

Функция возвращает имя созданной директории directory или значение FALSE при возникновении ошибки.

ftp_rmdir. Удаление директории

int ftp_rmdir (int ftp_stream, string directory)

Функция удаляет указанную директорию. В случае успеха возвращается значение TRUE. При возникновении ошибки возвращается значение FALSE.

ftp_nlist. Получение списка файлов директории

array ftp_nlist (int ftp_stream, string directory)

Функция возвращает массив с именами файлов указанной директории или значение FALSE при возникновении ошибки.

ftp_rawlist. Детализированный листинг директории

array ftp_rawlist (int ftp_stream, string directory)

Функция выполняет команду LIST и возвращает ее результат в массиве, где каждый элемент соответствует строке текста “как есть”. Идентификатор типа системы, возвращаемый ftp_systype(), может быть использован для определения того, как следует интерпретировать результаты.

ftp_systype. Получение системного идентификатора типа FTP- сервера

string ftp_systype (int ftp_stream)

Функция возвращает строковое значение или значение FALSE при возникновении ошибки.

ftp_get. Загрузка файла с FTP

int ftp_get (int ftp_stream, string local_file, string remote_file, int mode)

Функция загружает удаленный файл remote_file с сервера FTP и сохраняет его локально под именем local_file. Режим передачи mode должен быть указан либо как FTP_ASCII, либо как FTP_BINARY. В случае успеха возвращается значение TRUE. При возникновении ошибки возвращается значение FALSE.

ftp_fgetftp_fget. Загрузка и запись файла

int ftp_fget (int ftp_stream, int fp, string remote_file, int mode)

Функция загружает удаленный файл remote_file с сервера FTP и сохраняет его содержимое в открытом файле, имеющем дескриптор fp. Режим передачи mode должен быть указан либо как FTP_ASCII, либо как FTP_BINARY. В случае успеха возвращается значение TRUE. При возникновении ошибки возвращается значение FALSE.

ftp_put. Загрузка файла на сервер FTP

int ftp_put (int ftp_stream, string remote_file, string local_file, int mode)

Функция сохраняет файл local_file на FTP-сервере под именем remote_file. Режим передачи mode должен быть указан либо как FTP_ASCII, либо как FTP_BINARY. В случае успеха возвращается значение TRUE. При возникновении ошибки возвращается значение FALSE. Вызов функции выглядит достаточно просто:

$upload = ftp_put ($conn_id, "C:\\myfile.txt", "/myfile.txt", FTP_ASCII)

ftp_fput. Чтение и загрузка файла на сервер

int ftp_fput (int ftp_stream, string remote_file, int fp, int mode)

Функция читает открытый файл с дескриптором fp до его конца и загружает его на сервер FTP под именем remote_file. Режим передачи mode должен быть указан либо как FTP_ASCII, либо как FTP_BINARY. В случае успеха возвращается значение TRUE. При возникновении ошибки возвращается значение FALSE.

ftp_size. Определение размера файла

int ftp_size (int ftp_stream, string remote_file)

Функция возвращает размер файла в байтах или значение –1 при возникновении ошибки. Но не все серверы поддерживают эту возможность.

ftp_mdtm. Получение времени последней модификации файла

int ftp_mdtm (int ftp_stream, string remote_file)

Функция возвращает время последней модификации файла в формате “UNIX timestamp” или значение –1 при возникновении ошибки. Функция не работает с директориями.

ftp_rename. Переименование файла на сервере

int ftp_rename (int ftp_stream, string from, string to)

Функция переименовывает файл from в to. В случае успеха возвращается значение TRUE. При возникновении ошибки возвращается значение FALSE.

ftp_delete. Удаление файла на сервере

int ftp_delete (int ftp_stream, string path)

Функция удаляет на сервере файл с указанным именем. В случае успеха возвращается значение TRUE. При возникновении ошибки возвращается значение FALSE.

ftp_site. Выполнение команды SITE на сервере

int ftp_site (int ftp_stream, string cmd)

Функция посылает серверу команду cmd. В случае успеха возвращается значение TRUE. При возникновении ошибки возвращается значение FALSE. Команды SITE не стандартизированы, поэтому они могут различаться. Обычно они используются для изменения прав доступа к файлам и групповой принадлежности.

Сетевые функции

ip2long. Конвертация строки адреса IPv4 в число

int ip2long (string ip_address)

Функция возвращает четырехбайтовое численное представление адреса IPv4 из строки. Пример использования функции приведен в листинге 4.28.

Листинг 4.28
$ip = gethostbyname("www.php.net");  // получить IP адрес хоста
echo "Следующие URL эквивалентны:<br>\n",
   "http://www.php.net/, http://" .$ip. 
   "/, e http://" .ip2long($ip)."/<br>\n";

См. также long2ip().

long2ip. Конвертация числа в строку адреса IPv4

string long2ip (int proper_address)

Функция возвращает строковое представление IP-адреса в виде четырех чисел, разделенных точкой, из числового значения.

См. также ip2long().

gethostbyaddr. Получение имени хоста соответствующего адресу IP

string gethostbyaddr (string ip_address)

В аргументе функции указывается IP-адрес в строковом формате. Функция возвращает доменное имя, связанное с этим адресом. При ошибке возвращается ip_address. Но следует помнить, что большинству IP-адресов в Интернете соответствует несколько имен. Вызов функции достаточно прост:

echo gethostbyaddr("127.0.0.1")

См. также gethostbyname().

gethostbyname. Получение IP-адреса хоста

string gethostbyname (string hostname)

Функция возвращает строковое представление IP-адреса, который соответствует доменному имени, переданному в качестве параметра. Вызов функции достаточно прост:

print gethostbyname ("localhost"); // выведет: 127.0.0.1

См. также gethostbyaddr().

gethostbynamel. Получение списка IP-адресов, принадлежащих хосту

array gethostbynamel (string hostname)

Функция используется вместо gethostbyname(), когда хост hostname имеет несколько сетевых интерфейсов с разными адресами.

См. также gethostbyname(), gethostbyaddr(), checkdnsrr(), getmxrr().

getprotobyname. Определение номера порта, используемого протоколом

int getprotobyname (string name)

Функция возвращает номер используемого порта.

См. также getprotobynumber().

getprotobynumber. Определение протокола порта

string getprotobynumber (int number)

Функция возвращает строку с наименованием используемого протокола порта, номер которого передается в качестве параметра.

См. также getprotobyname().

getservbyname. Определение порта Интернет-службы

int getservbyname (string service, string protocol)

Функция возвращает номер порта, использующийся службой service. В системах UNIX это соответствие портов и служб указывается в файле /etc/services. В аргументе protocol указывается тип протокола TCP или UDP. Вызов функции достаточно прост:

echo getservbyname ("HTTP","TCP");  // может вывести: 80

См. также getservbyport().

getservbyport. Определение Интернет-службы, использующей порт

string getservbyport (int port, string protocol)

В аргументе protocol указывается тип протокола TCP или UDP. Функция возвращает имя службы, которая работает на указанном порту. Пример использования функции приведен в листинге 4.29.

Листинг 4.29
echo getservbyport(21,"TCP");	  // обычно выводит: ftp
echo getservbyport(23,"TCP");   // обычно выводит: telnet

См. также getservbyname().

checkdnsrr. Проверка записи DNS

int checkdnsrr (string host [, string type])

Функция отправляет запрос DNS-серверу для поиска записей хоста host. Возвращается значение TRUE, если были найдены записи типа type. В ином случае возвращается значение FALSE.

Аргумент type может иметь значение A, MX, NS, SOA, PTR, CNAME, ANY. По умолчанию используется значение MX.

Аргумент host может содержать IP-адрес с разделением точками или имя хоста.

См. также getmxrr(), gethostbyaddr(), gethostbyname(), gethostbynamel().

getmxrr. Получение MX-записи для Интернет-хоста

int getmxrr (string hostname, array mxhosts [, array weight])

Функция инициирует поиск в DNS-сервере записи MX, которая отвечает за почтовый сервер домена, для хоста hostname. Функция возвращает значение TRUE, если запись найдена. В ином случае возвращается значение FALSE.

Список записей MX заносится в массив mxhosts. Если указан массив weight, то он заполняется дополнительной информацией о записях.

См. также checkdnsrr(), gethostbyname(), gethostbynamel(), gethostbyaddr().

Сетевая отладка PHP

debugger_on . Разрешение использования внутреннего отладчика PHP

int debugger_on (string address)

Функция подключает отладчик на удаленном сервере по адресу address. Отладчик пока находится в стадии разработки, но он доступен для PHP версии 3.

define_syslog_variables . Инициализация константы диспетчера системных событий

void define_syslog_varaibles (void)

Функция инициализирует константы диспетчера системных событий. Эти константы в дальнейшем используются функциями системных событий.

См. также openlog(), syslog() и closelog().

openlog. Подключение к диспетчеру системных событий

int openlog (string ident, int option, int facility)

Функцию не обязательно вызывать явно. Она автоматически вызывается функцией syslog(), и в этом случае аргумент ident используется со значением FALSE. Строка ident будет добавляться к каждому отсылаемому сообщению. Обычно функция используется при необходимости явной передачи аргументов option и facility.

Аргумент option используется для указания параметров при генерации системного события. Возможные значения этого параметра указаны в следующем списке:

Возможно одновременное указание нескольких значений при помощи битового оператора ИЛИ, например LOG_CONS | LOG_NDELAY | LOG_PID.

Аргумент facility задает вид приложения, посылающего сообщение. Это влияет на их обработку системой. Возможные значения этого параметра указаны в следующем списке:

См. также define_syslog_variables(), syslog() и closelog().

closelog. Отключение от диспетчера системных событий

int closelog(void);

Функция позволяет отключиться от диспетчера системных событий. Но обычно ее не вызывают явно.

См. также define_syslog_variables(), syslog() и openlog().

syslog. Посылка системного сообщения

int syslog (int priority, string message)

В аргументе message указывается содержание сообщения. Cимволы %m в этом сообщении заменяются на строку текущего сообщения об ошибке, расшифровывающую значение errno. Аргумент priority является комбинацией уровня приложения и приоритета события. Его возможные значения перечислены в следующем списке в порядке понижения приоритета:

Пример использования этой функции для посылки сообщения приведен в листинге 4.30.

Листинг 4.30
define_syslog_variables();
openlog("myScripLog", LOG_PID | LOG_PERROR, LOG_LOCAL0);
// ... 
if (!authorized_client()) { // процедура авторизации
   // неавторизирован! (сохранить сообщение об этом объекте)
   $access = date("Y/m/d H:i:s");
   syslog(LOG_WARNING,"Unauthorized client: $access 
            $REMOTE_ADDR ($HTTP_USER_AGENT)");
}
closelog();

В системной документации должно быть указано, как установить собственный обработчик системных событий.

На системах Windows NT служба syslog эмулируется как Event Log.

См. также define_syslog_variables(), openlog() и closelog().

Общий низкоуровневый сетевой интерфейс

fsockopen. Открытие сокета Internet или домена UNIX

int fsockopen (string [udp://]hostname, int port [, int errno [, string errstr [, double timeout]]])

Функция инициирует подключение к сети Интернет (AF_INET, используя TCP или UDP) или к домену UNIX (AF_UNIX). Для Интернет-доменов открывается сеанс подключения с компьютером hostname через порт port. Значение hostname может быть либо полным доменным именем, либо IP-адресом. Для подключений UDP необходимо явно указывать протокол, например, udp://hostname. Для доменов UNIX параметр hostname может содержать путь к сокету, тогда значение port должно быть нулевым. При помощи необязательного аргумента timeout можно указать допустимый промежуток времени подключения в секундах.

Функция возвращает дескриптор файла, как при открытии локального файла. При возникновении ошибки возвращается FALSE, а после этого устанавливаются системные значения номера и сообщения причины ошибки в аргументы errno и errstr, которые должны передаваться по ссылке. Если возвращается значение FALSE, а аргумент errno равняется нулю, то это означает, что ошибка произошла до вызова функции.

По умолчанию сеанс открывается в эксклюзивном режиме. См. функцию socket_set_blocking().

Пример использования функции приведен в листинге 4.31.

Листинг 4.31
$fp = fsockopen ("www.php.net", 80, &$errno, &$errstr, 30);
if (!$fp) {
   echo "$errstr ($errno)<br>\n";
}
else {
   fputs ($fp, "GET / HTTP/1.0\r\n\r\n");
   while (!feof($fp)) {
      echo fgets ($fp,128);
   }
   fclose ($fp);
}

В листинге 4.32 демонстрируется получение даты и времени от UDP службы daytime (порт 13) на локальной машине.

Листинг 4.32
$fp = fsockopen("udp://127.0.0.1", 13, &$errno, &$errstr);
if (!$fp) {
   echo "ERROR: $errno - $errstr<br>\n";
}
else {
   fwrite($fp,"\n");
   echo fread($fp, 26);
   fclose($fp);
}

См. также pfsockopen(), socket_set_blocking(), socket_set_timeout(), fgets(), fgetss(), fputs(), fclose() и feof().

pfsockopen. Открытие устойчивого подключения

int pfsockopen (string hostname, int port [, int errno [, string errstr [, int timeout]]])

Функция полностью идентична fsockopen() с той разницей, что подключение не закрывается по окончании работы функции.

socket_get_status . Получение статуса подключения

array socket_get_status (resource socket_get_status)

Функция возвращает в массиве информацию об открытом подключении. В настоящее время возвращаются четыре элемента, перечисленные в следующем списке:

См. также accept_connect(), bind(), connect(), listen() и strerror().

socket_set_timeout . Установка периода timeout для сокета

bool socket_set_timeout (int socket_descriptor, int seconds, int microseconds)

Функция устанавливает для подключения socket_descriptor длительность периода ожидания ответа, которая рассчитывается как сумма аргументов seconds (секунды) и microseconds (микросекунды).

Пример использования функции приведен в листинге 4.33.

Листинг 4.33
$fp = fsockopen("www.php.net", 80);
if(!$fp) {
   echo "Ошибка подключения \n";
}
else {
   fputs($fp,"GET / HTTP/1.0\n\n");
   $start = time();
   socket_set_timeout($fp, 2);
   $res = fread($fp, 2000);
   var_dump(socket_get_status($fp));
   fclose($fp);
   print $res;
}

См. также fsockopen() и fopen().

socket_set_blocking . Установка режима блокирования

int socket_set_blocking (int socket_descriptor, int mode)

Если в аргументе mode указывается значение FALSE, то указанный дескриптором socket_descriptor сокет переводится в неблокируемый режим. Это воздействует на вызовы функций чтения, подобные fgets(), которые исполняются незамедлительно в неблокированном режиме.

Низкоуровневый сетевой интерфейс

Эта группа функций позволяет использовать низкоуровневый сетевой интерфейс и выступать как в качестве сервера, так и в качестве клиента. Для возможности их использования они должны быть разрешены при компиляции дополнительной директивой --enable-sockets. Подразумевается, что разработчик имеет представление о том, как функционирует этот интерфейс на уровне системы.

Наиболее общий сетевой интерфейс предоставляют функции fsockopen() и pfsockopen().

В листинге 4.34 приведен пример, который иллюстрирует реализацию простого сервера, отвечающего на запросы. В листинге надо изменить адрес и порт. Подключиться к этому серверу можно при помощи простого сетевого клиента, например, командой, telnet 192.168.1.53 10000. Конечно, в ней надо указать верные адрес и порт. Все, что будет посылаться на сервер, будет отображаться и возвращаться клиенту обратно. Для прекращения сеанса связи нужно ввести команду quit.

Листинг 4.34
<?php
error_reporting (E_ALL);
/* Позволяет скрипту бесконечно удерживать связь. */
set_time_limit (0);
$address = '192.168.1.53';  /* установите свои значения */
$port = 10000;
if (($sock = socket (AF_INET, SOCK_STREAM, 0)) < 0) {
   echo " Ошибка в socket(): " . strerror ($sock) . "\n";
}
if (($ret = bind ($sock, $address, $port)) < 0) {
   echo "Ошибка в bind(): " . strerror ($ret) . "\n";
}
if (($ret = listen ($sock, 5)) < 0) {
   echo "Ошибка в listen(): " . strerror ($ret) . "\n";
}
do {
   if (($msgsock = accept_connect($sock)) < 0) {
      echo "Ошибка в accept_connect(): " . strerror ($msgsock) . "\n";
      break;
   }
   do {
      $buf = '';
      $ret = read ($msgsock, $buf, 2048);
      if ($ret < 0) {
         echo "Ошибка в read(): " . strerror ($ret) . "\n";
         break 2;
      }
      if ($ret == 0) {
         break 2;
      }
      $buf = trim ($buf);
      if ($buf == 'quit') {
         close ($msgsock);
         break 2;
      }
      $talkback = "Вы ввели '$buf'.\n";
      write ($msgsock, $talkback, strlen ($talkback));
      echo "$buf\n";
   } while (TRUE);
   close ($msgsock);
} while (TRUE);
close ($sock);
?>

Код соответствующего клиентского приложения приведен в листинге 4.35. Это приложение получает страницу через HTTP, отправляет запрос HEAD, выводит ответ и завершается.

Листинг 4.35
<?php
error_reporting (E_ALL);
echo "<h2>TCP/IP Connection</h2>\n";
/* Получить порт службы WWW (iau?ii: 80). */
$service_port = getservbyname ('www', 'tcp');
/* Получить IP адрес хоста. */
$address = gethostbyname ('www.php.net');
/* Создать TCP/IP socket. */
$socket = socket (AF_INET, SOCK_STREAM, 0);
if ($socket < 0) {
   echo "Ошибка в socket(): " . strerror ($socket) . "\n";
}
else {
   "socket создан: " . strerror ($socket) . "\n";
}
echo "Попытка подключиться к '$address' (порт '$service_port') ...";
$result = connect ($socket, $address, $service_port);
if ($result < 0) {
   echo "Ошибка в connect(): ($result) ". strerror($result) ."\n";
}
else {
   echo "OK.\n";
}
$in = "HEAD / HTTP/1.0\r\n\r\n";  // посылаемые данные 
$out = '';                        // буфер для приема данных
echo "Sending HTTP HEAD request...";  // послать запрос заголовка HTTP
write ($socket, $in, strlen ($in));
echo "OK.\n";
echo "Reading response:\n\n";      // принять ответ (заголовок)
while (read ($socket, $out, 2048)) {
   echo $out;
}
echo "Closing socket...";
close ($socket);
echo "OK.\n\n";
?>

socket. Создание сокета

int socket (int domain, int type, int protocol)

Функция создает конечную точку сетевой коммуникации (сокетсокет) и возвращает его дескриптор. При ошибке возвращается отрицательное значение кода ошибки, которое затем может быть передано в функцию strerror() для получения текстового объяснения причины ошибки.

В аргументе domain указывается тип сети, в которой создается сокет. Можно использовать значения AF_INET и AF_UNIX.

Аргумент type указывает тип создаваемого сокета. Можно использовать значение SOCK_STREAM, SOCK_DGRAM, SOCK_SEQPACKET, SOCK_RAW, SOCK_RDM или SOCK_PACKET.

Аргумент protocol определяет используемый протокол передачи данных.

См. также accept_connect(), bind(), connect(), listen(), strerror() и socket_get_ status().

close. Закрытие сокета

bool close (int socket)

Функция закрывает сокет, указанный дескриптором socket. В случае успеха возвращается значение TRUE. При возникновении ошибки возвращается значение FALSE.

Функция не может использоваться с файловыми дескрипторами PHP, она работает только с дескрипторами, которые были созданы функцией: socket() или accept_connect().

См. также bind(), listen(), socket(), socket_get_status() и strerror().

connect. Подключение к сокету

int connect (int socket, string address [, int port])

Функция инициирует подключение, используя дескриптор socket. В случае успеха возвращается нулевое значение. При ошибке возвращается отрицательное значение кода ошибки, которое затем может быть передано в функцию strerror() для получения текстового описания.

Аргумент address должен содержать либо IP-адрес в строковом формате, если сокет принадлежит семейству AF_INET, либо строку пути к сокету в домене UNIX, если он из семейства AF_UNIX.

Аргумент port используется только для сокетов AF_INET и определяет порт удаленной машины, к которому производится подключение.

См. также bind(), listen(), socket(), socket_get_status() и strerror().

bind. Привязка сокета к адресу

int bind (int socket, string address [, int port])

Функция ставит сокет socket в соответствие IP-адресу address. В случае успеха возвращается нулевое значение. При ошибке возвращается отрицательное значение кода ошибки, которое затем может быть передано в функцию strerror() для получения текстового описания.

Аргумент address должен содержать либо IP-адрес в строковом формате, если сокет принадлежит семейству AF_INET, либо строку пути к сокету в домене UNIX, если он из семейства AF_UNIX.

Аргумент port используется только для сокетов AF_INET и определяет порт удаленной машины, к которому производится подключение.

Для подключения в качестве клиента используется функция connect(), и эта же функция позволяет выступать в роли сервера, но для этого дополнительно используются функции accept_connect() и listen().

См. также accept_connect(), connect(), listen(), socket(), socket_get_status() и strerror().

listen. Разрешение приема данных из сокета

int listen (int socket, int backlog)

После того как сокет был создан при помощи функции socket() и привязан к адресу функцией bind(), эта функция позволяет системе ожидать получения данных и перенаправлять их в соответствующий сокет. Аргумент backlog указывает максимальное число входящих и воспринимаемых подключений.

Функция применима только к типам сокетов SOCK_STREAM или SOCK_SEQPACKET.

В случае успеха возвращается нулевое значение. При ошибке возвращается отрицательное значение кода ошибки, которое затем может быть передано в функцию strerror() для получения текстового описания.

См. также accept_connect(), bind(), connect(), socket(), socket_get_status() и strerror().

accept_connect. Прием данных от сокета

int accept_connect (int socket)

После того как сокет был создан при помощи функции socket() и привязан к адресу функцией bind(), эта функция позволяет системе принимать внешние данные из сокета.

Функция возвращает новый дескриптор сокета. При ошибке возвращается отрицательное значение кода ошибки, которое затем может быть передано в функцию strerror() для получения текстового описания. Возвращаемый дескриптор используется исключительно для обмена данными с клиентскими подключениями. Исходный дескриптор тем не менее остается действительным и может использоваться.

При появлении нескольких входящих подключений используется первое из них. При их отсутствии функция будет ожидать их появления. Если сокет был разблокирован функцией socket_set_blocking() или set_nonblock(), то при отсутствии входящих данных функция завершается с соответствующим кодом ошибки.

См. также bind(), connect(), listen(), socket(), socket_get_status() и strerror().

read. Получение данных от сокета

int read (int socket_des, string &buffer, int length)

Функция читает данные из socket_des в буфер &buffer. При этом читается length байтов. Чтение завершается ранее, если встречается символ \n, \t или \0. Функция возвращает количество прочитанных байтов.

См. также accept_connect(), bind(), connect(), listen(), strerror(), socket_get_ status() и write().

write. Запись данных в сокет

int write (int socket_des, string &buffer, int length)

Функция записывает в сокет socket_des содержимое буфера buffer в объеме length байтов.

См. также accept_connect(), bind(), connect(), listen(), read(), strerror() и socket_ get_status().

strerror. Получение описания ошибки сокета

string strerror (int errno)

Принимаемый аргумент errno является значением, возвращаемым одной из функций. Возвращается строка текста, объясняющая код ошибки. Это делает более удобным разбор причин неработоспособности. Пример использования функции приведен в листинге 4.36.

Листинг 4.36
<?php
if (($socket = socket (AF_INET, SOCK_STREAM, 0)) < 0) {
   echo "Причина ошибки в socket(): " . strerror ($socket) . "\n";
}
if (($ret = bind ($socket, '127.0.0.1', 80)) < 0) {
   echo " Причина ошибки в bind(): " . strerror ($ret) . "\n";
}
?>

Если этот код будет исполняться не с административными привилегиями, то, скорее всего, он выведет сообщение Причина ошибки в bind(): Permission denied.

См. также accept_connect(), bind(), connect(), listen(), socket() и socket_get_ status().

Библиотека CURL (Client URL Library)

PHP поддерживает библиотеку libcurl, созданную Даниелем Стенбергом (Daniel Stenberg), позволяющую осуществлять подключение и взаимодействие с различными типами серверов, используя самые разнообразные протоколы. В настоящее время libcurl поддерживает протоколы http, https, ftp, gopher, telnet, dict, file, ldap. Также библиотека поддерживает сертификаты HTTPS, методы HTTP POST и PUT, загрузку с FTP и HTTP, прокси, cookies и аутентификацию пользователя с паролем.

Чтобы использовать функции CURL, необходимо инсталлировать пакет CURL, который можно загрузить со страницы curl.haxx.se. PHP необходима версия CURL 7.0.2-beta или выше. Затем нужно перекомпилировать PHP с дополнительным параметром --with-curl[=DIR], где DIR указывает на расположение директории пакета, содержащей поддиректории lib и include. В директории include должна находиться папка curl, содержащая файлы easy.h и curl.h, а в директории lib должен находиться файл libcurl.a.

Схема использования функций проста. Сначала при помощи функции curl_ init() инициализируется сессия CURL. При этом устанавливаются параметры передачи, с которыми она будет выполнена функцией curl_exec(), после чего сессия может быть завершена при помощи функции curl_close(). В листинге 4.37 приведен пример, получающий домашнюю страницу PHP и сохраняющий ее в файле.

Листинг 4.37
<?php
$ch = curl_init ("http://www.php.net/");
$fp = fopen ("php_homepage.txt", "w");
curl_setopt ($ch, CURLOPT_FILE, $fp);
curl_setopt ($ch, CURLOPT_HEADER, 0);
curl_exec ($ch);
curl_close ($ch);
fclose ($fp);
?>

curl_init. Открытие сеанса CURL

int curl_init ([string url])

Функция инициализирует новую сессию и возвращает дескриптор CURL, который затем будет использоваться функциями curl_setopt(), curl_exec() и curl_close(). В функции можно указать необязательный аргумент url, в дальнейшем используемый как параметр CURLOPT_URL. Впрочем, этот параметр можно также установить функцией curl_setopt().

Пример использования функции приведен в листинге 4.38.

Листинг 4.38
<?php
$ch = curl_init();
curl_setopt ($ch, CURLOPT_URL, "http://www.zend.com/");
curl_setopt ($ch, CURLOPT_HEADER, 0);
curl_exec ($ch);
curl_close ($ch);
?>

См. также curl_close(), curl_setopt().

curl_setopt. Установка параметров передачи CURL

bool curl_setopt (int ch, string option, mixed value)

Функция устанавливает параметр, имеющий имя option, сессии CURL с именем ch, в значение value.

Для возможных значений аргумента option, которые перечислены в следующем списке, соответствующее значение value должно указываться в виде целого числа:

Для следующих возможных значений аргумента option соответствующее значение value должно указываться в строковое значение.

Для следующих возможных значений аргумента option соответствующее значение value должно указываться дескриптором, полученным от функции fopen().

curl_exec. Выполнение CURL-сессии

bool curl_exec (int ch)

Функция выполняет подготовленную сессию. Эта функция должна вызываться после инициализации сессии CURL и после того, как все параметры сессии были установлены.

curl_close. Закрытие сеанса

void curl_close (int ch)

Функция закрывает сессию с освобождением всех ресурсов. Также удаляется дескриптор сессии CURL ch.

curl_version. Получение версии

string curl_version (void);

Функция возвращает строку с указанием текущей версии CURL.

Отправка почты

В этом разделе рассматриваются функции, позволяющие работать с сообщениями электронной почты.

mail. Отправление почтового сообщения

bool mail (string to, string subject, string message [, string additional_headers])

Функция позволяет отослать сообщение электронной почты с темой subject и содержимым message адресату to. Для указания нескольких адресатов в строке to их нужно разделять запятой. Вызов функции выглядит предельно просто:

mail("me@mail.ru", "Моя тема", "Привет \nмне \nот меня");

При указании четвертого строкового аргумента эта строка будет добавляться в конец заголовка, что позволит использовать дополнительные служебные заголовки электронного письма. Если нужно указать несколько заголовков, то их следует разделять символом перехода на новую строку \n.

Пример использования этой функции приведен в листинге 4.39.

Листинг 4.39
mail("nobody@aol.com", "the subject", $message,
      "From: webmaster@$SERVER_NAME\n" .
         "Reply-To: webmaster@$SERVER_NAME\nX-Mailer: PHP/".phpversion());

В листинге 4.40 приведен пример создания комплексных сообщений.

Листинг 4.40
/* получатели */
$recipient .= "Mary <mary@univer.edu>" . ", " ; // заметьте запятую
$recipient .= "admin@php.net";
/* тема сообщения */
$subject = "Привет Всем! С праздничком.";
/* само сообщение */
$message .= "The following email includes a formatted ASCII table\n";
$message .= "Day \t\tMonth \t\tYear\n";
$message .= "3rd \t\tAug \t\t1970\n";
$message .= "17rd\t\tAug \t\t1973\n";
/* можно добавить подпись (signature) */ 
$message .= "--\r\n";
$message .= "* Агент почтовой рассылки *";
/* Дополнительные заголовки */
$headers .= "From: Birthday Reminder <birthday@php.net>\n";
$headers .= "X-Sender: <birthday@php.net>\n"; 
$headers .= "X-Mailer: PHP\n"; // Почтовый агент
$headers .= "X-Priority: 1\n"; // Срочное сообщение!
$headers .= "Return-Path: <birthday@php.net>\n";  
// Путь для возвращения сообщений об ошибках
/* Если необходимо послать мейл в виде текста html mail, 
   то раскомментируйте следующую строку (указывающую тип Mime ) */
// $headers .= "Content-Type: text/html; charset=iso-8859-1\n"; 
$headers .= "cc:birthdayarchive@php.net\n"; // CC to
$headers .= "bcc:birthdaycheck@php.net, birthdaygifts@php.net\n"; 
// BCCs to
/* and now mail it */
mail($recipient, $subject, $message, $headers);

ezmlm_hash. Вычисление хеша EZMLM

int ezmlm_hash (string addr)

Функция вычисляет хеш, который используется для сохранения списков рассылки в базе данных MySQL.

Пример использования этой функции приведен в листинге 4.41.

Листинг 4.41
$user = "kris@koehntopp.de";
$hash = ezmlm_hash ($user);
$query = sprintf ("INSERT INTO sample VALUES (%s, '%s')", $hash, $user);
$db->query($query); // исплльзуем интерфейс PHPLIB db

IMAP, POP3 и NNTP

Чтобы использовать функции, описанные в этом разделе, необходимо перекомпилировать PHP с опцией --with-imap. Но для этого должны быть установлены клиентские библиотеки С. Последнюю версию для компиляции можно загрузить с ресурса ftp://ftp.cac.washington.edu/imap. Можно также подключить модуль динамически.

Для большего понимания методики работы этих функций будет полезно ознакомиться с перечисленными ниже документами RFC:

imap_open. Подключение к серверу и открытие почтового ящика

int imap_open (string mailbox, string username, string password [, int flags])

Функция возвращает дескриптор открытого почтового ящика IMAP или значение FALSE при возникновении ошибки. Эту функцию можно также использовать для подключения к серверам POP3 и NNTP, но в этом случае некоторые функции пакета будут недоступны.

В аргументе mailbox указывается имя сервера и путь к почтовому ящику. Имя сервера заключается в фигурные скобки и состоит из имени сервера или его IP-адреса, необязательного имени протокола, которое надо предварять символом слеша, и необязательного значения номера порта подключения, которое начинается с двоеточия. Имя сервера необходимо указывать всегда. Иногда бывает полезно указывать имя сервера в переменной, но следует учитывать, что фигурные скобки имеют специальное значение для переменных в строках в двойных кавычках, поэтому открывающую скобку следует предварять слешем, например \{$SERVER/ pop3:110}INBOX.

Специальное имя INBOX обозначает основной ящик пользователя и папку входящих сообщений. Если имя ящика включает дополнительные символы помимо стандартных латинских символов, то имя предварительно нужно закодировать функцией imap_utf7_encode(). Разделителем иерархии почтовых ящиков обычно является слеш, но для некоторых серверов им также может быть точка.

При помощи аргументов username и password указываются имя и пароль пользователя.

В аргументе flags указываются параметры открытия ящика в виде битовой маски. Эти параметры приведены в следующем списке.

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

$mbox = imap_open ("{localhost:143}INBOX", "user_id", "password");

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

$mbox = imap_open ("{localhost/pop3:110}INBOX", "user_id", "password");

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

$nntp = imap_open ("{localhost/nntp:119}comp.test", "", "");

Пример, приведенный в листинге 4.42, демонстрирует подключение к серверу IMAP your.imap.host и вывод имеющихся ящиков и сообщений для пользователя username.

Листинг 4.42
$mbox = imap_open ("{your.imap.host:143}", "username", "password");
echo "<p><h1>Ящики Mailboxes</h1>\n";
$folders = imap_listmailbox ($mbox, "{your.imap.host:143}", "*");
if ($folders == FALSE)   echo "Ошибка ящиков не обнаружено <br>\n";
else 
   while (list ($key, $val) = each ($folders)) 
      echo "\t $val <br>\n";
echo "<p><h1>Сообщения в INBOX</h1>\n";
$headers = imap_headers ($mbox);
if ($headers == FALSE) {   echo "Ошибка – сообщений нет <br>\n";  }
else 
   while (list ($key,$val) = each ($headers)) 
      echo "\t $val <br>\n";
imap_close($mbox);

После работы этого кода на экран будут выведены следующие строки:

Ящики Mailboxes 
   {localhost:143}linnn/igf<br>
   {localhost:143}linnn<br>
   {localhost:143}INBOX<br>
Сообщения в INBOX
   1)13-May-2001 Имя отправителя   Заголовок (1621 chars)<br>

imap_reopen. Переподключение и выбор другого ящика

int imap_reopen (int imap_stream, string mailbox [, string flags])

Функция аналогична imap_open(), но она не создает новый дескриптор подключения, а использует уже существующий дескриптор imap_stream. Имя пользователя и его пароль не изменяются. В случае успешного выполнения возвращается значение TRUE. При возникновении ошибки возвращается значение FALSE.

imap_close. Отключение от сервера

int imap_close (int imap_stream [, int flags])

Функция закрывает поток подключения, связанный с дескриптором imap_stream. Если в аргументе flags указывается значение CL_EXPUNGE, то при закрытии ящика из него автоматически удаляются все сообщения, помеченные на удаление.

imap_ping. Проверка активности подключения

int imap_ping (int imap_stream)

Функция возвращает значение TRUE, если подключение все еще действительно. Если оно разорвано, то возвращается значение FALSE.

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

imap_listmailbox. Получение списка почтовых ящиков

array imap_listmailbox (int imap_stream, string ref, string pattern)

Функция возвращает массив имен почтовых ящиков. Аргументы рассматривались в описании функции imap_getmailboxes(). Пример использования функции приведен в листинге 4.43.

Листинг 4.43
$mbox = imap_open("{your.imap.host}","username","password",OP_HALFOPEN)
      || die("can't connect: ".imap_last_error());
$list = imap_listmailbox($mbox,"{your.imap.host}","*");
if(is_array($list)) {
   reset($list);
   while (list($key, $val) = each($list))
      print imap_utf7_decode($val)."<br>\n";
}
else
   print "imap_listmailbox failed: ".imap_last_error()."\n";
imap_close($mbox);

imap_getmailboxes. Получение описания почтовых ящиков

array imap_getmailboxes (int imap_stream, string ref, string pattern)

Функция возвращает массив объектов, содержащих описания каждого ящика. Каждый объект имеет три атрибута, в которых указывается полное имя ящика name, разделитель иерархии ящиков delimiter и битовое поле attributes, которое может состоять из компонентов, перечисленных в следующем списке:

Имена ящиков могут содержать символы национальных алфавитов из набора ASCII, которые могут быть закодированы и затем декодированы функцией imap_ utf7_decode().

Аргумент ref должен содержать обычную спецификацию сервера, как в функции imap_open(), а аргумент pattern указывает, с какого ящика следует начинать перебор значений, а также шаблон для возвращаемых ящиков.

В аргументе pattern могут быть указаны два специальных значения. Символ звездочки означает, что следует возвращать всю иерархию ящиков, а символ процента заставляет функцию возвращать только текущий иерархический уровень без вложенных ящиков.

Пример использования функции приведен в листинге 4.44.

Листинг 4.44
$mbox = imap_open("{your.imap.host}","username","password",OP_HALFOPEN)
      || die("can't connect: ".imap_last_error());
$list = imap_getmailboxes($mbox,"{your.imap.host}","*");
if(is_array($list)) {
   print_r ($list);
}
else
   print "imap_getmailboxes failed: ".imap_last_error()."\n";
imap_close($mbox);

См. также imap_getsubscribed().

imap_createmailbox. Создание почтового ящика

int imap_createmailbox (int imap_stream, string mbox)

Функция предназначена для создания новых почтовых ящиков. Имя создаваемого ящика указывается в аргументе mbox. Имена, содержащие национальные символы, должны кодироваться функцией imap_utf7_encode().

В случае успешного выполнения возвращается значение TRUE. При возникновении ошибки возвращается значение FALSE.

См. также imap_renamemailbox(), imap_deletemailbox() и imap_open().

Пример использования функции приведен в листинге 4.45.

Листинг 4.45
$mbox = imap_open("{your.imap.host}","username","password",OP_HALFOPEN)
      || die("can't connect: ".imap_last_error());
$name1 = "newbox";
$name2 = imap_utf7_encode("мой личный ящик");
if(@imap_createmailbox($mbox,
      imap_utf7_encode("{your.imap.host}INBOX/$name1"))) {
   $status = @imap_status($mbox,"{your.imap.host}INBOX/$name1",SA_ALL);
   if($status) {
      echo  "Статус нового ящика '$name1': <br>\n",
         "Messages:   ". $status->messages   ."<br>\n",
         "Recent:     ". $status->recent     ."<br>\n",
         "Unseen:     ". $status->unseen     ."<br>\n",
         "UIDnext:    ". $status->uidnext    ."<br>\n",
         "UIDvalidity:". $status->uidvalidity."<br>\n";
      if(imap_renamemailbox($mbox,"{your.imap.host}INBOX/$name1",
            "{your.imap.host}INBOX/$name2")) {
         echo "Ящик '$name1' переименован в '$name2'<br>\n";
   }
   else{
      print "imap_renamemailbox failed: ".imap_last_error()."<br>\n";
   }
}
else{
   print  "imap_status failed: ".imap_last_error()."<br>\n";
}
if(@imap_deletemailbox($mbox,"{your.imap.host}INBOX/$name2")) {
   print "new mailbox removed <br>\n";
}
else {
   print  "imap_deletemailbox failed: ".
      implode("<br>\n",imap_errors())."<br>\n";
}
}
else {
   print  "could not create new mailbox: ".
      implode("<br>\n",imap_errors())."<br>\n";
}
imap_close($mbox);

imap_renamemailboximap_renamemailbox. Переименование ящика

int imap_renamemailbox (int imap_stream, string old_mbox, string new_mbox)

Функция позволяет переименовать существующий ящик. Имя ящика задается аргументом old_mbox, а его новое имя указывается в параметре new_mbox. Формат этих аргументов рассматривался в описании функции imap_open().

В случае успешного выполнения возвращается значение TRUE. При возникновении ошибки возвращается значение FALSE.

См. также imap_createmailbox(), imap_deletemailbox(), imap_open().

imap_deletemailbox. Удаление почтового ящика

int imap_deletemailbox (int imap_stream, string mbox)

Функция позволяет удалить существующий ящик. Имя ящика задается аргументом mbox. В случае успешного выполнения возвращается значение TRUE. При возникновении ошибки возвращается значение FALSE.

См. также imap_createmailbox(), imap_renamemailbox() и imap_open().

imap_check. Проверка текущего ящика

object imap_check (int imap_stream)

Функция возвращает объект, содержащий информацию о текущем почтовом ящике. При возникновении ошибки возвращается значение FALSE.

Свойства возвращаемого объекта перечислены в следующем списке:

Пример использования этой функции приведен в листинге 4.46.

Листинг 4.46
$mbox = imap_open("{localhost}","igor","igx324879",OP_HALFOPEN)
      || die("can't connect: ".imap_last_error());
print_r(imap_check ($mbox));
imap_close($mbox);

В результате работы этого кода на экран будут выведены следующие строки:

stdClass Object
(
   [Date] => Sun, 13 May 2008 14:31:38 +0400 (Московское время (лето))
   [Driver] => imap
   [Mailbox] => {igor:143/imap/user="igor"}<no_mailbox>
   [Nmsgs] => 0
   [Recent] => 0
)

imap_status. Получение статуса указанного ящика

object imap_status (int imap_stream, string mailbox, int options)

Функция возвращает объект, содержащий информацию о почтовом ящике с именем mailbox. При возникновении ошибки возвращается значение FALSE. Набор свойств возвращаемого объекта варьируется в зависимости от указанного значения аргумента options. Возможные значения этого параметра приведены в следующем списке:

Пример использования функции приведен в листинге 4.47.

Листинг 4.47
$mbox = imap_open("{your.imap.host}","username","password",OP_HALFOPEN)
      || die("can't connect: ".imap_last_error());
$status = imap_status($mbox,"{your.imap.host}INBOX",SA_ALL);
if($status) {
   print_r($status);
}
else
   print "imap_status failed: ".imap_lasterror()."\n";
imap_close($mbox);

imap_mailboxmsginfo. Получение информации о текущем ящике

object imap_mailboxmsginfo (int imap_stream)

Функция сходна с imap_status(), но она также вычисляет объем всех сообщений, находящихся в ящике. Функция возвращает объект, свойства которого перечислены в следующем списке:

Пример использования функции приведен в листинге 4.48.

Листинг 4.48
<?php
$mbox = imap_open("{your.imap.host}INBOX","username", "password")
      || die("can't connect: ".imap_last_error());
$check = imap_mailboxmsginfo($mbox);
if($check) {
   print "Date: "    . $check->Date    ."<br>\n" ;
   print "Driver: "  . $check->Driver  ."<br>\n" ;
   print "Mailbox: " . $check->Mailbox ."<br>\n" ;
   print "Messages: ". $check->Nmsgs   ."<br>\n" ;
   print "Recent: "  . $check->Recent  ."<br>\n" ;
   print "Unread: "  . $check->Unread  ."<br>\n" ;
   print "Deleted: " . $check->Deleted ."<br>\n" ;
   print "Size: "    . $check->Size    ."<br>\n" 
}
else {
   print "imap_check() failed: ".imap_last_error(). "<br>\n";
}
imap_close($mbox);
?>

imap_num_msg. Получение количества сообщений в текущем ящике

int imap_num_msg (int imap_stream)

Функция возвращает количество сообщений, хранящихся в почтовом ящике.

imap_num_recent. Получение количества новых сообщений в текущем ящике

int imap_num_recent (int imap_stream)

Функция возвращает количество новых сообщений в почтовом ящике.

imap_listsubscribed. Получение списка активных ящиков

array imap_listsubscribed (int imap_stream, string ref, string pattern)

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

Функция возвращает в массиве имена папок, выбранных для синхронизации. Она аналогична функции imap_listmailbox().

imap_getsubscribed. Получение описания активных ящиков

array imap_getsubscribed (int imap_stream, string ref, string pattern)

Функция аналогична imap_getmailboxes(), но она возвращает имена только тех ящиков, которые были выбраны для синхронизации.

imap_subscribe. Сделать ящик активным

int imap_subscribe (int imap_stream, string mbox)

Указанный ящик в дальнейшем будет использоваться для синхронизации. В случае успешного выполнения возвращается значение TRUE. При возникновении ошибки возвращается значение FALSE.

imap_unsubscribe. Сделать ящик неактивным

int imap_unsubscribe (int imap_stream, string mbox)

Функция делает ящик неактивным, и в дальнейшем он не будет использоваться для синхронизации.

imap_search. Поиск в текущем ящике

array imap_search (int imap_stream, string criteria, int flags)

Функция возвращает список почтовых ящиков, в которых было обнаружено соответствие критерию, указанному в аргументе criteria. В строке критерия указываются искомые слова, разделенные пробелами. Если необходимо искать фразу, то ее следует заключать в двойные кавычки. Перед набором слов указывается имя поля, в котором следует производить поиск. Можно также указать флаги просматриваемых сообщений. Применяемые флаги перечислены в следующем списке:

Чтобы найти все сообщения от отправителя Peter, на которые не был выслан ответ, указывается строка UNANSWERED FROM Peter. Поиск не чувствителен к регистру. Приведенный список критериев взят из исходного текста библиотеки и может быть не полным. Более подробная информация приведена в документе RFC2060, section 6.4.4.

Допустимым значением аргумента flags является SE_UID. Оно указывает, что вместо относительных последовательных номеров сообщений следует возвращать уникальные идентификаторы UID.

imap_scanmailbox. Поиск текста в сообщениях

array imap_scanmailbox (int imap_stream, string ref, string pattern, string content)

Функция подобна imap_listmailbox(), но она возвращает имена только тех ящиков, которые содержат в себе строку content.

imap_fetch_overview. Получение описания сообщений

array imap_fetch_overview (int imap_stream, string sequence [, int flags])

Функция возвращает в массиве объекты, содержащие информацию о сообщениях, номера которых перечислены в строке sequence. Эта строка должна содержать номер сообщения или номера нескольких сообщений через запятую, без пробелов. Можно также указать диапазон номеров, использовав двоеточие. Если в значении аргумента указана константа FT_UID, то это указывает на то, что номера являются уникальными идентификаторами UID.

Свойства объектов массива перечислены в следующем списке:

Пример использования функции приведен в листинге 4.49.

Листинг 4.49
$mbox = imap_open("{your.imap.host:143}","username","password")
      || die("can't connect: ".imap_last_error());
$overview = imap_fetch_overview($mbox,"2,4:6",0);
if(is_array($overview)) { print_r($overview); }
imap_close($mbox);

В результате работы этого кода на экран будет выведена следующая информация:

Array
(
   [0] => stdClass Object
      (
      [subject] => Поздравление
      [from] => IG <ig@igor.>
      [date] => Sun, 13 May 2001 01:41:00 +0400
      [message_id] => <000801c0db2c$3c46a2c0$0100007f@igor>
      [size] => 1621
      [uid] => 289703661
      [msgno] => 1
      [recent] => 0
      [flagged] => 0
      [answered] => 0
      [deleted] => 0
      [seen] => 1
      [draft] => 0
      )

imap_headers. Получение списка сообщений текущего ящика

array imap_headers (int imap_stream)

Функция возвращает массив, содержащий заголовки имеющихся сообщений. Сообщения вложенных папок не просматриваются.

imap_headerinfo. Просмотр заголовка сообщения

object imap_headerinfo (int imap_stream, int msg_number [, int fromlength [, int subjectlength [, string defaulthost]]]) 

Функция возвращает объект, содержащий различную информацию о сообщении. В качестве примера можно привести следующий вызов функции:

$mbox = imap_open ("\{$SERVER/pop3:110}INBOX", "igor7", "igx321"); 
print_r(imap_header($mbox,1));

В результате работы этого кода на экран будут выведены следующие строки:

stdClass Object
(
   [date] => Sun, 13 May 2005 01:41:00 +0400
   [Date] => Sun, 13 May 2005 01:41:00 +0400
   [subject] => Послание
   [Subject] => Послание
   [message_id] => <000801c0db2c$3c46a2c0$0100007f@igor>
   [toaddress] => igor@localhost
   [to] => Array
      (
      [0] => stdClass Object
         (
         [mailbox] => igor
         [host] => localhost
         )
      )
   [fromaddress] => IG <ig@igor.>
   [from] => Array
      (
      [0] => stdClass Object
         (
         [personal] => IG
         [mailbox] => ig
         [host] => igor.
         )
      )
   [reply_toaddress] => IG <ig@igor.>
   [reply_to] => Array
      (
      [0] => stdClass Object
         (
         [personal] => IG
         [mailbox] => ig
         [host] => igor.
         )
      )
   [senderaddress] => IG <ig@igor.>
   [sender] => Array
      (
      [0] => stdClass Object
         (
         [personal] => IG
         [mailbox] => ig
         [host] => igor.
         )
      )
   [Recent] => N
   [Unseen] =>
   [Flagged] =>
   [Answered] =>
   [Deleted] =>
   [Draft] =>
   [Msgno] =>    1
   [MailDate] => 13-May-2005 01:41:00 +0400
   [Size] => 1581
   [udate] => 989703660
)

Структура и формат записей определяются реализацией серверного интерфейса и могут сильно различаться для различных систем. В большинстве случаев для сообщений протоколов IMAP, POP3 и NNTP форматы информационных полей идентичны.

Для сообщений news-серверов дополнительно возвращается свойство newsgroup.

Пары полей date, Date и subject, Subject обычно совпадают. В message_id хранится уникальный хеш сообщения, а в Msgno — относительный порядковый номер. В записях Size и udate возвращаются, соответственно, размер сообщения в байтах и время в формате UNIX Timestamp.

В большинстве случаев адреса fromaddress, reply_toaddress и senderaddress совпадают. Если у сообщения имеется поле Cc, то также возвращается адрес ccaddress.

imap_sort. Сортировка заголовков

array imap_sort (int stream, int criteria, int reverse, int options)

Возвращает массив номеров сообщений, сортированных по критерию. Если в аргументе reverse указывается значение TRUE, то сортировка проводится в обратном порядке.

Возможные значения аргумента criteria приведены в следующем списке:

Флаги options аргумента могут содержать следующие значения:

imap_fetchstructure. Получение полной информации о сообщении

object imap_fetchstructure (int imap_stream, int msg_number [, int flags])

Информация возвращается в объекте, который описывает формат и структуру сообщения в текущем ящике, указанного порядковым номером msg_number. Если в аргументе flags указывается значение FT_UID, то это свидетельствует о том, что в аргументе msg_number указан не номер сообщения, а его идентификатор UID.

Поля объекта приведены в следующем списке:

Значения типа type основного тела перечислены в следующем списке:

Типы кодировки encoding перечислены в следующем списке:

Для простого сообщения искомый объект может выглядеть следующим образом:

stdClass Object
(
   [ifsubtype] => 1
   [subtype] => PLAIN
   [ifdescription] => 0
   [ifid] => 0
   [lines] => 2
   [bytes] => 41
   [ifdisposition] => 0
   [ifdparameters] => 0
   [ifparameters] => 0
   [parameters] => stdClass Object
      (
      )
)

Для сложного сообщения объект будет выглядеть несколько сложнее:

stdClass Object
(
   [type] => 1
   [ifsubtype] => 1
   [subtype] => ALTERNATIVE
   [ifdescription] => 0
   [ifid] => 0
   [ifdisposition] => 0
   [ifdparameters] => 0
   [ifparameters] => 1
   [parameters] => Array
      (
         [0] => stdClass Object
            (
            [attribute] => boundary
            [value] => ----=_NextPart_000_0005_01C0DB4D.C33837A0
            )
        )
   [parts] => Array
      (
         [0] => stdClass Object
            (
            [encoding] => 4
            [ifsubtype] => 1
            [subtype] => PLAIN
            [ifdescription] => 0
            [ifid] => 0
            [lines] => 5
            [bytes] => 59
            [ifdisposition] => 0
            [ifdparameters] => 0
            [ifparameters] => 1
            [parameters] => Array
               (
               [0] => stdClass Object
                  (
                  [attribute] => charset
                  [value] => koi8-r
                  )
               )
             )
          [1] => stdClass Object
             (
             [encoding] => 4
             [ifsubtype] => 1
             [subtype] => HTML
             [ifdescription] => 0
             [ifid] => 0
             [lines] => 14
             [bytes] => 547
             [ifdisposition] => 0
             [ifdparameters] => 0
             [ifparameters] => 1
             [parameters] => Array
                (
                [0] => stdClass Object
                   (
                   [attribute] => charset
                   [value] => koi8-r
                   )
                )
             )
      )
)

imap_fetchheader. Получение заголовка сообщения

string imap_fetchheader (int imap_stream, int msgno, int flags)

Функция возвращает полный заголовок формата RFC822 сообщения с номером msgno из выбранного ящика.

Возможные значения аргумента flags указаны в следующем списке:

imap_body. Получение сообщения

string imap_body (int imap_stream, int msg_number [, int flags])

Функция возвращает тело сообщения с номером msg_number из указанного ящика. Возможные значения аргумента flags перечислены в следующем списке:

Функция возвращает полную точную копию сообщения. С ее помощью можно прочитать простые сообщения. Для составных сообщений функция может вернуть строку This is a multi-part message in MIME format. Чтобы извлечь отдельные части сообщения и обработать их согласно указанному типу MIME, нужно воспользоваться функциями imap_fetch_structure() и imap_fetch_body().

imap_fetchbody. Получение части сообщения

string imap_fetchbody (int imap_stream, int msg_number, string part_number [, flags flags])

Функция возвращает часть тела сообщения с номером msg_number из выбранного ящика. Спецификация указания перечисления номеров секций в аргументе part_ number определяется IMAP4.

Возможные значения аргумента flags перечислены в следующем списке:

Для сложного сообщения, структура которого приведена в примере функции imap_fetchstructure(), содержание частей может быть усложненным.

Основная часть сообщения, которая возвращается вызовом imap_fetchbody ($m,1,0), выглядит следующим образом:

X-F: <ig@igor.> Sun May 13 01:41:00 2003
Received: from igor [127.0.0.1] by igor.
   (SMTPD32-6.06 EVAL) id ADEC10316; Sun, 13 May 2001 01:41:00 +0400
Message-ID: <000801c0db2c$3c46a2c0$0100007f@igor>
From: "IG" <ig@igor.>
To: <igor@localhost>
Subject: Приветствие
Date: Sun, 13 May 2001 01:41:00 +0400
MIME-Version: 1.0
Content-Type: multipart/alternative;
   boundary="----=_NextPart_000_0005_01C0DB4D.C33837A0"
X-Priority: 3
X-MSMail-Priority: Normal
X-Mailer: Microsoft Outlook Express 5.00.2919.6700
X-MimeOLE: Produced By Microsoft MimeOLE V5.00.2919.6700
X-RCPT-TO: <igor@localhost>
X-UIDL: 289703661
Status: U

Первая вложенная часть может быть получена при помощи вызова imap_ fetchbody($m,1,1). Выглядит она следующим образом:

Привет.
У нас все хорошо.
Пока.

Вторая вложенная часть, возвращенная вызовом imap_fetchbody($m,1,2), будет выглядеть сложнее:

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<HTML><HEAD>
<META content=3D"text/html; charset=3Dkoi8-r" http-equiv=3DContent-Type>
<META content=3D"MSHTML 5.00.2920.0" name=3DGENERATOR>
<STYLE></STYLE>
</HEAD>
<BODY bgColor=3D#ffffff>
<DIV><FONT face=3D"Arial Cyr" size=3D2> Привет.</FONT></DIV>
<DIV><FONT face=3D"Arial CYR" size=3D2> У нас все хорошо.</FONT></DIV>
<DIV><FONT face=3D"Arial CYR" size=3D2> Пока. </FONT></DIV>
</BODY></HTML>

imap_uid. Получение UID сообщения из порядкового номера

int imap_uid (int imap_stream, int msgno)

Функция возвращает уникальный идентификатор сообщения UID. Он отличается от обычного порядкового номера, потому что номера перевычисляются при удалении сообщений. Вызов функции предельно прост:

echo imap_uid($mbox,1);  // выводит, например, 289703661 

imap_msgno. Получение порядкового номера сообщения из UID

int imap_msgno (int imap_stream, int uid)

Действие функции обратно imap_uid().

imap_setflag_full. Установка флагов сообщения

string imap_setflag_full (int stream, string sequence, string flag, string options)

Функция позволяет установить флаги для выбранного сообщения. В аргументе sequence указывается перечисление номеров сообщений, для которых необходимо установить флаги, указанные в аргументе flag. Флаги обозначаются, как \\Seen, \\Answered, \\Flagged, \\Deleted, \\Draft и \\Recent.

В аргументе options может быть указано значение ST_UID, указывающее на то, что в аргументе sequence указан уникальный идентификатор UID.

Пример использования функции приведен в листинге 4.50.

Листинг 4.50
$mbox = imap_open("{your.imap.host:143}","username","password")
      || die("can't connect: ".imap_last_error());
if (imap_setflag_full($mbox,"2,4,15:19,23","\\Seen \\Flagged"))
   print "Флаги установлены\n";
imap_close($mbox);

imap_clearflag_full. Сброс флагов сообщения

string imap_clearflag_full (int stream, string sequence, string flag, string options)

Действие функции противоположно imap_setflag_full(). Она сбрасывает флаги у выбранных сообщений.

imap_delete. Маркировка сообщения как удаленного

int imap_delete (int imap_stream, int msg_number [, int flags])

В аргументе msg_number указывается номер сообщения, а в параметре flags при значении FT_UID указывается, является ли номер идентификатором. Сообщения, помеченные к удалению, остаются в ящике, пока не будет вызвана функция imap_ expunge() или подключение с установленным флагом CL_EXPUNGE не будет закрыто функцией imap_close().

Пример использования функции пирведен в листинге 4.51.

Листинг 4.51
$mbox = imap_open ("{your.imap.host}INBOX", "username", "password")
      || die ("can't connect: " . imap_last_error());
$check = imap_mailboxmsginfo ($mbox);
print "Сообщений до удаления: ". $check->Nmsgs . "<br>\n" ;
imap_delete ($mbox, 1);
$check = imap_mailboxmsginfo ($mbox);
print "Сообщений после удаления: ".$check->Nmsgs."<br>\n" ;
imap_expunge ($mbox);
$check = imap_mailboxmsginfo ($mbox);
print " Сообщений после expunge(): ".$check->Nmsgs."<br>\n" ;
imap_close ($mbox);

imap_undelete. Восстановление удаленного сообщения

int imap_undelete (int imap_stream, int msg_number)

Функция снимает флаг удаления с сообщения с номером msg_number. Этот флаг ранее мог быть установлен функциями imap_delete(), imap_mail_move(), или imap_ setflag_full().

imap_expunge. Удаление сообщений, помеченных к удалению

int imap_expunge (int imap_stream)

Функция полностью удаляет из ящика сообщения, имеющие флаг \\Deleted, который может быть установлен функциями imap_delete(), imap_mail_move() или imap_ setflag_full().

imap_mail_copy. Копирование сообщения в ящик

int imap_mail_copy (int imap_stream, string msglist, string mbox [, int flags])

Перечисление номеров копируемых сообщений указывается в строковом аргументе msglist. Их следует перечислять без пробелов через запятую, диапазоны указываются знаком двоеточия. Функция копирует выбранное сообщение в указанный ящик.

Ящик назначения, указываемый в аргументе mbox, указывается без имени сервера.

В аргументе flags можно указывать битовую маску из следующих констант:

Вызов функции выглядит достаточно просто:

imap_mail_copy($m, "1,3:5","INBOX/Текущие")

imap_mail_move. Перемещение сообщения в ящик

int imap_mail_move (int imap_stream, string msglist, string mbox [, int flags])

Функция аналогична следующему вызову:

imap_mail_copy(imap_stream, msglist, mbox, flags | CP_MOVE )

imap_alertsimap_alerts. Получение извещений IMAP

array imap_alerts (void)

Функция возвращает массив, содержащий все извещения, посланные сервером от начала подключения или после прошлого вызова данной функции.

imap_mime_header_decode. Декодирование элементов MIME- заголовков

array imap_header_decode (string text)

Функция декодирует расширенные заголовки, посланные не в виде текста ASCII. Декодированные элементы возвращаются в массиве объектов, каждый из которых содержит значения "charset" и "text", в которых указываются кодировка и содержимое текста. Если заголовки не были закодированы, то значение элемента "charset" будет равно "default".

Пример использования функции приведен в листинге 4.52.

Листинг 4.52
$text="=?ISO-8859-1?Q?Keld_J=F8rn_Simonsen?= <keld@dkuug.dk>";
print_r(imap_mime_header_decode($text));

В результате работы этого кода на экран будут выведены следующие строки:

Array(
   [0] => stdClass Object (
      [charset] => ISO-8859-1
      [text] => Keld Jorn Simonsen
   )
   [1] => stdClass Object (
      [charset] => default
      [text] =>  <keld@dkuug.dk>
   )
)

imap_mail_compose. Создание сообщения MIME по шаблону

string imap_mail_compose (array envelope, array body)

Функция создает новое сообщение, как показано в листинге 4.53.

Листинг 4.53
<?php
$envelope["from"]="musone@afterfive.com";
$envelope["to"]="musone@darkstar";
$envelope["cc"]="musone@edgeglobal.com";
$part1["type"]=TYPEMULTIPART;
$part1["subtype"]="mixed";
$filename="/tmp/imap.c.gz";
$fp=fopen($filename,"r");
$contents=fread($fp,filesize($filename));
fclose($fp);
$part2["type"]=TYPEAPPLICATION;
$part2["encoding"]=ENCBINARY;
$part2["subtype"]="octet-stream";
$part2["description"]=basename($filename);
$part2["contents.data"]=$contents;
$part3["type"]=TYPETEXT;
$part3["subtype"]="plain";
$part3["description"]="description3";
$part3["contents.data"]="contents.data3\n\n\n\t";
$body[1]=$part1;
$body[2]=$part2;
$body[3]=$part3;
echo nl2br(imap_mail_compose($envelope,$body));
?>

imap_append. Создание сообщения в ящике

int imap_append (int imap_stream, string mbox, string message [, string flags])

Функция позволяет создавать сообщения в выбранном ящике. В аргументе message содержится текст сообщения, включая текст заголовка. Для многих серверов необходимо обозначать конец строк парой символов \r\n.

В аргументе flags можно указать флаги, присваиваемые сообщению.

Пример использования функции приведен в листинге 4.54.

Листинг 4.54
$stream = imap_open("{your.imap.host}INBOX.Drafts","username", "password");
$check = imap_check($stream);
print "Сообщений было: ". $check->Nmsgs."\n";
imap_append($stream,"{your.imap.host}INBOX.Drafts"
                   ,"From: me@my.host\r\n"
                   ."To: you@your.host\r\n"
                   ."Subject: test\r\n"
                   ."\r\n"
                   ."this is a test message, please ignore\r\n",
                   "\\Flagged \\Draft");
$check = imap_check($stream);
print "Сообщений стало: ". $check->Nmsgs."\n";
imap_close($stream);

Вспомогательные функции

imap_last_error. Получение описания последней ошибки

string imap_last_error (void)

Функция возвращает строку, содержащую полное описание ошибки IMAP, произошедшей в ходе исполнения скрипта. Стек сообщений не изменяется, и повторный вызов функции возвратит то же самое значение, если не произошло других ошибок.

imap_errors. Получение всех возникших ошибок

array imap_errors (void)

Функция возвращает массив, содержащий строки описания ошибок IMAP, произошедших от начала подключения или с момента последнего вызова данной функции. Вызов функции полностью очищает стек ошибок.

imap_rfc822_write_addressimap_rfc822_write_address. Форматирование строки адреса

string imap_rfc822_write_address (string mailbox, string host, string personal)

Функция возвращает строку электронного адреса, сформированную из заданных значений, согласно правилам, указанным в RFC822. Вызов функции достаточно прост:

print imap_rfc822_write_address("ig","php.net","Igor Grigin");      
// выведет: Igor Grigin <ig@php.net> 

imap_rfc822_parse_adrlist. Интерпретация адреса

array imap_rfc822_parse_adrlist (string address, string default_host)

Исходная строка с перечислением почтовых адресов, записанных в формате RFC822, указывается в аргументе address. Аргумент содержит имя хоста, добавляемое к адресу. Функция возвращает массив объектов, свойства которых указаны в следующем списке:

Пример использования функции приведен в листинге 4.55.

Листинг 4.55
$address_string = "Igor Grigin <ig@my.domain.net>,
   postmaster@somedomain.net, root";
$address_array = imap_rfc822_parse_adrlist($address_string,"our.net");
if(! is_array($address_array)) die("somethings wrong\n");
print_r($address_array);

В результате работы этого кода на экран будут выведены следующие строки:

Array(
   [0] => stdClass Object (
      [mailbox] => ig
      [host] => my.domain.net
      [personal] => Igor Grigin
   )
   [1] => stdClass Object (
      [mailbox] => postmaster
      [host] => somedomain.net
   )
   [2] => stdClass Object (
      [mailbox] => root
      [host] => our.net
   )
)

imap_rfc822_parse_headers. Интерпретация заголовков из строки

object imap_rfc822_parse_headers (string headers [, string defaulthost])

Функция сходна с imap_header(), но информацию она получает не от сервера IMAP, а из строки headers.

imap_utf7_decode. Декодирование строки UTF-7

string imap_utf7_decode (string text)

Функция возвращает оригинальную строку после декодирования. Эта кодировка часто используется для адресов почтовых ящиков, содержащих национальные символы. Функция использует модифицированный алгоритм, описанный в RFC 2060, section 5.1.3. Устаревший алгоритм был описан в RFC1642.


Любой из материалов, опубликованных на этом сервере, не может быть воспроизведен в какой бы то ни было форме и какими бы то ни было средствами без письменного разрешения владельцев авторских прав.