PHP 5.4.36 Released

Upload de arquivos com o método POST

Este recurso permite realizar uploads de arquivos de texto e binários. Com as funções de autenticação e manipulação de arquivos do PHP, você tem o controle completo de quem pode fazer o upload e o que deve ser feito com o arquivo após o upload estar completo.

O PHP é capaz de receber uploads de arquivos de qualquer browser compatível com RFC-1867.

Nota: Nota Sobre Configurações Relacionadas

Veja também as diretivas file_uploads, upload_max_filesize, upload_tmp_dir, post_max_size, max_input_time no php.ini

O PHP também suporta o método PUT para upload de arquivos como o usado pelo Netscape Composer e clientes para Amaya W3C. Veja Suporte ao Método Put para maiores detalhes.

Exemplo #1 Formulário para Upload de Arquivo

Uma interface para upload de arquivo pode ser criada com um formulário especial parecido com este:

<!-- O tipo de encoding de dados, enctype, DEVE ser especificado abaixo -->
<form enctype="multipart/form-data" action="__URL__" method="POST">
    <!-- MAX_FILE_SIZE deve preceder o campo input -->
    <input type="hidden" name="MAX_FILE_SIZE" value="30000" />
    <!-- O Nome do elemento input determina o nome da array $_FILES -->
    Enviar esse arquivo: <input name="userfile" type="file" />
    <input type="submit" value="Enviar arquivo" />
</form>

O parâmetro __URL__ no exemplo acima deve ser substituido e apontar para um arquivo PHP.

O campo escondido (input type="hidden") MAX_FILE_SIZE (medido em bytes) deve preceder o campo de input de arquivo (input type="file"), e o seu valor é o tamanho limite aceito pelo PHP. Este elemento do formulário deve sempre ser usado para evitar que usuários tenham o problema de ter que esperar pela transferência de um arquivo para só então descobrir que ele era grande demais e a transferência falhar. Fique ciente: é muito simples burlar esse parâmetro pelo lado do navegador, portanto nunca dependa exclusivamente desse recurso para bloquear arquivos com maior tamanho. Isso é um recurso meramente conveniente para usuários da aplicação no lado do cliente. Os parâmetros do PHP (no servidor) para "maximum-size", no entanto, não podem ser burlados.

Nota:

Tenha certeza que seu formulário de upload tenha o atributo enctype="multipart/form-data" por outro lado o upload não irá funcionar.

A variável global $_FILES conterá toda a informação do arquivo enviado. O conteúdo do formulário de exemplo acima será como o exemplo descrito abaixo. Note que isso assume o nome do arquivo enviado userfile, como foi usado no script de exemplo acima, contudo isso pode ter qualquer nome.

$_FILES['userfile']['name']

O nome original do arquivo na máquina do cliente.

$_FILES['userfile']['type']

O tipo mime do arquivo, se o navegador fornecer essa informação. Um exemplo poderia ser "image/gif". O tipo mime no entanto não é verificado pelo PHP portanto não considere que esse valor será concedido.

$_FILES['userfile']['size']

O tamanho, em bytes, do arquivo enviado.

$_FILES['userfile']['tmp_name']

O nome temporário com o qual o arquivo enviado foi armazenado no servidor.

$_FILES['userfile']['error']

O código de erro associado a esse upload de arquivo.

Os arquivos serão guardados por padrão no diretório temporário do servidor, a menos que outro local seja especificado através da diretiva upload_tmp_dir no php.ini. O diretório padrão do servidor pode ser alterado através da configuração da variável de ambiente TMPDIR no ambiente onde o PHP esta sendo executado. Configurando isso usando putenv() em um script PHP não irá funcionar. Esta variável de ambiente também pode ser usada para certificar que outras operações estão funcionando nos arquivos enviados.

Exemplo #2 Validando o upload de arquivos

Veja também as funções is_uploaded_file() e move_uploaded_file() para maiores informações. O exemplo a seguir irá processar o upload de um arquivo que vem de um formulário.

<?php
// Nas versões do PHP anteriores a 4.1.0, $HTTP_POST_FILES deve ser utilizado ao invés
// de $_FILES.

$uploaddir '/var/www/uploads/';
$uploadfile $uploaddir basename($_FILES['userfile']['name']);

echo 
'<pre>';
if (
move_uploaded_file($_FILES['userfile']['tmp_name'], $uploadfile)) {
    echo 
"Arquivo válido e enviado com sucesso.\n";
} else {
    echo 
"Possível ataque de upload de arquivo!\n";
}

echo 
'Aqui está mais informações de debug:';
print_r($_FILES);

