www.aleph1.co.uk Git - yaffs-website/blob - vendor/psr/http-message/src/UploadedFileInterface.php

   1 <?php
   2
   3 namespace Psr\Http\Message;
   4
   5 /**
   6  * Value object representing a file uploaded through an HTTP request.
   7  *
   8  * Instances of this interface are considered immutable; all methods that
   9  * might change state MUST be implemented such that they retain the internal
  10  * state of the current instance and return an instance that contains the
  11  * changed state.
  12  */
  13 interface UploadedFileInterface
  14 {
  15     /**
  16      * Retrieve a stream representing the uploaded file.
  17      *
  18      * This method MUST return a StreamInterface instance, representing the
  19      * uploaded file. The purpose of this method is to allow utilizing native PHP
  20      * stream functionality to manipulate the file upload, such as
  21      * stream_copy_to_stream() (though the result will need to be decorated in a
  22      * native PHP stream wrapper to work with such functions).
  23      *
  24      * If the moveTo() method has been called previously, this method MUST raise
  25      * an exception.
  26      *
  27      * @return StreamInterface Stream representation of the uploaded file.
  28      * @throws \RuntimeException in cases when no stream is available or can be
  29      *     created.
  30      */
  31     public function getStream();
  32
  33     /**
  34      * Move the uploaded file to a new location.
  35      *
  36      * Use this method as an alternative to move_uploaded_file(). This method is
  37      * guaranteed to work in both SAPI and non-SAPI environments.
  38      * Implementations must determine which environment they are in, and use the
  39      * appropriate method (move_uploaded_file(), rename(), or a stream
  40      * operation) to perform the operation.
  41      *
  42      * $targetPath may be an absolute path, or a relative path. If it is a
  43      * relative path, resolution should be the same as used by PHP's rename()
  44      * function.
  45      *
  46      * The original file or stream MUST be removed on completion.
  47      *
  48      * If this method is called more than once, any subsequent calls MUST raise
  49      * an exception.
  50      *
  51      * When used in an SAPI environment where $_FILES is populated, when writing
  52      * files via moveTo(), is_uploaded_file() and move_uploaded_file() SHOULD be
  53      * used to ensure permissions and upload status are verified correctly.
  54      *
  55      * If you wish to move to a stream, use getStream(), as SAPI operations
  56      * cannot guarantee writing to stream destinations.
  57      *
  58      * @see http://php.net/is_uploaded_file
  59      * @see http://php.net/move_uploaded_file
  60      * @param string $targetPath Path to which to move the uploaded file.
  61      * @throws \InvalidArgumentException if the $targetPath specified is invalid.
  62      * @throws \RuntimeException on any error during the move operation, or on
  63      *     the second or subsequent call to the method.
  64      */
  65     public function moveTo($targetPath);
  66
  67     /**
  68      * Retrieve the file size.
  69      *
  70      * Implementations SHOULD return the value stored in the "size" key of
  71      * the file in the $_FILES array if available, as PHP calculates this based
  72      * on the actual size transmitted.
  73      *
  74      * @return int|null The file size in bytes or null if unknown.
  75      */
  76     public function getSize();
  77
  78     /**
  79      * Retrieve the error associated with the uploaded file.
  80      *
  81      * The return value MUST be one of PHP's UPLOAD_ERR_XXX constants.
  82      *
  83      * If the file was uploaded successfully, this method MUST return
  84      * UPLOAD_ERR_OK.
  85      *
  86      * Implementations SHOULD return the value stored in the "error" key of
  87      * the file in the $_FILES array.
  88      *
  89      * @see http://php.net/manual/en/features.file-upload.errors.php
  90      * @return int One of PHP's UPLOAD_ERR_XXX constants.
  91      */
  92     public function getError();
  93
  94     /**
  95      * Retrieve the filename sent by the client.
  96      *
  97      * Do not trust the value returned by this method. A client could send
  98      * a malicious filename with the intention to corrupt or hack your
  99      * application.
 100      *
 101      * Implementations SHOULD return the value stored in the "name" key of
 102      * the file in the $_FILES array.
 103      *
 104      * @return string|null The filename sent by the client or null if none
 105      *     was provided.
 106      */
 107     public function getClientFilename();
 108
 109     /**
 110      * Retrieve the media type sent by the client.
 111      *
 112      * Do not trust the value returned by this method. A client could send
 113      * a malicious media type with the intention to corrupt or hack your
 114      * application.
 115      *
 116      * Implementations SHOULD return the value stored in the "type" key of
 117      * the file in the $_FILES array.
 118      *
 119      * @return string|null The media type sent by the client or null if none
 120      *     was provided.
 121      */
 122     public function getClientMediaType();
 123 }