POST запрос, составное содержимое (multipart/form-data)
В жизни любого программиста попадаются задачки, которые человека цепляют. Вот не нравится стандартный метод решения и все! А порой бывает, что стандартные решения не подходят по какой-то причине. Некоторые люди обходят такие задачи стороной, другие же любят решать их. Можно даже сказать сами их находят. Одна из таких задач отсылка файла или несколько файлов методом POST.
Некоторые наверное скажут, эта задача совсем не задача. Ведь есть замечательная библиотека CURL, которая довольно простая и решает эту задачу легко! Но не спешите. Да, CURL мощная библиотека, да она загружает файлы, но… Как Вы знаете у нее есть маленькая особенность — файл должен быть размещен на жестком диске!
А теперь давайте представим себе такую ситуацию, Вы генерируете динамически файл или же он уже находится в памяти и нужно его отправить методом POST на удаленный Web сервер. Что же тогда получается? Перед его отправкой нужно его сохранить? Да именно так и поступило бы 90% программистов. Зачем искать лишние проблемы, если решение лежит на поверхности? Но мы же с Вами не из этих 90%! Мы же лучше, мы же можем решить любую задачку. Зачем нам лишнее действие? Во-первых, оно задействует не быструю файловую систему жесткого диска. Во-вторых, у нас может и не быть доступа к файловой системе или же там выделено слишком мало места.
Как же нам тогда решить эту задачку? Для этого надо взглянуть как собственно передаются данные методом POST. Единственный вариант решения — это передача файла составным запросом с помощью multipart/form-data. Этот метод хорошо описан в RFC7578. Давайте взглянем как будет выглядеть тело POST запроса multipart/form-data:
POST /form.html HTTP/1.1 Host: server.com Referer: http://server.com/form.html User-Agent: Mozilla Content-Type: multipart/form-data; boundary=-------------573cf973d5228 Content-Length: 288 Connection: keep-alive Keep-Alive: 300 (пустая строка) (отсутствующая преамбула) ---------------573cf973d5228 Content-Disposition: form-data; name="field" text ---------------573cf973d5228 Content-Disposition: form-data; name="file"; filename="sample.txt" Content-Type: text/plain Content file ---------------573cf973d5228--
Наше тело состоит из двух частей, в первой части мы передаем значение поля формы name=«field» равное: text. Во второй части мы передаем поле name=«file» с содержимым файла filename=«sample.txt»: Content file. В заголовке мы указываем формат содержимого POST запроса — Content-Type: multipart/form-data, строку разделитель составных частей: boundary=————-573cf973d5228 и длину сообщения — Content-Length: 288.
Осталось, собственно, написать программу реализующий этот метод. Так как мы люди умные и не пишем по сто раз одно и тоже в разных проектах, то оформим все в виде класса реализующий этот метод. Плюс к этому, расширим его для разных вариантов отправки как файлов, так и простых элементов формы. А что бы отличить среди массива POST данных, наличие файла, создадим отдельный файл — контейнер с содержимым файла и его данных (имя и расширение). Таким образом он будет выглядеть следующим образом:
class oFile < private $name; private $mime; private $content; public function __construct($name, $mime=null, $content=null) < // Проверяем, если $content=null, значит в переменной $name - путь к файлу if(is_null($content)) < // Получаем информацию по файлу (путь, имя и расширение файла) $info = pathinfo($name); // проверяем содержится ли в строке имя файла и можно ли прочитать файл if(!empty($info['basename']) && is_readable($name)) < $this->name = $info['basename']; // Определяем MIME тип файла $this->mime = mime_content_type($name); // Загружаем файл $content = file_get_contents($name); // Проверяем успешно ли был загружен файл if($content!==false) $this->content = $content; else throw new Exception('Don`t get content - "'.$name.'"'); > else throw new Exception('Error param'); > else < // сохраняем имя файла $this->name = $name; // Если не был передан тип MIME пытаемся сами его определить if(is_null($mime)) $mime = mime_content_type($name); // Сохраняем тип MIME файла $this->mime = $mime; // Сохраняем в свойстве класса содержимое файла $this->content = $content; >; > // Метод возвращает имя файла public function Name() < return $this->name; > // Метод возвращает тип MIME public function Mime() < return $this->mime; > // Метод возвращает содержимое файла public function Content() < return $this->content; > >;
Теперь собственно сам класс по формированию тела multipart/form-data для POST запроса:
class BodyPost < //Метод формирования части составного запроса public static function PartPost($name, $val) < $body = 'Content-Disposition: form-data; name="' . $name . '"'; // Проверяем передан ли класс oFile if($val instanceof oFile) < // Извлекаем имя файла $file = $val->Name(); // Извлекаем MIME тип файла $mime = $val->Mime(); // Извлекаем содержимое файла $cont = $val->Content(); $body .= '; filename="' . $file . '"' . "\r\n"; $body .= 'Content-Type: ' . $mime ."\r\n\r\n"; $body .= $cont."\r\n"; > else $body .= "\r\n\r\n".urlencode($val)."\r\n"; return $body; > // Метод формирующий тело POST запроса из переданного массива public static function Get(array $post, $delimiter='-------------0123456789') < if(is_array($post) && !empty($post)) < $bool = false; // Проверяем есть ли среди элементов массива файл foreach($post as $val) if($val instanceof oFile) ; if($bool) < $ret = ''; // Формируем из каждого элемента массива, составное тело POST запроса foreach($post as $name=>$val) $ret .= '--' . $delimiter. "\r\n". self::PartPost($name, $val); $ret .= "--" . $delimiter . "--\r\n"; > else $ret = http_build_query($post); > else throw new \Exception('Error input param!'); return $ret; > >;
Данный класс состоит из нескольких методов. Метод — PartPost формирует отдельные части составного запроса, а метод — Get объединяет эти части и формирует тело POST запроса в формате — multipart/form-data.
Теперь у нас есть универсальный класс для отправки тела POST запроса. Осталось написать программу использующую данный класс для отправки файлов на удаленный Web сервер. Воспользуемся библиотекой CURL:
// Подключаем класс-контейнер содержимого файла include "ofile.class.php"; // Подключаем класс для формирования тела POST запроса include "bodypost.class.php"; // Генерируем уникальную строку для разделения частей POST запроса $delimiter = '-------------'.uniqid(); // Формируем объект oFile содержащий файл $file = new oFile('sample.txt', 'text/plain', 'Content file'); // Формируем тело POST запроса $post = BodyPost::Get(array('field'=>'text', 'file'=>$file), $delimiter); // Инициализируем CURL $ch = curl_init(); // Указываем на какой ресурс передаем файл curl_setopt($ch, CURLOPT_URL, 'http://server/upload/'); // Указываем, что будет осуществляться POST запрос curl_setopt($ch, CURLOPT_POST, 1); // Передаем тело POST запроса curl_setopt($ch, CURLOPT_POSTFIELDS, $post); /* Указываем дополнительные данные для заголовка: Content-Type - тип содержимого, boundary - разделитель и Content-Length - длина тела сообщения */ curl_setopt($ch, CURLOPT_HTTPHEADER, array('Content-Type: multipart/form-data; boundary=' . $delimiter, 'Content-Length: ' . strlen($post))); // Отправляем POST запрос на удаленный Web сервер curl_exec($ch);Если CURL не подходит, то данную библиотеку можно применить и для отправки через сокеты. Ну и собственно ссылки на источники:
- сайт документации php.net
- статья CURL: POST запрос, составное содержимое
- википендия: multipart/form-data
- RFC7578
Multipart form-data
Multipart/form-data — это заголовок поля Content-Type, использующийся для обозначения множественного содержимого. Со стороны клиента чаще всего используются при отправке HTML-формы, файлов, данных, не входящих в набор ASCII, двоичных данных методом POST. Типичный пример: страницы отправки электронных писем со вложенными файлами. При отправке такого письма браузер формирует сообщение типа multipart/form-data, интегрируя в него как отдельные части, введённые пользователем, тему письма, адрес получателя, сам текст и вложенные файлы. Сообщение типа «multipart/form-data» состоит из нескольких частей, каждая из которых представляет содержимое отдельного элемента формы. Части отправляются обрабатывающему агенту в том порядке, в котором соответствующие управляющие элементы представлены в потоке документа. Границы частей не должны находиться в данных; обеспечение этого требования лежит вне области, рассматриваемой в данной спецификации. Каждая часть должна содержать:
- Заголовок «Content-Disposition», имеющий значение «form-data».
- Атрибут именования, определяющий имя соответствующего управляющего элемента. Имена управляющих элементов, изначально закодированные с использованием наборов символов, отличных от ASCII, могут кодироваться с помощью метода, описанного в RFC 2045
пример отправки письма с вложенными картинками:
Основная статья: MIME
POST /send-message.html HTTP/1.1 Host: mail.example.com Referer: http://mail.example.com/send-message.html User-Agent: BrowserForDummies/4.67b Content-Type: multipart/form-data; boundary=Asrf456BGe4h Content-Length: (суммарный объём включая дочерние заголовки) Connection: keep-alive Keep-Alive: 300 (пустая строка) (отсутствующая преамбула) --Asrf456BGe4h Content-Disposition: form-data; name="DestAddress" (пустая строка) brutal-vasya@example.com --Asrf456BGe4h Content-Disposition: form-data; name="MessageTitle" (пустая строка) Я негодую --Asrf456BGe4h Content-Disposition: form-data; name="MessageText" (пустая строка) Привет, Василий! Твой ручной лев, которого ты оставил у меня на прошлой неделе, разодрал весь мой диван. Пожалуйста забери его скорее! Во вложении две фотки с последствиями. --Asrf456BGe4h Content-Disposition: form-data; name="AttachedFile1"; filename="horror-photo-1.jpg" Content-Type: image/jpeg (пустая строка) (двоичное содержимое первой фотографии) --Asrf456BGe4h Content-Disposition: form-data; name="AttachedFile2"; filename="horror-photo-2.jpg" Content-Type: image/jpeg (пустая строка) (двоичное содержимое второй фотографии) --Asrf456BGe4h-- (отсутствующий эпилог - пустая строка)
так же следует отметить, что boundary — это последовательность байт, которые не должны встречаться в самом файле. Обычно клиент или браузер генерирует эту последовательность случайно или по специальному алгоритму
Ссылки
- Появились в 1982 году
- Электронная почта
- Форматы данных
- HTML
- Протокол HTTP
Wikimedia Foundation . 2010 .
FormData
В этой главе речь пойдёт об отправке HTML-форм: с файлами и без, с дополнительными полями и так далее. Объекты FormData помогут нам с этим. Как вы, наверняка, догадались по его названию, это объект, представляющий данные HTML формы.
let formData = new FormData([form]);Если передать в конструктор элемент HTML-формы form , то создаваемый объект автоматически прочитает из неё поля.
Его особенность заключается в том, что методы для работы с сетью, например fetch , позволяют указать объект FormData в свойстве тела запроса body .
Он будет соответствующим образом закодирован и отправлен с заголовком Content-Type: multipart/form-data .
То есть, для сервера это выглядит как обычная отправка формы.
Отправка простой формы
Давайте сначала отправим простую форму.
Как вы видите, код очень компактный:
В этом примере серверный код не представлен, он за рамками этой статьи, он принимает POST-запрос с данными формы и отвечает сообщением «Пользователь сохранён».
Методы объекта FormData
С помощью указанных ниже методов мы можем изменять поля в объекте FormData :
- formData.append(name, value) – добавляет к объекту поле с именем name и значением value ,
- formData.append(name, blob, fileName) – добавляет поле, как будто в форме имеется элемент , третий аргумент fileName устанавливает имя файла (не имя поля формы), как будто это имя из файловой системы пользователя,
- formData.delete(name) – удаляет поле с заданным именем name ,
- formData.get(name) – получает значение поля с именем name ,
- formData.has(name) – если существует поле с именем name , то возвращает true , иначе false
Технически форма может иметь много полей с одним и тем же именем name , поэтому несколько вызовов append добавят несколько полей с одинаковыми именами.
Ещё существует метод set , его синтаксис такой же, как у append . Разница в том, что .set удаляет все уже имеющиеся поля с именем name и только затем добавляет новое. То есть этот метод гарантирует, что будет существовать только одно поле с именем name , в остальном он аналогичен .append :
- formData.set(name, value) ,
- formData.set(name, blob, fileName) .
Поля объекта formData можно перебирать, используя цикл for..of :
let formData = new FormData(); formData.append('key1', 'value1'); formData.append('key2', 'value2'); // Список пар ключ/значение for(let [name, value] of formData) < alert(`$= $`); // key1=value1, потом key2=value2 >Отправка формы с файлом
Объекты FormData всегда отсылаются с заголовком Content-Type: multipart/form-data , этот способ кодировки позволяет отсылать файлы. Таким образом, поля тоже отправляются, как это и происходит в случае обычной формы.
Пример такой формы:
Картинка: Отправка формы с Blob-данными
Ранее в главе Fetch мы видели, что очень легко отправить динамически сгенерированные бинарные данные в формате Blob . Мы можем явно передать её в параметр body запроса fetch .
Но на практике бывает удобнее отправлять изображение не отдельно, а в составе формы, добавив дополнительные поля для имени и другие метаданные.
Кроме того, серверы часто настроены на приём именно форм, а не просто бинарных данных.
В примере ниже посылается изображение из и ещё несколько полей, как форма, используя FormData :
Пожалуйста, обратите внимание на то, как добавляется изображение Blob :
formData.append("image", imageBlob, "image.png");Это как если бы в форме был элемент и пользователь прикрепил бы файл с именем «image.png» (3-й аргумент) и данными imageBlob (2-й аргумент) из своей файловой системы.
Сервер прочитает и данные и файл, точно так же, как если бы это была обычная отправка формы.
Итого
Объекты FormData используются, чтобы взять данные из HTML-формы и отправить их с помощью fetch или другого метода для работы с сетью.
Мы можем создать такой объект уже с данными, передав в конструктор HTML-форму – new FormData(form) , или же можно создать объект вообще без формы и затем добавить к нему поля с помощью методов:
- formData.append(name, value)
- formData.append(name, blob, fileName)
- formData.set(name, value)
- formData.set(name, blob, fileName)
Отметим две особенности:
- Метод set удаляет предыдущие поля с таким же именем, а append – нет. В этом их единственное отличие.
- Чтобы послать файл, нужно использовать синтаксис с тремя аргументами, в качестве третьего как раз указывается имя файла, которое обычно, при , берётся из файловой системы.
- formData.delete(name)
- formData.get(name)
- formData.has(name)
Атрибут enctype
Определяет способ кодирования данных формы при их отправке на сервер. Обычно устанавливать значение атрибута enctype не требуется, данные вполне правильно понимаются на стороне сервера. Однако если используется поле для отправки файла ( input type=»file» ), следует определить атрибут enctype как multipart/form-data .
Синтаксис
Значения
application/x-www-form-urlencoded Вместо пробелов ставится +, символы вроде русских букв кодируются их шестнадцатеричными значениями (например, %D0%90%D0%BD%D1%8F вместо Аня). multipart/form-data Данные не кодируются. Это значение применяется при отправке файлов. text/plain Пробелы заменяются знаком +, буквы и другие символы не кодируются.
Значение по умолчанию
Пример
Результат данного примера показан на рис. 1.
Рис. 1. Поле для отправки файла
Браузеры
| 4 | 12 | 1 | 4 | 3 | 1 |
В таблице браузеров применяются следующие обозначения.
- — элемент полностью поддерживается браузером;
- — элемент браузером не воспринимается и игнорируется;
- — при работе возможно появление различных ошибок, либо элемент поддерживается с оговорками.
Число указывает версию браузреа, начиная с которой элемент поддерживается.