git.m6w6.name Git - mdref/mdref-http/blob - http/Message/Body/addForm.md

   1 # http\Message\Body http\Message\Body::addForm([array $fields = NULL[, array $files = NULL]])
   2
   3 Add form fields and files to the message body.
   4
   5 > ***NOTE:***
   6 > Currently, http\Message\Body::addForm() creates "multipart/form-data" bodies.
   7
   8 ## Params:
   9
  10 * array $fields = NULL
  11   List of form fields to add.
  12
  13 * array $files = NULL
  14   List of form files to add.
  15
  16 $fields must look like:
  17
  18     [
  19       "field_name" => "value",
  20       "multi_field" => [
  21         "value1",
  22         "value2"
  23       ]
  24     ]
  25
  26 $files must look like:
  27
  28     [
  29       [
  30         "name" => "field_name",
  31         "type" => "content/type",
  32         "file" => "/path/to/file.ext"
  33       ], [
  34         "name" => "field_name2",
  35         "type" => "text/plain",
  36         "file" => "file.ext",
  37         "data" => "string"
  38       ], [
  39         "name" => "field_name3",
  40         "type" => "image/jpeg",
  41         "file" => "file.ext",
  42         "data" => fopen("/home/mike/Pictures/mike.jpg","r")
  43     ]
  44
  45 As you can see, a file structure must contain a "file" entry, which holds a file path, and an optional "data" entry, which may either contain a resource to read from or the actual data as string.
  46
  47 ## Returns:
  48
  49 * http\Message\Body, self.
  50
  51 ## Throws:
  52
  53 * http\Exception\InvalidArgumentException
  54 * http\Exception\RuntimeException
  55
  56 ## Example:
  57
  58     <?php
  59     $body = new http\Message\Body;
  60     $body->addForm([
  61       "field_name" => "value",
  62       "multi_field" => [
  63         "value1",
  64         "value2"
  65       ]
  66     ], [
  67       [
  68         "name" => "field_name",
  69         "type" => "application/octet-stream",
  70         "file" => "/run/gpm.pid"
  71       ], [
  72         "name" => "field_name2",
  73         "type" => "text/plain",
  74         "file" => "signature.txt",
  75         "data" => "--  \nMike\n"
  76       ], [
  77         "name" => "field_name3",
  78         "type" => "image/jpeg",
  79         "file" => "picture.jpg",
  80         "data" => fopen("/home/mike/Pictures/mike.jpg","r")
  81       ]
  82     ]);
  83
  84     echo $body;
  85     ?>
  86
  87 Yields:
  88
  89     --32260b4b.3fea9114
  90     Content-Disposition: form-data; name="field_name"
  91
  92     value
  93     --32260b4b.3fea9114
  94     Content-Disposition: form-data; name="multi_field[0]"
  95
  96     value1
  97     --32260b4b.3fea9114
  98     Content-Disposition: form-data; name="multi_field[1]"
  99
 100     value2
 101     --32260b4b.3fea9114
 102     Content-Disposition: form-data; name="field_name"; filename="gpm.pid"
 103     Content-Transfer-Encoding: binary
 104     Content-Type: application/octet-stream
 105
 106     316
 107
 108     --32260b4b.3fea9114
 109     Content-Disposition: form-data; name="field_name2"; filename="signature.txt"
 110     Content-Transfer-Encoding: binary
 111     Content-Type: text/plain
 112
 113     --
 114     Mike
 115
 116     --32260b4b.3fea9114
 117     Content-Disposition: form-data; name="field_name3"; filename="picture.jpg"
 118     Content-Transfer-Encoding: binary
 119     Content-Type: image/jpeg
 120
 121     ...JPEG...
 122     --32260b4b.3fea9114--