Classe Upload de Arquivo
Esta classe permite que o upload de arquivos. Vocë pode configurar várias preferências, restringindo o tipo e tamanho dos arquivos.
O Processo
Subir um arquivo envolve o processo geral:
- Um formulário de upload é exibido, permitndo ao usuário selecionar um arquivo para enviar.
- Quando o form é submetido, o arquivo é subido ao destino que você especificar.
- Durante o trajeto, o arquivo é validado para ter certeza que é permitido, baseado em suas preferências.
- Uma vez enviado o arquivo, ao usuário será exibida uma mensagem de sucesso.
Para demonstrar este processo, abaixo vai um breve tutorial. Logo após, você irá encontrar informações de referência.
Criando o Formulário de Upload
Usando um editor de texto, crie um formulário chamado upload_form.php. Nele, coloque este código e o salve na pasta applications/views/:
Você irá notar que estamos usando um assistente de formulário para criar a tag form de abertura. Uploads de arquivo requerem um formulário multiparte, por isso o assistente criará a sintaxe específica para você. Note também que temos uma variável $error. Com ela podemos mostrar mensagens de erro no caso do usuário fazer alguma coisa errada.
A Página de Sucesso
Usando um editor de texto, crie um formulário chamado upload_success.php. Nele, coloque este código e o salve na pasta applications/views/:
O Controller
Usando um editor de texto, crie um controller chamado upload.php. Nele, coloque este código e o salve em sua pasta applications/controllers/:
A Pasta Upload
Você irá precisar de uma pasta de destino para os arquivos enviados. Crie uma pasta na raiz do diretório de instalação do Code Igniter chamada uploads e configure sua permissão de arquivo para 777.
Experimente!
Para testar seu formulário, visite seu site usando uma URL semelhante a esta:
www.seu-site.com/index.php/upload/
Você deverá ver o formulário. Experimente enviar uma imagem (no formato jpg, gif, ou png). Se o caminho em seu controller estiver correto, deverá funcionar.
Guia de Referência
Inicializando a Classe Upload
Como a maioria das classes no Code Igniter, a classe Upload é inicializada em seu controller usando a função $this->load->library:
$this->load->library('upload');
Uma vez carregada, o objeto estará disponível usando: $this->upload
Configurando as Preferências
De forma similar às outras bibliotecas, você controlará o que é permitido enviar através de suas preferências. No controller que você construiu acima, você deve configurar o seguinte:
$config['upload_path'] = './uploads/';
$config['allowed_types'] = 'gif|jpg|png';
$config['max_size'] = '100';
$config['max_width'] = '1024';
$config['max_height'] = '768';
$this->load->library('upload', $config);
// Alternativamente você pode configurar as preferências chamando a função initialize. É útil se você auto-carregar a classe:
$this->upload->initialize($config);
As preferências acima devem ser quase auto-explicativas. Abaixo vai uma tabela descrevendo todas as preferências disponíveis.
Preferências
As seguintes preferências estão disponíveis. O valor default indica o que será caso você não especifique nada ali.
| Preferência | Valor%nbsp;Default | Opções | Descrição |
|---|---|---|---|
| upload_path | Nenhum | Nenhum | O caminho para o diretório onde o arquivo deve ser colocaod. O diretório deve ter permissão de escrita e o caminho pode ser absoluto ou relativo. |
| allowed_types | Nenhum | Nenhum | Os mime types correspondentes aos tipos de arquivo que você permite serem enviados. Geralente a extesão do arquivo pode ser usada como mime type. Separe-os com uma barra vertical. |
| overwrite | FALSE | TRUE/FALSE (boolean) | Se TRUE e se um arquivo com mesmo nome já existir, ele será sobrescrito. Se FALSE, um número será adicionado ao nome do arquivo para diferenciá-lo. |
| max_size | 0 | Nenhum | O tamanho máximo (em kilobytes) que um arquivo pode ter. Coloque zero para ilimitado. Nota: A maioria das instalações PHP têm seu próprio limite, como especificado em seu arquivo php.ini. Geralmente são 2MB (ou 2048 KB). |
| max_width | 0 | Nenhum | A largura máxima (em pixels) do arquivo. Coloque zero para ilimitada. |
| max_height | 0 | Nenhum | A altura máxima (em pixels) do arquivo. Coloque zero para ilimitada. |
| encrypt_name | FALSE | TRUE/FALSE (boolean) | Se TRUE, o nome do arquivo será convertido em uma string randomicamente criptografada. Pode ser útil se você quiser que arquivo seja salvo com um nome initeligível para a pessoa que o está enviando. |
| remove_spaces | TRUE | TRUE/FALSE (boolean) | Se TRUE, qualquer espaço no nome do arquivo será convertido em underscores. Esta é recomendada. |
Configurando preferências no arquivo config
Caso preferir não configurar as preferências do jeito mostrado acima, pode colocá-las num arquivo de configuração. Simplesmente crie um novo arquivo chamado upload.php e adicione a array $config. Salve então o arquivo em: config/upload.php e ele será usado automaticamente. Você NÃO precisará usar a função $this->upload->initialize se salvar suas preferências neste arquivo de configuração.
Referência para Funcões
As seguintes funções estão disponíveis
$this->upload->do_upload()
Executa o upload baseado nas preferências que você configurou. Nota: Por default, a rotina de upload espera que o arquivo venha a partir de um campo chamado userfile no formulário, e o formulário deve ser do tipo "multiparte":
<form method="post" action="some_action" enctype="multipart/form-data" />
Se você quiser configurar seu próprio nome para o campo, simplesmente passe seu valor para a função do_upload:
$field_name = "nome_do_seu_campo";
$this->upload->do_upload($field_name)
$this->upload->display_errors()
Captura qualquer mensagem de erro se a função do_upload() retornar FALSE. A função não dá echo automaticamente, ela retorna o dado para que então você faça o que desejar com ele.
Erros de Formatação
Por default, a função acima envolve qualquer erro com tags <p>. Mas você pode configurar seu próprio delimitador assim:
$this->upload->display_errors('<p>', '</p>');
$this->upload->data()
Esta é uma função assistente que retorna uma array contendo todos os dados relacionados com o arquivo enviado. Aqui está um protótipo dela:
Array
(
[file_name] => minhaimagem.jpg
[file_type] => image/jpeg
[file_path] => /caminho/para/seu/arquivo/
[full_path] => /caminho/para/seu/arquivo.jpg
[raw_name] => minhaimagem
[orig_name] => minhaimagem.jpg
[file_ext] => .jpg
[file_size] => 22.2
[is_image] => 1
[image_width] => 800
[image_height] => 600
[image_type] => jpeg
[image_size_str] => width="800" height="200"
)
Explicação
Esta é a explicação para os itens da array acima.
| Item | Descrição |
|---|---|
| file_name | O nome do arquivo que foi enviado incluidno sua extensão. |
| file_type | O mime type do arquivo. |
| file_path | O caminho absoluto do arquivo no servidor. |
| full_path | O caminho absoluto do arquivo no servidor incluindo seu nome. |
| raw_name | O nome do arquivo sem sua extensão. |
| orig_name | O nome original do arquivo. Para o caso de você tê-lo encriptado via preferências. |
| file_ext | A extensão do arquivo com ponto final. |
| file_size | O tamanho do arquivo em kilobytes. |
| is_image | Quando o arquivo for imagem ou não. 1 = imagem. 0 = não. |
| image_width | Largura da imagem. |
| image_heigth | Altura da imagem |
| image_type | Tipo da imagem. Tipicamente o nome de sua extensão sem o ponto final. |
| image_size_str | Uma string contendo a largura e altura. Útil para colocar nas propriedades da imagem, como numa tag. |