print 
"</pre>";

?>

O script PHP que recebe o arquivo enviado deve implementar qualquer lógica que for necessária para determinar o que deve ser feito com o arquivo enviado. Você pode, por exemplo, usar a variável $_FILES['userfile']['size'] para descartar qualquer arquivo que seja muito pequeno ou muito grande. Você pode usar a variável $_FILES['userfile']['type'] para descartar arquivos imcompatíveis com um determinado critério, mas use isso apenas como a primeira de uma serie de verificações, porque esse valor está totalmente sob o controle do cliente e não é verificado pelo PHP. Você também pode usar $_FILES['userfile']['error'] e planejar sua lógica de acordo com os Códigos de erro. Independente da lógica, você também deve apagar o arquivo do diretório temporário ou movê-lo para outro local.

Se nenhum arquivo for selecionado em seu formulário, o PHP irá retornar $_FILES['userfile']['size'] como 0, e $_FILES['userfile']['tmp_name'] como "none" (nenhum).

O arquivo será excluído do diretório temporário ao fim da requisição se ele não for movido ou renomeado.

Exemplo #3 Enviando uma array de arquivos

O PHP suporta array HTML mesmo com arquivos.

<form action="" method="post" enctype="multipart/form-data">
<p>Imagens:
<input type="file" name="pictures[]" />
<input type="file" name="pictures[]" />
<input type="file" name="pictures[]" />
<input type="submit" value="Enviar" />
</p>
</form>
<?php
foreach ($_FILES["pictures"]["error"] as $key => $error) {
    if (
$error == UPLOAD_ERR_OK) {
        
$tmp_name $_FILES["pictures"]["tmp_name"][$key];
        
$name $_FILES["pictures"]["name"][$key];
        
move_uploaded_file($tmp_name"data/$name");
    }
}
?>

O Progresso do upload de arquivos pode ser implementado usando a Sessão do Progresso de Upload (Session Upload Progress).

add a note add a note

User Contributed Notes 11 notes

up
26
daevid at daevid dot com
5 years ago
I think the way an array of attachments works is kind of cumbersome. Usually the PHP guys are right on the money, but this is just counter-intuitive. It should have been more like:

Array
(
    [0] => Array
        (
            [name] => facepalm.jpg
            [type] => image/jpeg
            [tmp_name] => /tmp/phpn3FmFr
            [error] => 0
            [size] => 15476
        )

    [1] => Array
        (
            [name] =>
            [type] =>
            [tmp_name] =>
            [error] => 4
            [size] =>
        )
)

and not this
Array
(
    [name] => Array
        (
            [0] => facepalm.jpg
            [1] =>
        )

    [type] => Array
        (
            [0] => image/jpeg
            [1] =>
        )

    [tmp_name] => Array
        (
            [0] => /tmp/phpn3FmFr
            [1] =>
        )

    [error] => Array
        (
            [0] => 0
            [1] => 4
        )

    [size] => Array
        (
            [0] => 15476
            [1] => 0
        )
)

Anyways, here is a fuller example than the sparce one in the documentation above:

<?php
foreach ($_FILES["attachment"]["error"] as $key => $error)
{
      
$tmp_name = $_FILES["attachment"]["tmp_name"][$key];
       if (!
$tmp_name) continue;

      
$name = basename($_FILES["attachment"]["name"][$key]);

    if (
$error == UPLOAD_ERR_OK)
    {
        if (
move_uploaded_file($tmp_name, "/tmp/".$name) )
           
$uploaded_array[] .= "Uploaded file '".$name."'.<br/>\n";
        else
           
$errormsg .= "Could not move uploaded file '".$tmp_name."' to '".$name."'<br/>\n";
    }
    else
$errormsg .= "Upload error. [".$error."] on file '".$name."'<br/>\n";
}
?>
up
10
michael
5 years ago
Just a little note, when I was trying to get this to work on my webserver I got error telling me the permissions were wrong, I checked and couldn't see anything wrong then I thought to try "./" for my upload directory instead of the full address which was something like "home/username/public_html/uploaddir". This will save it in the same directory as your script for the program above thats something like

<?php
// In PHP versions earlier than 4.1.0, $HTTP_POST_FILES should be used instead
// of $_FILES.

$uploaddir = './';//<----This is all I changed
$uploadfile = $uploaddir . basename($_FILES['userfile']['name']);

echo
'<pre>';
if (
move_uploaded_file($_FILES['userfile']['tmp_name'], $uploadfile)) {
    echo
"File is valid, and was successfully uploaded.\n";
} else {
    echo
"Possible file upload attack!\n";
}

