Manual do PHP
Anterior |  | Próxima

# Capítulo 20. Gerenciar o upload de arquivos

# Upload de arquivos com o método POST

O PHP é capaz de receber o upload de qualquer browser que siga a norma RFC-1867 (o que inclui Netscape Navigator 3 ou posterior, Microsoft Internet Explorer 3 com um patch da Microsoft, ou posterior sem patch). Isto permite que se faça o upload 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 de arquivo e o que fazer com o arquivo após seu upload.

> Nota Sobre Configurações Relacionadas: Veja também file_uploads, upload_max_filesize, upload_tmp_dir, post_max_size, max_input_time no `php.ini`

Note que o PHP também suporta o método PUT para upload de arquivos como o usado por Netscape Composer e W3C's Amaya clients. Veja Suporte ao Método Put para maiores detalhes.

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

Exemplo 20-1. Formulário para Upload de Arquivo
    <form enctype="multipart/form-data" action="_URL_" method="post">
    <input type="hidden" name="MAX_FILE_SIZE" value="30000" />
    Send this file: <input name="userfile" type="file" />
    <input type="submit" value="Send File" />
    </form>

A "_URL_" no exemplo acima deve ser substituida e apontar para um arquivo PHP. O campo escondido MAX_FILE_SIZE (medido em bytes) deve preceder o campo de input do arquivo, e seu valor é o tamanho limite aceito para o arquivo. Também tenha certeza que seu formulário de upload de arquivo tenha enctype="multipart/form-data" em outro caso o upload do arquivo não irá funcionar.

Atenção
O valor de MAX_FILE_SIZE é um aviso para o browser. É fácil contornar este limite. Então não conte que o browser irá obedecer a sua vontade. O que foi estabelecido para maximum-size no PHP não pode ser enganado. Mas você deve adicionar MAX_FILE_SIZE em qualquer caso, já que salva os usuários do problema de esperar por um grande arquivo ser transferido somente para descobrir depois de tudo que ele é muito grande.

As variáveis definidas para o upload de arquivos são diferentes dependendo da versão e da configuração. A autoglobal $_FILES existe desde o PHP 4.1.0. A array $HTTP_POST_FILES existe desde o PHP 4.0.0. Estas array irão conter toda a informação do upload do arquivo. Usar $_FILES é preferido. Se a opção register_globals é on, os nomes de variáveis relacionados também existirão. O padrão de register_globals é off desde o PHP 4.2.0.

Os conteúdos de $_FILES do nosso script de exemplo é como segue. Note que isso assume que o nome do upload do arquivo é userfile, como o usado no exemplo acima. Pode ser qualquer nome.

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

  O nome original do arquivo no computador do usuário.

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

  O tipo mime do arquivo, se o browser deu esta informação. Um exemplo pode ser "image/gif".

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

  O tamanho, em bytes, do arquivo.

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

  O nome temporário do arquivo, como foi guardado no servidor.

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

  O código de erro associado a este upload de arquivo. ['error'] foi adicionado no PHP 4.2.0

> Nota: Em versões anteriores a 4.1.0 o nome era $HTTP_POST_FILES e não é uma variável autoglobal como $_FILES é. PHP 3 não suporta $HTTP_POST_FILES.

Quando register_globals esta em on no `php.ini`, variáveis adicionais estão disponíveis. Por exemplo, $userfile_name será igual a $_FILES['userfile']['name'], $userfile_type será igual a $_FILES['userfile']['type'], etc. Lembre-se que desde o PHP 4.2.0, o padrão para register_globals é off. É preferível não depender desta opção.

Os arquivos serão guardados no diretório temporário do servidor, a menos que outro lugar seja especificado com a opção upload_tmp_dir no `php.ini`. O diretório padrão do servidor pode ser mudado se mudando o valor da variável de ambiente TMPDIR no ambiente onde o PHP esta sendo executado PHP. Mudando-a com putenv() de um script PHP não irá funcionar. Esta variável de ambiente também pode ser usada para se ter certeza que outras operações estão funcionando no arquivo do upload.

Note que deve se definir upload_temp_dir no `php.ini` ou TMPDIR, não podendo estarem ambos vazios, sendo recomendado no mínimo upload_tmp_dir.

Exemplo 20-2. Validando o upload de arquivos Veja também as funções is_uploaded_file() e move_uploaded_file() para maiores informações. O seguinte exemplo irá processar o envio de um arquivo que vem de um formulário.
`<?php // Nas versões do PHP anteriores a 4.1.0, deve ser usado $HTTP_POST_FILES // ao invés de $_FILES. $uploaddir = '/var/www/uploads/'; $uploadfile = $uploaddir . $_FILES['userfile']['name']; print "<pre>"; if (move_uploaded_file($_FILES['userfile']['tmp_name'], $uploaddir . $_FILES['userfile']['name'])) { print "O arquivo é valido e foi carregado com sucesso. Aqui esta alguma informação:\n"; print_r($_FILES); } else { print "Possivel ataque de upload! Aqui esta alguma informação:\n"; print_r($_FILES); } print "</pre>"; ?>`

O script PHP que irá receber o arquivo do upload deve implementar qualquer lógica que for necessária para determinar o que deve ser feito com o arquivo do upload. 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'] que não sejam de um certo tipo. Desde o PHP 4.2.0, você pode usar $_FILES['userfile']['error'] e planejar a sua lógica de acordo com os códigos de erro. Qualquer que seja a lógica, você deve excluir o arquivo do diretório temporário ou move-lo para outro lugar.

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.

O arquivo será excluído do diretório temporário ao fim do script se não tiver sido movido ou renomeado.

Anterior | Principal | Próxima
Dealing with XForms | Acima | Explicação das mensagens de erro