Criando API PHP com Laravel e PostgreSQL

Neste artigo iremos criar uma API usando Laravel em conexão com o PostgreSQL.

Se você não possui o Laravel, poderá ver como instalá-lo acessando nosso artigo Instalando e Configurando o Laravel no Windows, Linux e Mac.

Em um dos nossos últimos artigos nós ensinamos a instalar o Postgres e também criamos uma primeira tabela. Você pode acessar esse conteúdo clicando aqui.

Será com base neste Banco de Dados que criaremos nossa API.

Iniciando a API

Para iniciar um projeto em Laravel, vamos usar o seguinte comando: laravel new hcode-api-users.

Após criar nossa aplicação, vamos acessá-la no Terminal com o comando cd hcode-api-users e realizar a configuração do Banco de Dados. Para isso, vamos editar o arquivo .env na raiz de nosso projeto, informando as credenciais de nosso Banco. Ele ficará assim:

DB_CONNECTION=pgsql
DB_HOST=127.0.0.1
DB_PORT=5432
DB_DATABASE=hcodedb
DB_USERNAME=postgres
DB_PASSWORD=root

Além disso, como vamos realizar uma conexão com o Postgres, precisamos verificar se nosso PHP possui as DLLs deste Banco de Dados definidos em nosso arquivo de configuração. Se você estiver usando XAMPP, poderá verificar essa configuração no arquivo xampp/php/php.ini. As duas linhas a seguir devem estar sem comentários:

extension=pdo_pgsql
extension=pgsql

Agora que toda a configuração inicial está realizada, vamos iniciar o servidor da API. Para isso, vamos executar o comando php artisan serve em nosso Terminal. Será retornada a seguinte mensagem no Terminal:

Criando primeira rota

A primeira rota que criaremos será a rota para listar os usuários. O arquivo de rotas no Laravel fica na pasta routes. Vamos editar o arquivo api.php. Esse arquivo faz uso da classe Route. Ela possui um método estático para cada método de requisição HTTP. Para listar usuários, usamos o método GET. Dessa forma, adicionaremos o seguinte código em nosso arquivo:

Route::get('users', function() {
	return 'Funcionando!!!';
});

Explicando: o primeiro parâmetro para o método é a rota em si, ou seja, “users”. O segundo parâmetro é uma função que será executada ao acessar a rota. Neste caso, iremos apenas retornar uma string.

Para testar essa rota, precisamos acessar a URL localhost:8000/api/users em nosso navegador. Note que informamos “/api”, que é o nome de nosso arquivo PHP. Ao acessar esse endereço no navegador, vemos o seguinte resultado:

Excelente, a nossa rota funcionou. Bem simples, não acha?

O próximo passo é deixar essa rota dinâmica. Afinal de contas, queremos listar os usuários do Banco, não apenas retornar uma mensagem estática. Isso nos leva para o próximo recurso do Laravel.

Listando os Usuários

O Laravel faz uso do padrão MVC (Model View Controller). De acordo com esse padrão, em vez de deixar a regra de negócio explícita nas rotas de nossa aplicação, devemos incluí-la em uma classe específica, os nossos Controllers. Será por meio deles que retornaremos os usuários para nossa rota.

Podemos criar um Controller por meio da linha de comando, através do php artisan, informando em seguida o nome do Controller que estamos criando. Vamos executar o seguinte comando:

php artisan make:controller UsersController

O nosso Controller será automaticamente criado na pasta app/Http/Controllers. É recomendado que criemos Controllers sempre no plural. Isso é considerado uma boa prática.

Nosso Controller foi criado com sucesso. Contudo, ele não é o responsável por ir até o Banco de Dados e trazer os dados. Essa função é exercida pelo Model, outra camada da estrutura MVC. Podemos dizer que o controller é quem faz o “meio de campo” para trazer os dados para a rota. Mas quem vai buscar esses dados é o Model.

Para criar um Model, podemos usar os recursos do php artisan novamente. Vamos executar o seguinte comando:

php artisan make:model User

Note que o Model é criado no singular, e isso também é considerado uma boa prática. Quando executarmos esse comando, será retornado um erro, informando que este Model já existe. Isso ocorre pois o Model com nome “User” é um dos que o Laravel nos traz por padrão. Contudo, se precisarmos criar outros Models, podemos usar esse mesmo comando.

Agora que tanto o Controller e o Model estão criados, vamos conectar um ao outro. Vamos fazer isso no arquivo UsersController.php. Iremos criar um método chamado index(), que será o que iremos informar no arquivo de rotas.

Esse método irá realizar a chamada do método all(), que vem do Model User. Esse método tem o objetivo de trazer todos os registros da tabela de usuários. Nosso código ficará assim:

use App\User;

public function index() {
	return User::all();
}

Agora vamos realizar a chamada desse método em nosso arquivo api.php. Ele ficará assim:

Route::get('users', "UsersController@index");

Explicando: nós substituímos a função que estávamos executando antes pela chamada da classe UsersController e do método index, que foram separados pelo símbolo de arroba (@).

Agora, ao acessar o mesmo endereço no navegador, vemos o seguinte resultado:

Nossos usuários estão sendo listados por meio de nossa API. Mas note que em nenhum momento nós executamos um comando SELECT com o PHP, de maneira imperativa. Nós precisamos apenas criar os métodos em nossas classes, de maneira declarativa, e o Laravel nos trouxe os dados desejados. Incrível, não é mesmo?

Criando um Usuário

Iremos agora programar a criação de um usuário através de nossa API. Vamos começar por criar o método de nosso Controller. Vamos chamá-lo de store(). Ele possuirá o seguinte código:

public function store(Request $request) {

	$user = User::create([
		"name"=>$request->input("name"),
		"email"=>$request->input("email")
	]);

	return $user;

}

