Методы класса FileSystem

Существует три различных способа указания пути к файлу:

• абсолютный (например, "/images/banner.gif", обратите внимание на слеш в начале строки): такой путь отсчитывается от корневого каталога сайта. Наиболее удобный вариант, поскольку позволяет использовать одни и те же пути и для локальных сборок, и для продукционных сайтов;
• относительный (например, "images/banner.gif", без начального слеша): такой путь отсчитывается от текущего каталога. Не рекомендуется использовать, так как на разных серверах и на разных версиях PHP понятие "текущего каталога" может сильно различаться;
• канонический (например, "/var/www/sites/mysite/public_html/images/banner.gif"): отсчитывается от корневого каталога сервера. Также не рекомендуется использовать, поскольку эти пути на всех серверах разные.

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

void normalize ( string &filename )

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

Пример:

$filename="/images/title.gif";
$fileSystem->normalize($filename);
echo $filename; // Что-нибудь вроде /var/www/public_html/images/title.gif 

void localize ( string &filename )

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

Пример:

$filename="/var/www/public_html/images/title.gif";
$fileSystem->localize($filename);
echo $filename; // Выводит /images/title.gif 

string validateFilename ( string filename )

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

Пример:

$filename="'Landscape...' (image).JPG";
echo $fileSystem->validateFilename($filename); // Landscape_image.jpg

$filename="@#$%@.dat";
echo $fileSystem->validateFilename($filename); // noname.dat 

string incrementFilename ( string filename )

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

Пример:

$filename="image.jpg";
echo $fileSystem->incrementFilename($filename); // image1.jpg

$filename="image1.jpg";
echo $fileSystem->incrementFilename($filename); // image2.jpg

$filename="image100.jpg";
echo $fileSystem->incrementFilename($filename); // image101.jpg 

string openFile ( string filename [, bool normalize] )

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

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

Пример:

$content=$fileSystem->openFile("/files/data.txt");
if($content=="") die("Нет данных.");

string openFileTimeout ( string filename [, int timeout [, bool normalize]] )

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

Пример:

$content=$fileSystem->openFileTimeout("http://yandex.ru/");
if($content=="") die("Не удалось загрузить страницу.");

bool saveFile ( string filename, string content [, bool normalize] )

Метод сохраняет данные content в файле filename. Как и в случае метода openFile, вы можете указать путь к файлу в любом формате, но если формат отличается от абсолютного − укажите значение false в качестве последнего параметра.

Метод возвращает true или false, в зависимости от того, удалось сохранить файл или нет. Если файл с таким именем уже существует, он будет перезаписан.

Пример:

$success=$fileSystem->saveFile("/files/data.txt","Важные данные");
if(!$success) die("Не удалось сохранить данные.");

bool renameFile ( string oldfilename, string newfilename [, bool normalize] )

Метод переименовывает либо перемещает файл. Путь к файлу передается параметром oldfilename, новое местоположение и новое имя файла передается параметром newfilename. Если вы хотите только переименовать файл, достаточно указать параметром newfilename только его новое имя. Как и с методом openFile, укажите false в качестве последнего параметра, если вы указываете путь к файлу не в абсолютном формате.

Метод возвращает true или false, в зависимости от того, удалось переименовать файл или нет.

Пример:

$success=$fileSystem->renameFile("/files/data.txt","secretdata.txt");
if(!$success) die("Не удалось переименовать файл.");

bool deleteFile ( string filename [, bool normalize] )

Метод удаляет файл, путь к которому указан параметром filename. Если файл успешно удален, возвращается значение true. Если файл не найден, либо это каталог, либо не хватает прав доступа, метод возвращает false.

Пример:

$success=$fileSystem->deleteFile("/files/data.txt");
if(!$success) die("Не удалось удалить файл.");

bool isFileExists ( string filename [, bool normalize] )

Метод проверяет, существует ли файл либо каталог с именем, переданным параметром filename, и возвращает true, если файл/каталог был найден, и false в противном случае.

Пример:

$found=$fileSystem->isFileExists("/files/data.txt");
if(!$found) die("Файл data.txt не найден.");

int getFileSize ( string filename [, bool normalize] )

Метод возвращает размер файла filename в байтах. В случае ошибки (файл не найден или недостаточно прав для чтения) метод тихо возвращает значение 0, как и в случае пустого файла. Если вам нужно различить ситуации "файл отсутствует" и "файл присутствует, но пуст", используйте метод isFileExists.