echo
'Here is some more debugging info:';
print_r($_FILES);

print
"</pre>";

?>

I know something trivial but when your new to this, those kind of things elude you.
up
2
eslindsey at gmail dot com
5 years ago
Also note that since MAX_FILE_SIZE hidden field is supplied by the browser doing the submitting, it is easily overridden from the clients' side.  You should always perform your own examination and error checking of the file after it reaches you, instead of relying on information submitted by the client.  This includes checks for file size (always check the length of the actual data versus the reported file size) as well as file type (the MIME type submitted by the browser can be inaccurate at best, and intentionally set to an incorrect value at worst).
up
0
Anonymous
23 days ago
For the love of god, don't do what michael suggests in http://php.net/manual/en/features.file-upload.post-method.php#94973 or you will be instantly pwned by someone uploading a php-shell to your script dir.

When the mods come to delete this note for violating the don't-refer-to-another-note rule, please please /please/ delete michael's note too.
up
-2
Age Bosma
3 years ago
"If no file is selected for upload in your form, PHP will return $_FILES['userfile']['size'] as 0, and $_FILES['userfile']['tmp_name'] as none."

Note that the situation above is the same when a file exceeding the MAX_FILE_SIZE hidden field is being uploaded. In this case $_FILES['userfile']['size'] is also set to 0, and $_FILES['userfile']['tmp_name'] is also empty. The difference would only be the error code.
Simply checking for these two conditions and assuming no file upload has been attempted is incorrect.

Instead, check if $_FILES['userfile']['name'] is set or not. If it is, a file upload has at least been attempted (a failed attempt or not). If it is not set, no attempt has been made.
up
-2
claude dot pache at gmail dot com
5 years ago
Note that the MAX_FILE_SIZE hidden field is only used by the PHP script which receives the request, as an instruction to reject files larger than the given bound. This field has no significance for the browser, it does not provide a client-side check of the file-size, and it has nothing to do with web standards or browser features.
up
-4
Anonymous
1 year ago
Normalizing $_FILES structure:

<?php
    $files
= [];
   
$fix = function (&$files, $values, $prop) use (&$fix) {
        foreach (
$values as $key => $value) {
            if (
is_array($value)) {
               
$fix($files[$key], $value, $prop);
            } else {
               
$files[$key][$prop] = $value;
            }
        }
    };
    foreach (
$_FILES as $name => $props) {
        foreach (
$props as $prop => $value) {
            if (
is_array($value)) {
               
$fix($files[$name], $value, $prop);
            } else {
               
$files[$name][$prop] = $value;
            }
        }
    }
?>
up
-5
gustavo at roskus dot com
3 years ago
Some hosting does not have permission to use the move_uploaded_file function should replace the copy function
up
-6
Mark
4 years ago
$_FILES will be empty if a user attempts to upload a file greater than post_max_size in your php.ini

post_max_size should be >= upload_max_filesize in your php.ini.
up
-12
mail at markuszeller dot com
3 years ago
If you want to increase the upload size, it could make sense to allow it only to a specified directory and not in the php.ini for the whole domain or server. In my case it worked very well placing that into the .htaccess file like this:

php_value    upload_max_filesize    100M
php_value    post_max_size    101M

Remember, post_max_size must be bigger than the upload_max_filesize.
up
-14
zingaburga at hotmail dot com
3 years ago
The documentation is a little unclear about the MAX_FILE_SIZE value sent in the form with multiple file input fields.  The following is what I have found through testing - hopefully it may clarify it for others.

The MAX_FILE_SIZE is applied to each file (not the total size of all files) and to all file inputs which appear after it.  This means that it can be overridden for different file fields.  You can also disable it by sending no number, or sending 0 (probably anything that == '0' if you think about it).

Example:

<form enctype="multipart/form-data" action="." method="POST">
  <!-- no maximum size for userfile0 -->
  <input name="userfile0" type="file" />

  <input type="hidden" name="MAX_FILE_SIZE" value="1000" />
  <!-- maximum size for userfile1 is 1000 bytes -->
  <input name="userfile1" type="file" />
  <!-- maximum size for userfile2 is 1000 bytes -->
  <input name="userfile2" type="file" />

  <input type="hidden" name="MAX_FILE_SIZE" value="2000" />
  <!-- maximum size for userfile3 is 2000 bytes -->
  <input name="userfile3" type="file" />

  <input type="hidden" name="MAX_FILE_SIZE" value="0" />
  <!-- no maximum size for userfile4 -->
  <input name="userfile4" type="file" />
</form>
To Top