Request

Classe Request para lidar com solicitações HTTP do cliente.

No Hello, uma "request" refere-se a uma solicitação HTTP feita ao aplicativo. Quando um usuário acessa um site, por exemplo, ele envia uma solicitação HTTP para o servidor do site. O Hello é um framework PHP que fornece recursos para lidar com solicitações HTTP, incluindo a capacidade de recuperar dados enviados pelos usuários em um formulário, verificar se uma solicitação é autorizada e manipular as informações recebidas.

O objeto "Request" do Hello é uma representação dessa solicitação HTTP, contendo informações como o método HTTP utilizado (GET, POST, PUT, DELETE, etc.), o URL solicitado, as informações do cabeçalho da solicitação e quaisquer dados enviados no corpo da solicitação. O Hello fornece uma série de recursos para trabalhar com objetos Request, incluindo a validação de dados recebidos, a criação de respostas personalizadas e o gerenciamento de erros de validação.

use Kernel\Http\Request;

Recuperar um input field enviado do tipo input ou textarea

$request = new Request;

$request->get('name');

//Ou você pode usar assim
$request->name;

//Para recuperar todos
$request->all();
//Output array

Recuperar um header especifico. 

$request->getHeader('nome-header');

Recuperar todos os headers.

$request->getHeaderAll();

OBS: $request->nome = 'João' é equivalente a $request->set('nome', 'João').

A classe Request possui os seguintes métodos públicos:

string getHeader($key)

Retorna o valor do cabeçalho HTTP especificado pelo parâmetro $key. Se o cabeçalho não existir, retorna null.

array getHeaderAll()

Retorna um array associativo contendo todos os cabeçalhos HTTP da requisição.

array all()

Retorna um array contendo todos os dados da requisição, exceto a chave 'uri'.

bool has(string $key)

Verifica se existe um valor associado à chave especificada pelo parâmetro $key. Retorna true se existir e false caso contrário.

void set(string $key, $value = null)

Define um valor associado à chave especificada pelo parâmetro $key. O parâmetro opcional $value define o valor a ser atribuído.

string get(string $key)

Retorna o valor associado à chave especificada pelo parâmetro $key. Se a chave não existir, retorna null.

void validate($validations, $messages = array())

Valida os dados da requisição de acordo com as regras de validação especificadas no parâmetro $validations. O parâmetro opcional $messages permite definir mensagens personalizadas de erro para cada regra de validação.

array except($excepts, array $data = null)

Retorna um novo array contendo os dados da requisição, excluindo as chaves especificadas no parâmetro $excepts. O parâmetro opcional $data permite especificar um array de dados para realizar a exclusão, caso esse parâmetro seja omitido, o método usará o método all() para acessar os dados da requisição HTTP atual.

array only(array $onlys, array $data = null)

Retorna um novo array contendo apenas as chaves especificadas no parâmetro $onlys, juntamente com seus respectivos valores, a partir dos dados da requisição. O parâmetro opcional $data permite especificar um array de dados para realizar a exclusão, caso esse parâmetro seja omitido, o método usará o método all() para acessar os dados da requisição HTTP atual.

array errors()

Retorna um array contendo as mensagens de erro das validações realizadas. As mensagens são definidas anteriormente usando o método validate().

bool fails()

Verifica se a validação falhou. Retorna true se houver erros de validação e false caso contrário.

array validated(array $excepts = array())