Пример:

$size=$fileSystem->getFileSize("/files/data.txt");
if($size>10000) die("Файл слишком большой.");

mixed getImageSize ( string filename [, bool normalize] )

Метод определяет графические размеры изображения, хранящегося в файле filename. Если в файле действительно хранится картинка (поддерживаются все основные графические форматы), метод возвращает ассоциативный массив с ключами width и height. Значения массива − ширина и высота изображения в пикселах. Если файл отсутствует, или его не удается прочитать, или файл не является изображением, метод возвращает false.

Пример:

$size=$fileSystem->getImageSize("/images/title.jpg");
die("Размеры рисунка − $size[width] x $size[height] пикселов.");

string getFileExtension ( string filename )

Метод возвращает расширение файла (начиная с точки), либо пустую строку, если у файла нет расширения.

В качестве параметра filename можно указать как просто имя файла (без пути), так и полный путь к файлу. В отличие от многих других методов класса FileSystem, у этого метода нет параметра normalize, поскольку он корректно определяет расширение файла независимо от того, в каком формате был указан путь к файлу.

Пример:

$filename="image.jpg";
echo $fileSystem->getFileExtension($filename); // .jpg

$filename="/images/image.jpg";
echo $fileSystem->getFileExtension($filename); // .jpg

$filename="data/FileWithNoExtension";
echo $fileSystem->getFileExtension($filename); // Пустая строка 

bool createFolder ( string folder [, int attrs [, bool normalize]] )

Метод создает каталог, путь и имя которого указаны параметром folder. Вторым параметром attrs можно указать права доступа к создаваемому каталогу. По умолчанию каталог создается с правами доступа 0777 (полный доступ для всех), это значение хранится в константе FolderCreateAttributes. Если вы хотите, чтобы каталог создавался с более строгими правами доступа (рекомендуется значение 0755 или даже 0700, но это может работать не на всяком сервере), переопределите эту константу либо укажите значение параметра attrs явно.

Метод возвращает true или false в зависимости от того, удалось ли создать каталог.

Пример:

$success=$fileSystem->createFolder("/files/subfolder");
if(!$success) die("Не удалось создать каталог.");

bool deleteFolder ( string folder [, bool normalize] )

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

Пример:

$success=$fileSystem->deleteFolder("/files/subfolder");
if(!$success) die("Не удалось удалить каталог.");

array getFolder ( string folder [, mixed extensions [, bool normalize]] )

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

Если вас интересуют только файлы определенного типа или типов, вторым параметром extensions можно указать нужное ограничение. Например, можно указать строку (допустимый тип файла) или массив строк (список допустимых типов). Метод вернет только те файлы, типы которых входят в перечисленный вами набор. Сравнение типов происходит без учета регистра.

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

Пример:

$files=$fileSystem->getFolder("/images/photos");
foreach($files as $filename) echo $filename; // icon.png photo1.jpg photo2.jpg photo3.jpg

$files=$fileSystem->getFolder("/images/photos",".jpg");
foreach($files as $filename) echo $filename; // photo1.jpg photo2.jpg photo3.jpg 

array getSubfolders ( string folder [, bool normalize] )

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

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

Пример:

$folders=$fileSystem->getSubfolders("/images/photos");
foreach($folders as $folder) echo $folder; // autumn spring summer winter 

mixed getUploadInformation ( string name )

Метод проверяет, был ли загружен файл с внутренним именем name, и если файл был загружен успешно, возвращает массив со служебной информацией о файле − предположительное имя файла, размер, временное расположение и так далее. Если файл не был успешно загружен, метод возвращает false.

Данный метод является скорее служебным, и используется методами isUploadAttempt, getUploadedFile и processUploadedFile, которые передают ему свой параметр name, и получают служебную информацию о файле, которую уже и обрабатывают каждый по-своему.

Начиная с версии 2.5.1, параметр name может быть массивом, обозначающим "путь" к файлу в структуре _FILES. Это может быть удобно в случае, если файлы или изображения загружаются на сайт пачками − необходимо только помнить, что один вызов метода обрабатывает ровно один файл, соответственно вам нужно для каждого загруженного файла сделать по вызову метода, каждый раз с новым значением параметра name.

bool isUploadAttempt ( string name )