Explicando: esse método espera como parâmetro a requisição do nosso cliente, que no Laravel é representada pela classe Request. Essa classe possuirá todas as informações postadas, como o nome e o email do novo usuário.

Novamente fazemos uso do Model User e chamamos seu método create(), outro recurso nativo do Laravel, que é o responsável por criar o novo registro no Banco. Nós informamos para esse método um array com os dados que queremos inserir. Note que fazemos uso do método input() da classe Request. Esse método é o responsável por identificar de fato o valor do que foi postado pelo usuário.

Vamos agora chamar esse método por meio de nosso arquivo de rotas. Faremos isso por meio da seguinte linha de código:

Route::post('users', "UsersController@store");

Note que mais uma vez fizemos uso da rota “users”. Contudo, agora com o método post().

Para fazer o teste dessa rota, podemos usar o Insomnia, um REST Client muito poderoso. Nós ensinamos a realizar sua instalação e mostramos alguns de seus recursos no artigo Usando Insomnia para testar as requisições de nossas APIs.

Vamos acessá-lo e criar uma nova requisição:

Vamos dar o nome “Hcode API POST” para essa requisição:

Vamos deixar claro que essa é uma requisição POST e definir que o corpo da requisição será do tipo “Form URL Encoded”:

Precisamos informar agora os campos que iremos postar e o valor de cada um deles:

O próximo passo é definir a URL que iremos acessar:

Por fim, basta clicar em “Send”. Quando fazemos isso, vemos o seguinte erro no Insomnia:

Esse erro ocorre pois o Laravel exige que possuamos duas colunas padrão em todas as tabelas que criarmos. Essas colunas são “updated_at” e “created_at”. Elas são constantemente atualizadas pelo Laravel.

Assim, vamos acessar o nosso Postgres e adicionar essas colunas à tabela users. Iremos executar o seguinte comando:

ALTER TABLE users
	ADD COLUMN updated_at TIMESTAMP DEFAULT NULL,
	ADD COLUMN created_at TIMESTAMP DEFAULT NULL;

Agora, ao enviar a requisição novamente, vemos o seguinte resultado:

Perfeito! Nossos dados foram inseridos corretamente.

Editando um Usuário

Para editar um usuário, vamos criar em nosso Controller um método chamado update(). Ele irá esperar como parâmetro os dados informados pela requisição, mas também as informações do usuário já existente que queremos alterar. Sua estrutura será a seguinte:

public function update(Request $request, User $user) {

	$user->name = $request->input('name');
	$user->email = $request->input('email');

	$user->save();

	return $user;

}

Explicando: o valor das propriedades “name” e “email” do Model User serão substituídos pelas informações postadas pelo usuário. Contudo, para que isso seja possível, é necessário que deixemos explícito em nosso Model que essas propriedades podem ser editadas. Para isso, usamos uma propriedade chamada $fillable, que traduzindo significa “preenchível”.

O Model User, criado por padrão pelo Laravel, já possui essa propriedade, que por coincidência já possui os atributos “name” e “email” definidos. Assim, não precisamos nos preocupar com essa configuração:

O método de nosso Controller já está pronto. Vamos chamá-lo em nosso arquivo de rotas. Para editar os dados de um usuário, podemos escolher entre usar os método PUT ou PATCH. O primeiro tem o objetivo de editar todos os dados de um usuário específico. O segundo edita apenas parte dos dados de nosso usuário e será ele quem escolheremos. Nosso arquivo ficará assim:

Route::patch('users/{user}', "UsersController@update");

Note que nós informamos a palavra “user” entre chaves para a rota. Isso constitui um parâmetro para nossa rota de edição. Esse parâmetro será o ID do usuário que desejamos editar. O próprio Laravel irá carregar suas informações e editá-las.

Vamos criar uma nova requisição no Insomnia, chamada “Hcode API PATCH”:

Vamos informar a URL de nossa API para essa requisição, definindo o ID 3 como o que será editado, junto com as informações que queremos atualizar:

Ao clicar em “Send”, vemos o seguinte resultado:

Nossos dados foram atualizados com sucesso!

Excluindo um usuário

Por fim, vamos programar a exclusão de um usuário. Iremos criar um método chamado remove() em nosso Controller. Ele esperará como parâmetro apenas os dados do usuário que iremos excluir, que será representado pelo Model User. Daí, chamaremos o método delete() que essa classe possui. Seu código será o seguinte:

public function remove(User $user) {

	$user->delete();

	return response()->json([
		'message'=>'Usuário excluído com sucesso'
	]);

}

Vamos fazer a chamada desse método em nosso arquivo de rotas, usando o método delete():

Route::delete('users/{user}', "UsersController@remove");

Perceba que neste caso também fizemos uso da passagem de parâmetros para a rota.

Vamos criar a requisição de exclusão no Insomnia com o nome “Hcode API DELETE”:

Vamos definir a URL da API em nossa requisição, informando o ID 1 para ela.

Veremos o seguinte resultado ao enviá-la:

Nosso usuário foi excluído com sucesso.

É interessante notar que construímos um CRUD de usuários sem quase acessar o Banco de Dados. O Laravel fez isso por nós. Dessa forma, se desejássemos manipular outro Banco de Dados que não fosse o Postgres, precisaríamos apenas mudar as configurações de acesso a ele que definimos no arquivo .env e o código continuaria funcionando.

Você pode encontrar os códigos desenvolvidos neste artigo em nosso GitHub.

O Laravel é realmente uma “mão na roda” para criarmos APIs em PHP de uma maneira muito mais rápida e simples. Nós ensinamos outros recursos desse incrível framework em nosso curso Criando REST API com Laravel 5.7.

Obrigado por ter lido e até o próximo artigo :)