Desenvolvimento do Sistema de Seleção da PRPPG - Guavira

• Preparação do Ambiente Virtual Conteinerizado
• Deploy dos contêineres
• Instalação do PHP, Composer e preparando ambiente Laravel no Linux
• Criando as conexões no ambiente Laravel
• Criando e Estabelecendo conexão com o Banco de Dados do Guavira
• Criando as Migrations
• Como criar uma Migration
• Deploy de alterações do código via git
• Fluxo de Desenvolvimento com GitLab

Preparação do Ambiente Virtual Conteinerizado

Deploy dos contêineres

1. Estruturação Inicial e Banco de Dados

Como definido previamente, decidiu-se iniciar a implementação do Guavira pela estruturação e criação do seu banco de dados. Para isso, é possível consultar a documentação disponibilizada pela UFVJM, que apresenta um guia para a criação de um contêiner com o serviço de banco de dados PostgreSQL, responsável por hospedar a estrutura do sistema.

2. Acesso ao Repositório e Clonagem do Projeto

Após obter acesso ao GitLab por meio do LDAP, que é o sistema de login institucional, e realizar a criação de uma chave SSH para autorizar operações a partir do seu computador, é possível prosseguir para a próxima etapa. Nessa fase, será necessário implementar no projeto da API o contêiner responsável por hospedar o banco de dados do Guavira.

Para isso, deve-se realizar a clonagem do projeto para o ambiente local, permitindo sua manipulação de forma segura. É importante destacar que os projetos clonados do GitLab devem estar localizados no diretório home do usuário, pois alguns comandos e operações dependem dessa localização. Após a clonagem, recomenda-se executar o comando de configuração de codificação, a fim de evitar que diferenças de encoding sejam interpretadas como alterações pelo Git.

git clone git@git.dds.ufvjm.edu.br:conta-institucional/api.git api

# entrar na pasta baixada
cd api

# Instrução para o Git ignorar alterações de permissão de arquivo (as permissões não são versionadas)
git config core.fileMode false

3. Configuração do LDAP e Variáveis de Ambiente

Para que o projeto da API funcione corretamente, é necessário que o serviço de LDAP esteja ativo, visto que grande parte das funcionalidades depende desse mecanismo de autenticação. Para realizar o deploy dos contêineres, será preciso obter as credenciais do LDAP, que são confidenciais e devem ser solicitadas via RocketChat a um responsável do DSI, não sendo, portanto, incluídas nesta documentação.

Com as credenciais em mãos, deve-se criar um arquivo .env, contendo as variáveis de ambiente necessárias para o funcionamento dos contêineres. Esse arquivo pode ser gerado a partir de uma cópia do .env.example, substituindo-se os valores pelas credenciais corretas.

cp .env.example .env

4. Deploy dos Contêineres

O processo de deploy será realizado com o auxílio de um Makefile, que contém scripts responsáveis por executar comandos Docker. Inicialmente, é necessário clonar o projeto de automação, uma vez que ele contém o serviço de LDAP. Em seguida, deve-se realizar o login no HUB da UFVJM utilizando o comando apropriado.

docker login -u nome.sobrenome hub.dds.ufvjm.edu.br

Caso esteja utilizando o Docker Desktop, pode ocorrer um erro durante esse processo. Para solucioná-lo, é necessário acessar o arquivo ~/.docker/config.json e remover o par chave-valor "credsStore".

Após isso, pode-se prosseguir com a clonagem do projeto de automação e realizar o deploy apenas do contêiner de LDAP, sendo recomendado comentar os demais serviços para evitar consumo desnecessário de recursos da máquina.

# ir pra home do usuario
cd ~

# baixar o repositório
git clone git@git.dds.ufvjm.edu.br:dds/automacao.git

5. Execução dos Serviços

Por fim, com todas as configurações concluídas, pode-se utilizar o script start presente no Makefile para realizar o deploy dos contêineres da API. Paralelamente, deve-se utilizar o comando docker compose up para iniciar o contêiner de automação, garantindo o funcionamento completo do ambiente necessário para o desenvolvimento do sistema.