Метод проверяет, была ли попытка закачать на сервер пользовательский файл через поле формы с именем name. Сам по себе этот метод не выполняет никаких действий по перемещению закачанного файла на сайт; он только определяет, был ли файл вообще отправлен на сервер. Метод возвращает true, если файл был успешно закачан (и теперь дожидается своей участи во временной папке сервера), и false в противном случае.

Пример:

<!-- HTML-код формы для закачки файла на сервер -->
<!-- Файл будет отправлен на сервер через слот "imagedata" -->
<form enctype="multipart/form-data" action="/actionUpload" method="post">
Картинка: <input type="file" name="imagedata"><br>
<input type="submit">
</form>

$uploaded=$fileSystem->isUploadAttempt("imagedata");
if(!$uploaded) die("Вы не указали файл.");

mixed getUploadedFile ( string name )

Метод возвращает информацию о загруженном файле, такую, как указанное пользователем имя файла, его размер и содержимое. Параметр name означает имя поля формы, через которое файл был закачан на сервер. Если файл был загружен успешно, метод возвращает ассоциативный массив с ключами filename, size, content − предполагаемое имя файла, размер в байтах и содержимое. Если во время загрузки произошла ошибка, или был загружен файл нулевой длины, или сервер вообще не поддерживает загрузку файлов, метод возвращает false.

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

Пример:

// Берем информацию о файле
$file=$fileSystem->getUploadedFile("imagedata");
if(!$file) die("Не указан или не загрузился файл.");
// Делаем имя файла безопасным для сохранения
$filename=$fileSystem->validateFilename($file["filename"]);
// Сохраняем файл на сервере в папке files, под именем $filename
$fileSystem->saveFile("/files/$filename",$file["content"]);

mixed processUploadedFile ( string name, string folder [, mixed format [, mixed extensions [, array convert [, int maxsize [, bool normalize]]]]] )

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

Обязательных параметров у метода всего два:

• name: имя формы, через которое пользователь загрузил файл на сервер.
• folder: путь к папке сайта, в которой предполагается сохранить загруженный файл.

Все остальные параметры метода являются опциональными:

• format: формат, согласно которому загружаемому файлу назначается конечное имя. Если этот параметр не указан или указано значение false, используется то имя файла, которое было указано пользователем при загрузке файла, предварительно "обезопасенное" при помощи метода validateFilename. Если в качестве значения format был указан массив, то его поля используются для формирования имени файла на сервере. Массив должен быть ассоциативным и иметь ключи start, digits, prepend и append (начальное значение числового счетчика, минимальное количество знаков, префикс и суффикс имени). Пример допустимого формата можно найти в конце файла phpc/constant.php, переменная $uploadDefaultFormat.
• extensions: список допустимых типов файла, разрешенных для загрузки. Можно указать строку с допустимым типом (включая точку), либо строку со списком допустимых типов через запятую, либо массив со списком допустимых типов. По умолчанию этот параметр имеет значение константы UploadSafeExtensions, что позволяет загружать на сервер только файлы-изображения. Если вы укажете этому параметру значение false, все типы будут считаться допустимыми. Будьте осторожны, значение false позволит посетителю закачать на сервер файл любого типа, в том числе и PHP-скрипт!
• convert: этот параметр позволяет автоматически конвертировать одни типы файлов в другие при загрузке. Укажите в качестве значения ассоциативный массив, как для функции strtr(), например, .jpeg=>.jpg, либо укажите пустой массив, если автоматическая конвертация типов вам не нужна. По умолчанию этот параметр равен пустому массиву.
• maxsize: максимальный размер загружаемого файла в байтах. Если размер файла превышает ограничение, файл не будет загружен. По умолчанию этот параметр имеет значение false, что означает "ограничений на размер файла нет".
• normalize: нужно ли нормализовать значение параметра folder перед сохранением файла. По умолчанию этот параметр равен true, что позволяет указывать методу путь к папке в абсолютном формате.

Пример:

// Настраиваем параметры загрузки файла
$format=$uploadDefaultFormat;
$extensions=UploadSafeExtensions;
$convert=array(".jpeg"=>".jpg");
$maxsize=1000000;
// Выполняем загрузку файла
$image=$fileSystem->processUploadedFile(
  "imagedata","/images/upload",$format,$extensions,$convert,$maxsize);
// Проверяем, что получилось
if(!$image) die("Изображение имеет неверный формат.");
echo "Изображение доступно по ссылке: $image";