Retorna um array contendo os dados validados da requisição, excluindo as chaves especificadas no parâmetro `$except'

Validações

As validações de requisições são uma abordagem simples para validar as entradas dos usuários. É uma prática importante para garantir que os dados inseridos sejam corretos e coerentes. Alguns exemplos de valores que podem ser validados incluem endereços de e-mail, datas, horários e números de telefone.

Para realizar a validação, você pode utilizar o método validate da classe Request, que recebe dois argumentos no formato de array associativo. O primeiro argumento contém um array onde as chaves são os nomes dos campos do formulário a serem validados e os valores são os tipos de validação. Você pode colocar quantos tipos de validação forem necessários para cada campo.

Para cada tipo de validação nativa, existe uma mensagem padrão associada a ela, que é retornada em formato de array pelo método errors em caso de falha. No entanto, caso você deseje personalizar as mensagens retornadas, é possível passar o segundo argumento, que também é um array associativo. As chaves desse array são os nomes dos campos a serem validados, e os valores são as mensagens personalizadas.

Para cada tipo de validação, você deve informar no array o nome do campo como chave, seguido pelo nome do tipo de validação.

Exemplo de utilização:

// Exemplo de validação de um formulário de registro

$request = new Request();

$campos = [
    'nome' => 'required',
    'email' => 'required|email',
    'telefone' => 'required|phone',
    'data_nascimento' => 'required|date',
];

$mensagensPersonalizadas = [
    'nome.required' => 'O campo nome é obrigatório.',
    'email.email' => 'Por favor, insira um e-mail válido.',
    'telefone.phone' => 'O número de telefone fornecido é inválido.',
    'data_nascimento.date' => 'Insira uma data de nascimento válida.',
];

$request->validate($campos, $mensagensPersonalizadas);

$errors = 
if ($request->fails()) {
     //Retorna o array com os erros
     return $request->errors();
} else {
    // Retorna os dados que foram validados válidos
    return $request->validated(); 
}

Neste exemplo, definimos uma série de campos a serem validados, como nome, e-mail, telefone e data de nascimento. Utilizamos os tipos de validação nativos required, email, phone e date. Também personalizamos as mensagens de erro para cada campo, caso a validação falhe.

Após chamar o método validate, podemos verificar se existem erros utilizando o método errors. Se o array de erros estiver vazio, significa que todos os campos foram validados com sucesso e podemos prosseguir com o processamento dos dados. Caso contrário, podemos tratar os erros e exibir as mensagens correspondentes aos usuários.

Tipos nativos de validação disponíveis

  • required: O campo é obrigatório.

  • email: O campo deve conter um endereço de e-mail válido.

  • numeric: O campo deve ser um número.

  • integer: O campo deve ser um número inteiro.

  • digits: O campo deve ter um número específico de dígitos.

  • min: O valor mínimo permitido para o campo.

  • max: O valor máximo permitido para o campo.

  • is: O campo deve corresponder a um valor específico.

  • not_is: O campo não deve corresponder a nenhum valor específico.

  • alpha: O campo deve conter somente caracteres alfabéticos.

  • alpha_num: O campo deve conter somente caracteres alfanuméricos.

  • alpha_dash: O campo deve conter somente caracteres alfanuméricos, sublinhados e hífens.

  • regex: O campo deve corresponder a uma expressão regular específica.

  • confirmed: O campo deve ser confirmado por outro campo com o mesmo nome seguido de "_confirmation".

  • unique: O valor do campo deve ser único em uma determinada tabela de banco de dados.

  • exists: O valor do campo deve existir em uma determinada tabela de banco de dados.

  • file: Você deve fazer o upload de arquivo válido.

    Observação: Esse validador não se comporta adequadamente quando combinado com o validador "required". Isso ocorre porque o validador "file" já exige a presença de um arquivo válido. Ao usar a combinação de "required" com "file", o validador "required" entenderá que não há valor para o arquivo, uma vez que o "required" é destinado a validar entradas de dados do tipo "inputs", excluindo o tipo de arquivo.

  • size: O tamanho de arquivo é muito grande. Informe o tamanho do arquivo por bytes.

  • extension: Extensão de arquivo não permitida para upload. Informe as extensões separadas por vírgulas.

Obs: O itens marcados em vermelho não foram completamente implementados ou ainda estão em testes.

Regra de validação personalizada

Para criar uma regra de validação personalizada no Hello, você pode seguir os seguintes passos:

Se você preferir evitar a criação manual da estrutura da sua classe de validação personalizada, você pode utilizar o seguinte comando de CLI (Interface de Linha de Comando) chamado "Hello CLI" para agilizar o processo. Basta executar o comando "php hello make:rule <name_rule>" e você poderá pular os passos iniciais de criação da estrutura básica para a sua regra de validação personalizada. Isso irá gerar automaticamente a estrutura necessária para a sua classe de validação personalizada no diretório: app/Validations/Rules

php hello make:rule CustomRule

  1. Abra o diretórioapp/Validations/Rules no seu projeto Hello. Se o diretório Rules não existir, crie-o.

  2. Crie um novo arquivo PHP dentro do diretório Rules para sua regra de validação personalizada. Por exemplo, você pode criar um arquivo chamado CustomRule.php.

  3. No arquivo CustomRule.php, defina uma classe que estenda a classe Kernel\Http\RuleRequest e implemente o método passes e message conforme o código abaixo:

    <?php

namespace App\Validations\Rules;

use Kernel\Http\RuleRequest\CustomRule;

class CustomRule implements Rule
{
    public function passes($name, $value)
    {
        // Lógica de validação personalizada aqui
        // Retorne true se o valor for válido, ou false caso contrário
    }

    public function message()
    {
        // Mensagem de erro que será exibida em caso de falha na validação
        //Retorne uma string contendo a sua mesangem
    }
}

  4. Na função passes, implemente a lógica de validação personalizada para verificar se o valor fornecido é válido. Retorne true se o valor for válido e false caso contrário.

  5. Na função message, defina a mensagem de erro que será exibida em caso de falha na validação. Você pode retornar uma mensagem de erro estática ou personalizar a mensagem com base no atributo ou valor em questão.

  6. Agora você pode utilizar a sua regra de validação personalizada em qualquer lugar em que as validações do Hello são utilizadas, como nos controladores ou nas regras de validação dos formulários.

    use App\Validations\Rules\CustomRule;

$request->validate([
    'campo' => ['required', new CustomRule],
]);

Certifique-se de importar a classe da regra de validação personalizada no local onde você pretende utilizá-la.

Ao seguir esses passos, você será capaz de criar regras de validação personalizadas no Hello e aplicá-las em seus formulários e validações de dados.

Formulário de requisição

Um FormRequest no Hello é uma classe usada para validar os dados de um formulário antes de serem processados. Ele permite definir regras de validação para cada campo do formulário e separa a lógica de validação do controlador. Com o FormRequest, você pode garantir que os dados estejam corretos antes de prosseguir com o processamento.

Você pode criar a estrutura básica automáticamente usando o Hello CLI com o seguinte comando:

 php hello make:request UserRequest
<?php

namespace App\Validations\Forms;

use Kernel\Http\FormRequest;

class UserRequest extends FormRequest
{
     public function rules()
     {
        return [
            'name' => 'required|string|max:255',
            'email' => 'required|email|unique:users',
            'password' => 'required|min:8|confirmed',
        ];
     }

    public function messages()
    {
        return [
            'name.required' => 'O campo nome é obrigatório.',
            'email.required' => 'O campo e-mail é obrigatório.',
            'password.required' => 'O campo senha é obrigatório.'
        ];
    }
}

Esse código representa a definição de uma classe chamada UserRequest, que é usada para validar os dados de um formulário relacionado a usuários no Laravel.

A classe UserRequest estende a classe FormRequest, que é fornecida pelo Hello e fornece recursos para validar os dados do formulário.

Dentro da classe, temos dois métodos principais:

  1. O método rules() define as regras de validação para cada campo do formulário. No exemplo, temos regras como "required" (obrigatório), "string" (texto), "max:255" (máximo de 255 caracteres), "email" (formato de e-mail válido), "unique:users" (campo único na tabela "users") e "confirmed" (deve ser igual ao campo de confirmação). Essas regras garantem que os dados inseridos no formulário estejam corretos antes de serem processados.

  2. O método messages() define mensagens de erro personalizadas para cada campo do formulário. Essas mensagens serão exibidas caso a validação falhe. No exemplo, temos mensagens como "O campo nome é obrigatório", "O campo e-mail é obrigatório" e "O campo senha é obrigatório". Essas mensagens fornecem feedback claro para os usuários sobre quais campos são obrigatórios.

Essa classe UserRequest pode ser usada em um controlador no Hello, como um parâmetro de método, para validar e processar os dados do formulário de usuário. O Hello irá automaticamente executar a validação com base nas regras definidas e retornar erros caso necessário, facilitando o desenvolvimento de formulários seguros e confiáveis.

Estender a classe Request

A classe FormRequest estende a classe Request no Hello. Ao utilizar essa classe, o processo de instância é semelhante ao da classe Request. No entanto, com o FormRequest, você já terá campos e mensagens agrupadas e personalizadas de forma centralizada para um ou mais formulários específicos, de acordo com as necessidades do seu projeto.

Isso significa que, ao criar uma classe FormRequest, você pode definir as regras de validação e as mensagens de erro correspondentes para cada campo do formulário em um único lugar. Dessa forma, você evita a repetição de código e tem um local centralizado para gerenciar a validação e as mensagens.

Essa abordagem torna o processo de validação mais eficiente e organizado, facilitando a manutenção e o desenvolvimento de formulários em seu projeto.

Requisição de arquivos

A classe Request estende as funcionalidades da classeFileRequest e possui os seguintes métodos públicos para recuperação de arquivos:

array file(string $name, bool $one = true)

Retorna um ou vários arquivos com base no nome especificado. Se $one for verdadeiro, retorna apenas o primeiro array do arquivo encontrado. Caso contrário, retorna todos os arrays de arquivos encontrados.

array getFile(string $name)

Retorna uma coleção de array de arquivos com base no nome especificado. Se houver mais de um arquivo com o mesmo nome, eles são divididos em um array de arquivos individuais. Os arquivos também são atribuídos com informações adicionais, como caminho temporário, data de upload, extensão do arquivo, novo nome e validação.

Coleção de arquivos

Os métodos file e getFile retornam uma coleção de arrays contendo as seguintes chaves. A seguir, está o significado de cada chave com a respectiva descrição. A forma como os dados dos arquivos são armazenados para recuperação foi concebida com o objetivo de facilitar o armazenamento por uma classe responsável por essa funcionalidade. A compreensão de como as coisas são feitas já foi pensada levando em consideração essa facilidade.

  • "name": O nome original do arquivo.

  • "type": O tipo MIME do arquivo.

  • "tmp_name": O caminho temporário onde o arquivo é armazenado.

  • "error": Um código que indica se ocorreu algum erro durante o envio do arquivo.

  • "size": O tamanho do arquivo em bytes.

  • "file": O caminho completo do arquivo no servidor.

  • "upload_date": A data e hora do envio do arquivo.

  • "extension": A extensão do arquivo.

  • "new_name": O novo nome atribuído ao arquivo após o upload.

  • "validated": Um valor booleano indicando se o arquivo foi validado com sucesso.

Essas chaves fornecem informações relevantes sobre os arquivos, como nome, tipo, tamanho, localização temporária, data de envio, extensão, e outras informações úteis para processamento e manipulação posterior. A estrutura foi projetada para facilitar a utilização por uma classe responsável pelo armazenamento, visando simplicidade e praticidade no gerenciamento dos dados.

Exemplo de retorno do método file com o parâmetro $one definido como true, que é o valor padrão:

{
  "name": "lifecycle.PNG",
  "type": "image/png",
  "tmp_name": "C:\\xampp\\tmp\\phpFC13.tmp",
  "error": 0,
  "size": 62173,
  "file": "C:\\xampp\\tmp\\phpFC13.tmp",
  "upload_date": "2023-06-17 22:25:53",
  "extension": "png",
  "new_name": "e73e6643624ba0d8cd7fe4f237223edc.png",
  "validated": true
}

Com base na saída acima, é possível recuperar o nome do arquivo ou qualquer outro campo no formato de objeto, como exemplificado no código abaixo:

$file = $request->file('arquivo');
echo $file->name;

Exemplo de retorno do método getFile, que recupera um campo HTML com o atributo 'multiple' definido para vários arquivos:

[
  {
    "name": "lifecycle.PNG",
    "type": "image/png",
    "tmp_name": "C:\\xampp\\tmp\\phpBB48.tmp",
    "error": 0,
    "size": 62173,
    "file": "C:\\xampp\\tmp\\phpBB48.tmp",
    "upload_date": "2023-06-17 22:39:49",
    "extension": "png",
    "new_name": "e73e6643624ba0d8cd7fe4f237223edc.png",
    "validated": true
  },
  {
    "name": "lifecycle2.PNG",
    "type": "image/png",
    "tmp_name": "C:\\xampp\\tmp\\phpBB49.tmp",
    "error": 0,
    "size": 62173,
    "file": "C:\\xampp\\tmp\\phpBB49.tmp",
    "upload_date": "2023-06-17 22:39:49",
    "extension": "png",
    "new_name": "37695576317093079eadf7cdc79f7208.png",
    "validated": true
  }
]

Com a saída acima, que é um array de objetos, é possível acessar os valores do arquivo de forma iterativa por meio de um loop em PHP, conforme exemplificado no código abaixo:

$arrayDeObjetos = $request->getFile('arquivo');

foreach ($arrayDeObjetos as $objeto) {
    $name = $objeto->name;
    $type = $objeto->type;
    $tmp_name = $objeto->tmp_name;
    $error = $objeto->error;
    $size = $objeto->size;
    $file = $objeto->file;
    $upload_date = $objeto->upload_date;
    $extension = $objeto->extension;
    $new_name = $objeto->new_name;
    $validated = $objeto->validated;

    // Faça o processamento ou manipulação dos valores do arquivo aqui
    // ...
}

Dentro do loop, você pode acessar individualmente os valores de cada arquivo e realizar o processamento ou manipulação necessários. Os atributos como "name", "type", "tmp_name", "error", "size", "file", "upload_date", "extension", "new_name" e "validated" podem ser utilizados para realizar as operações desejadas.

bool hasFile(string $name)

Verifica se há um arquivo com o nome especificado na requisição. Retorna verdadeiro se existir um arquivo e falso caso contrário.

int fileSize($name, $one = true)

Retorna o tamanho total dos arquivos com o nome especificado. Se $one for verdadeiro, considera apenas o primeiro arquivo encontrado. Caso contrário, considera todos os arquivos encontrados.

array fileExtension(string $name_file, $one = true)

Retorna as extensões dos arquivos com o nome especificado do arquivo. Se $one for verdadeiro, retorna apenas a extensão do primeiro arquivo encontrado. Caso contrário, retorna as extensões de todos os arquivos encontrados.

bool fileCheckExtension(array $extensions_files, array $extensions)

Verifica se as extensões dos arquivos fornecidos estão contidas no array de extensões especificadas. Retorna verdadeiro se todas as extensões dos arquivos estiverem contidas, caso contrário, retorna falso.

Esses métodos permitem acessar, manipular e validar arquivos em uma requisição HTTP usando a classe FileRequest, que já é herdada em Request. A integração entre elas ocorre de forma suave, como exemplificado no código abaixo.

Exemplo de recuperação de arquivo

No código abaixo, declaramos uma rota do tipo GET que renderiza um formulário HTML. Utilizamos funções auxiliares de URL para apontar para uma rota interna do próprio sistema e também utilizamos a função auxiliar csrf_token() para obter o token CSRF da página atual.

Route::get('file',function(){

   return '<!DOCTYPE html>
     <html>
     <head>
         <title>Envio de Arquivo</title>
     </head>
    <body>
       <h1>Envio de Arquivo</h1>
   
         <form method="POST" action="'.url('teste').'" enctype="multipart/form-data">
           <input type="hidden" name="_token" value="'.csrf_token().'">
            <label for="file">Selecione um arquivo:</label>
            <input type="file" name="arquivo" id="file">
               <br>
            <input type="submit" value="Enviar">
          </form>
        
        </body>
   </html>';

});

No código abaixo, é mostrado como é simples fazer a recuperação de arquivos. Os arquivos enviados para o servidor têm seus campos armazenados em uma coleção de arrays, onde podem ser recuperados campo a campo, caso necessário. 

Route::post('file',function(Kernel\Http\Request $request){ 
      
        $request->validate(
        [
          'arquivo'=>'file'
        ]);

        if($request->fails())
        {
            return $request->errors();

        }else{
            return $request->getFile('arquivo');
        }
});

Salvando um arquivo no diretório storage

É possível realizar o salvamento de um arquivo enviado para a sua aplicação Hello por meio dos métodos publicos que são disponibilizados além do atributos para recuperação das informações dos arquivos informado acima. Veja o seguinte exemplo:

string | false store(string $path = null, $disk = null)

O método store é um método conveniente fornecido pelo Hello Framework para armazenar arquivos enviados pelo usuário. Ele lida com todo o processo de receber o arquivo, mover para o local desejado e gerar um nome único para o arquivo. O método store possui a seguinte assinatura:

  • $path (opcional): O caminho para onde o arquivo será armazenado. Se não for especificado, o Hello Framework usará o diretório padrão de armazenamento.

  • $disk (opcional): O nome do disco que será usado para armazenar o arquivo. Se não for especificado, o disco padrão será usado.

$file = $request->file('photo');

$storedPath = $file->store('photos');

echo "O arquivo foi armazenado em: " . $storedPath;

/*
  O método store retorna o caminho completo 
  para o arquivo armazenado, incluindo o nome gerado automaticamente.
*/

OBS: Neste exemplo, um arquivo de foto (photo) enviado pelo usuário é armazenado no diretório "photos" dentro do diretório "storage". O Hello Framework cuidará de todos os detalhes, como mover o arquivo e gerar um nome exclusivo.

string | false storeAs(string $path = null, $fileName = null,$disk = null)

O método storeAs é semelhante ao método store, mas permite que você especifique um nome de arquivo personalizado para o arquivo armazenado. Ele também lida com todo o processo de mover o arquivo e armazená-lo no local desejado. O método storeAs possui a seguinte assinatura:

  • $path: O caminho para onde o arquivo será armazenado.

  • $fileName: O nome do arquivo personalizado que você deseja atribuir ao arquivo armazenado.

  • $disk (opcional): O nome do disco que será usado para armazenar o arquivo. Se não for especificado, o disco padrão será usado.

$file = $request->file('document');

$storedPath = $file->storeAs('documents', 'mydocument');

echo "O arquivo foi armazenado em: " . $storedPath;

/*
 O método storeAs retorna o caminho completo 
 para o arquivo armazenado, 
 incluindo o nome do arquivo personalizado.
*/

Neste exemplo, um arquivo de documento enviado pelo usuário é armazenado no diretório "documents" dentro do diretório "storage" com o nome de arquivo personalizado "mydocument". O Hello Framework cuidará de todo o processo de armazenamento.

Obs: Infelizmente, o recurso de utilizar o parâmetro $disk nos métodos store e storeAs para outros discos, como os buckets do AWS S3, ainda não está completamente funcional devido a uma fase de testes e implementação em andamento. No entanto, se você precisar dessa funcionalidade, recomendamos criar um serviço personalizado para lidar com as operações desejadas.

Isso permitirá que você desenvolva as funcionalidades específicas que você necessita, personalizando o processo de armazenamento e manipulação de arquivos de acordo com as suas necessidades. Ao criar um serviço personalizado, você terá mais controle sobre a interação com os discos e poderá adaptar o código para utilizar recursos externos, como os buckets do AWS S3.

Lembrando que é importante acompanhar as atualizações e lançamentos do Hello Framework, pois o suporte para discos adicionais, como o AWS S3, pode ser incorporado em versões futuras, à medida que o recurso for aprimorado e estabilizado.

PreviousServicesNextLifeCycle

Last updated