# cd ~/api
make start

# cd ~/automacao
docker compose up

Como etapa final de organização do ambiente de desenvolvimento, recomenda-se realizar o attach (ou abertura) dos dois projetos — API e automação — em uma IDE de sua preferência, como o PhpStorm. Isso facilita a navegação entre os arquivos, execução de comandos, edição de código e integração com ferramentas de versionamento. Em IDEs como o PhpStorm, é possível abrir ambos os projetos na mesma janela, utilizando a opção de Attach Project, ou simplesmente abrindo os diretórios simultaneamente no workspace.

Instalação do PHP, Composer e preparando ambiente Laravel no Linux

{
    "require": {
        "php": "^8.2",
        "laravel/framework": "^12.0"
    }
}

cat composer.json | grep php

php -v

PHP 8.1.2 (cli)

sudo apt update

sudo add-apt-repository ppa:ondrej/php
sudo apt update

sudo apt install php8.2 \
php8.2-cli \
php8.2-common \
php8.2-mysql \
php8.2-mbstring \
php8.2-xml \
php8.2-curl \
php8.2-zip \
php8.2-bcmath \
php8.2-intl

sudo update-alternatives --config php

There are 2 choices for the alternative php:

Selection    Path
-------------------------------------
0            /usr/bin/php8.2
1            /usr/bin/php8.1
2            /usr/bin/php8.2

php -v

PHP 8.2.x

composer --version

sudo apt install composer

composer --version

Composer version 2.8.5

composer install

projeto/
├── app/
├── database/
├── routes/
├── vendor/
├── composer.json
├── composer.lock
└── .env

php artisan

Laravel Framework 12.x

Available commands:
  about
  migrate
  route:list
  serve
  ...

php -v
composer --version
php artisan

# Verificar versão do PHP
php -v

# Instalar PHP 8.2
sudo add-apt-repository ppa:ondrej/php
sudo apt update

sudo apt install php8.2 \
php8.2-cli \
php8.2-common \
php8.2-mysql \
php8.2-mbstring \
php8.2-xml \
php8.2-curl \
php8.2-zip \
php8.2-bcmath \
php8.2-intl

# Definir PHP padrão
sudo update-alternatives --config php

# Verificar Composer
composer --version

# Instalar Composer
sudo apt install composer

# Instalar dependências do projeto
composer install

# Gerar APP_KEY
php artisan key:generate

# Verificar Laravel
php artisan

Criando as conexões no ambiente Laravel

Criando e Estabelecendo conexão com o Banco de Dados do Guavira

6. Configuração da Conexão com o Banco de Dados

Após realizar o deploy do contêiner responsável pelo banco de dados, é necessário configurar uma conexão com ele na API Laravel. Esse passo é fundamental para garantir que as migrations e demais operações relacionadas ao banco de dados sejam executadas na base correta.

Essa configuração é especialmente importante porque a aplicação possui conexões com diversos bancos de dados institucionais, como os utilizados pelo RU, E-Campus, ambiente de testes e outros serviços. Portanto, antes de criar ou executar qualquer migration, é preciso garantir que a conexão do banco de dados da Seleção PRPPG esteja devidamente cadastrada.

Para realizar essa configuração, serão necessárias algumas variáveis de ambiente. Por motivos de segurança, os valores reais não serão apresentados nesta documentação, sendo substituídos por exemplos fictícios. As credenciais corretas devem ser solicitadas pelos canais oficiais da organização.

SELECAO_PRPPG_DB_CONNECTION=pgsql
SELECAO_PRPPG_DB_HOST=postgres
SELECAO_PRPPG_DB_PORT_FORWARD=5450
SELECAO_PRPPG_DB_PORT=5432
SELECAO_PRPPG_DB_USERNAME=admin
SELECAO_PRPPG_DB_PASSWORD=admin123
SELECAO_PRPPG_DB_DATABASE=prppg

7. Adicionando a Conexão no Laravel

Com as variáveis de ambiente configuradas, o próximo passo é acessar o arquivo:

api/config/database.php

Nesse arquivo encontra-se o array associativo connections, responsável por armazenar todas as conexões de banco de dados utilizadas pela aplicação. Cada conexão segue a estrutura:

nome_da_conexao => [
    // configurações
]

Dentro desse array, deve-se criar uma nova entrada correspondente ao banco de dados da Seleção PRPPG.

  env('SELECAO_PRPPG_DB_CONNECTION', 'pgsql_selecao_prppg') => [
            'driver' => 'pgsql',
            'url' => env('DB_URL'),
            'host' => env('SELECAO_PRPPG_DB_HOST', '127.0.0.1'),
            'port' => env('SELECAO_PRPPG_DB_PORT', '5432'),
            'database' => env('SELECAO_PRPPG_DB_DATABASE', 'laravel'),
            'username' => env('SELECAO_PRPPG_DB_USERNAME', 'root'),
            'password' => env('SELECAO_PRPPG_DB_PASSWORD', ''),
            'charset' => env('DB_CHARSET', 'utf8'),
            'prefix' => '',
            'prefix_indexes' => true,
            'search_path' => 'public',
            'sslmode' => 'prefer',
        ],

A configuração da conexão é composta por diversos parâmetros, cada um responsável por definir uma característica específica da comunicação com o banco de dados:

• O nome da conexão e o valor padrão utilizado caso a variável de ambiente correspondente não seja encontrada;
• O driver de banco de dados utilizado pela conexão;
• A URL de conexão, utilizada como configuração genérica dentro do projeto;
• O host do banco de dados e seu valor padrão;
• A porta em que o serviço está escutando e seu valor padrão;
• O nome do banco de dados e seu valor padrão;
• O usuário utilizado para autenticação e seu valor padrão;
• A senha da conexão e seu valor padrão;
• O conjunto de caracteres (charset) utilizado pelo banco de dados.

8. Utilizando a Conexão nas Migrations

Com a conexão devidamente cadastrada no Laravel, resta apenas informar às migrations qual conexão deverá ser utilizada durante sua execução.

Isso pode ser feito definindo o atributo $connection na classe da migration:

return new class extends Migration
{
    /**
     * The database connection used by the migration.
     *
     * @var string
     */
    protected $connection = 'pgsql_ru';

    /**
     * Class constructor.
     */
    public function __construct()
    {
        // if tests are running, then change the testing connection to pgsql_testing
        if (app()->environment('testing')) {
            $this->connection = 'pgsql_testing';
        }
    }

Ao especificar essa propriedade, o Laravel executará todas as operações daquela migration utilizando a conexão indicada, garantindo que as tabelas sejam criadas, alteradas ou removidas no banco de dados correto. Dessa forma, evita-se que alterações sejam aplicadas acidentalmente em outros bancos de dados configurados na aplicação.

Criando as Migrations

Como criar uma Migration

Tutorial: Criando uma Migration no Laravel

Este tutorial demonstra o processo completo de criação de uma migration no Laravel utilizando como exemplo a tabela usuarios.

Ao final deste guia você será capaz de:

• Criar uma migration;
• Definir a conexão do banco utilizada;
• Criar tabelas e colunas;
• Definir chaves primárias;
• Definir restrições de unicidade;
• Utilizar enums;
• Executar migrations;
• Reverter migrations;
• Compreender os tipos de colunas mais utilizados.

1. O que é uma Migration?

Uma migration é um arquivo PHP responsável por definir a estrutura do banco de dados.

Ela funciona como um controle de versão do banco.

Em vez de executar manualmente comandos SQL como:

CREATE TABLE usuarios (...);

o Laravel utiliza migrations:

Schema::create('usuarios', function (Blueprint $table) {
    ...
});

Isso permite que toda a equipe mantenha o banco sincronizado.

2. Criando uma Migration

Para criar uma migration:

php artisan make:migration create_usuarios_table

Será criado um arquivo semelhante a:

database/migrations/
└── 2026_06_10_144334_create_usuarios_table.php

Caso o projeto utilize uma pasta específica:

php artisan make:migration create_usuarios_table \
--path=database/migrations/selecao_prppg

3. Estrutura básica de uma Migration

Toda migration possui dois métodos:

public function up(): void
{
    // cria ou altera tabelas
}

public function down(): void
{
    // desfaz alterações
}

Método up()

Executado quando rodamos:

php artisan migrate

Método down()

Executado quando rodamos:

php artisan migrate:rollback

4. Definindo a conexão do banco

No projeto de vocês existe mais de uma conexão.

Por isso foi definido:

protected $connection = 'pgsql_selecao_prppg';

Isso indica que a migration será executada utilizando a conexão:

DB_CONNECTION=pgsql_selecao_prppg

configurada em:

config/database.php

5. Tratamento para ambiente de testes

No construtor:

public function __construct()
{
    if (app()->environment('testing')) {
        $this->connection = 'pgsql_testing';
    }
}

Quando os testes automatizados forem executados:

php artisan test

a migration utilizará:

pgsql_testing

em vez de:

pgsql_selecao_prppg

evitando alterações no banco real.

6. Verificando se a tabela já existe

Antes da criação:

if (!Schema::hasTable('usuarios'))

O Laravel verifica:

SELECT ...
FROM information_schema.tables

Se a tabela já existir:

usuarios

ela não será criada novamente.

7. Criando a tabela

A criação da tabela ocorre através de:

Schema::create('usuarios', function (Blueprint $table) {
    ...
});

Equivalente ao SQL:

CREATE TABLE usuarios (...);

8. Criando a chave primária

Código:

$table->id()
      ->autoIncrement()
      ->primary()
      ->comment('Id do Usuario');

Resultado:

id BIGINT PRIMARY KEY AUTO_INCREMENT

Observação:

No Laravel moderno geralmente basta:

$table->id();

pois o framework já cria:

• auto increment
• primary key

automaticamente.

9. Criando campos texto

Nome:

$table->string('nome', 100);

Resultado:

VARCHAR(100)

Email:

$table->string('email', 100);

Resultado:

VARCHAR(100)

CPF:

$table->string('cpf', 11);

Resultado:

VARCHAR(11)

10. Definindo valores únicos

Email:

$table->string('email', 100)->unique();

Resultado:

UNIQUE(email)

Não será possível cadastrar dois usuários com o mesmo email.

CPF:

$table->string('cpf', 11)->unique();

Resultado:

UNIQUE(cpf)

11. Trabalhando com datas

Campo:

$table->dateTime('data_cadastro');

Resultado:

DATETIME

ou

TIMESTAMP

dependendo do banco.

Exemplo:

2026-06-10 14:30:00

12. Trabalhando com Enum

Campo:

$table->enum('cargo', [
    'SECRETARIA',
    'COORDENADOR',
    'COMISSAO',
    'ADMINISTRADOR'
]);

Resultado:

ENUM(...)

Valores permitidos:

SECRETARIA
COORDENADOR
COMISSAO
ADMINISTRADOR

Qualquer outro valor será rejeitado.

13. Campo senha

Campo:

$table->string('senha', 60);

Resultado:

VARCHAR(60)

Normalmente armazenará um hash:

$2y$12$...

e não a senha em texto puro.

14. Timestamps automáticos

Código:

$table->timestamps();

Cria automaticamente:

created_at
updated_at

Exemplo:

15. Executando a Migration

Após criar o arquivo:

php artisan migrate

O Laravel:

1. Localiza migrations pendentes.
2. Executa o método up().
3. Registra a execução na tabela:

migrations

16. Verificando o status

php artisan migrate:status

Exemplo:

Migration name                     Ran?
-----------------------------------------
create_usuarios_table              Yes

17. Revertendo a Migration

Desfaz a última migration executada:

php artisan migrate:rollback

Executa:

public function down()
{
    Schema::dropIfExists('usuarios');
}

18. Recriando tudo

Muito utilizado durante desenvolvimento:

php artisan migrate:fresh

Apaga todas as tabelas e executa novamente todas as migrations.

Comandos mais utilizados

Tipos de colunas mais utilizados

Modificadores mais utilizados

Relacionamentos (Foreign Keys)

Os mais utilizados no projeto Guavira serão:

Forma moderna

$table->foreignId('programa_id')
      ->constrained('programas');

Com cascade

$table->foreignId('programa_id')
      ->constrained('programas')
      ->cascadeOnDelete();

Forma explícita

$table->unsignedBigInteger('programa_id');

$table->foreign('programa_id')
      ->references('id')
      ->on('programas');

Métodos mais utilizados no projeto

Ao criar as tabelas programas, editais, linhas_pesquisa, inscricoes, resultados e demais entidades do sistema, você utilizará principalmente:

Esses métodos são suficientes para construir praticamente todas as tabelas do banco do sistema de seleção PRPPG/Guavira.

Deploy de alterações do código via git

Fluxo de Desenvolvimento com GitLab

1. Criar uma Issue

Antes de iniciar qualquer desenvolvimento, deve ser criada uma Issue no GitLab descrevendo a atividade a ser realizada.

A Issue deve conter:

• Título claro e objetivo;
• Descrição detalhada da demanda;
• Critérios de aceitação, quando aplicável;
• Labels apropriadas (feature, bug, hotfix, etc.).

Após a criação, o GitLab atribuirá um identificador único (ID) à Issue, por exemplo:

#123

Esse ID será utilizado na nomenclatura da branch e nas mensagens de commit.

2. Criar uma Branch

A branch deve ser criada utilizando o ID da Issue.

Para novas funcionalidades

Padrão:

feature/<id-da-issue>-<descricao>

Exemplo:

feature/123-cadastro-de-usuarios

Para correções urgentes (Hotfix)

Padrão:

hotfix/<id-da-issue>-<descricao>

Exemplo:

hotfix/124-correcao-validacao-cpf

3. Atualizar as Referências Locais

Antes de trocar para a nova branch, atualize as referências do repositório:

git pull

4. Trocar para a Branch de Trabalho

Após a criação da branch:

git switch nome-da-branch

Exemplo:

git switch feature/123-cadastro-de-usuarios

5. Recuperar Alterações Temporariamente Armazenadas

Caso tenha utilizado stash anteriormente:

git stash pop

6. Verificar Arquivos Alterados

Antes de realizar o commit:

git status

7. Corrigir Padrão de Código

Caso existam inconsistências no padrão de escrita do código, execute:

make pint-fixer

Esse comando aplica automaticamente as regras de formatação definidas pelo projeto.

8. Adicionar Arquivos ao Commit

Após validar as alterações:

git add .

9. Verificar Novamente o Status

Confirme os arquivos que serão enviados:

git status

10. Realizar o Commit

A mensagem do commit deve obrigatoriamente referenciar a Issue correspondente.

Padrão:

git commit -m "#<id> descrição da alteração"

Exemplos:

git commit -m "#123 adiciona cadastro de usuários"

git commit -m "#124 corrige validação de CPF"

11. Enviar Alterações para o Repositório Remoto

git push

Caso seja o primeiro push da branch:

git push -u origin nome-da-branch

Exemplo:

git push -u origin feature/123-cadastro-de-usuarios

12. Criar Merge Request

Após concluir o desenvolvimento:

1. Acesse o GitLab;
2. Crie um Merge Request da branch criada para a branch principal do projeto;
3. Vincule a Issue correspondente;
4. Solicite revisão de código;
5. Aguarde aprovação e merge.

Resumo do Fluxo

git pull
git switch feature/123-cadastro-de-usuarios
git stash pop
git status
make pint-fixer
git add .
git status
git commit -m "#123 adiciona cadastro de usuários"
git push