🌐 Projeto PHP Composer POO MVC

Autor: Prof. Gill Gonzales
E-mail: gillgonzales@ifsul.edu.br
ORCID: 0000-0002-4539-3181
Códigos e outros projetos: GitHub - gillgonzales

📖 Sobre o projeto

Este repositório é um protótipo educacional de uma aplicação MVC escrita em PHP, com poucas dependências externas. Seu objetivo é reforçar, por meio de um exemplo executável, os conceitos de:

• Programação Orientada a Objetos (POO), com classes, namespaces, interfaces, traits, encapsulamento e herança;
• Arquitetura MVC, separando modelos, controladores e visualizações;
• Roteamento de requisições web e de uma API simples;
• Persistência com PDO;
• Padrões de projeto, especialmente o Singleton usado pela classe Connection para reaproveitar a conexão com o banco de dados;
• Autoloading PSR-4 e gerenciamento de dependências com Composer.

Ao estabelecer a primeira conexão, a aplicação verifica se as tabelas existem e instala o dump SQL correspondente ao banco configurado.

🧰 Requisitos

Para executar o projeto localmente, instale:

• PHP 8.5 ou compatível com o Dockerfile, com as extensões PDO, pdo_mysql ou pdo_pgsql conforme o banco escolhido;
• Composer;
• Git;
• Docker com Docker Compose.

A forma recomendada para estudo é usar Docker, pois o Dockerfile já instala PHP, Composer e as extensões PDO para MariaDB e PostgreSQL.

📥 Obtendo o código

git clone https://github.com/gillgonzales/php_composer_poo_mvc.git
cd php_composer_poo_mvc

Para consultar ou criar uma alteração em uma branch própria:

git status
git switch -c minha-alteracao
# depois de revisar
git add .
git commit -m "Descreve a alteração"
git push -u origin minha-alteracao

O endereço do repositório pode variar conforme a origem utilizada. Confirme-a com git remote -v.

⚙️ Configuração do ambiente

Copie o arquivo de exemplo antes de iniciar a aplicação:

cp .env.example .env

O .env não deve ser versionado. Ajuste estas variáveis de acordo com o modo de execução:

Variável	Finalidade	Exemplo
APP_PORT	Porta publicada para a aplicação	8081
APP_HOST	URL base da aplicação	http://localhost:8081
APP_BASE_URL	Prefixo base das URLs	/
APP_TEMPLATE	Template visual opcional	natal
FORWARD_DB_PORT	Porta do banco publicada no host	3310
FORWARD_DBADMIN_PORT	Porta do cliente de administração	8093 ou 8090
APP_DB_DRIVE	Driver PDO	mysql ou pgsql
APP_DB_HOST	Host do banco	mariadb, pgsql ou 127.0.0.1
APP_DB_NAME	Nome do banco	apiprods ou apiprod
APP_DB_PORT	Porta do banco vista pela aplicação	3306 ou 5432
APP_DB_CHARSET	Charset do MySQL/MariaDB	utf8
APP_DB_USER	Usuário do banco	phpapp ou root
APP_DB_PASS	Senha do banco	passwd ou r00t

🗄️ Banco escolhido

O projeto oferece suporte a MariaDB e PostgreSQL. As configurações dos serviços ficam em arquivos Compose separados:

• compose.yaml: MariaDB e phpMyAdmin;
• compose.pgsql.yaml: PostgreSQL e pgAdmin;
• compose.mariadb.yaml: configuração alternativa de MariaDB.

Use apenas um perfil de banco por vez. Em uma execução dentro do Docker, o host deve ser o nome do serviço da rede Compose (mariadb ou pgsql) e a porta interna deve ser 3306 ou 5432. Em uma execução PHP fora do Docker, use 127.0.0.1 e a porta publicada em FORWARD_DB_PORT.

🐬 Exemplo para MariaDB com Docker

No .env, use valores equivalentes a:

APP_PORT=8081
APP_HOST=http://localhost:8081
FORWARD_DB_PORT=3310
FORWARD_DBADMIN_PORT=8093
APP_DB_DRIVE=mysql
APP_DB_HOST=mariadb
APP_DB_NAME=apiprods
APP_DB_PORT=3306
APP_DB_CHARSET=utf8
APP_DB_USER=phpapp
APP_DB_PASS=passwd

🐘 Exemplo para PostgreSQL com Docker

No .env, use valores equivalentes a:

APP_PORT=8081
APP_HOST=http://localhost:8081
FORWARD_DB_PORT=5433
FORWARD_DBADMIN_PORT=8090
APP_DB_DRIVE=pgsql
APP_DB_HOST=pgsql
APP_DB_NAME=apiprod
APP_DB_PORT=5432
APP_DB_USER=root
APP_DB_PASS=r00t

O .env.example contém os dois blocos de configuração. Ative somente o bloco correspondente ao banco escolhido e confira o host conforme o modo de execução.

🐳 Inicialização com Docker

🐬 MariaDB

docker compose -f compose.yaml up --build

A aplicação ficará disponível em http://localhost:8081 e o phpMyAdmin em http://localhost:8093. Para interromper os serviços, pressione Ctrl+C ou execute:

docker compose -f compose.yaml down

🐘 PostgreSQL

docker compose -f compose.pgsql.yaml up --build

A aplicação ficará disponível em http://localhost:8081 e o pgAdmin em http://localhost:8090. Para interromper os serviços:

docker compose -f compose.pgsql.yaml down

Os dados persistem nos volumes volmariadb ou pgsql-data. Para remover também os dados persistidos, use down -v, sabendo que essa operação apaga o banco local:

docker compose -f compose.yaml down -v
# ou
# docker compose -f compose.pgsql.yaml down -v

O serviço PHP executa composer i na inicialização do container e depois chama o script start, que serve o diretório public/ na porta 80 do container.

💻 Inicialização sem Docker

Com PHP e Composer instalados, instale as dependências:

composer install

Configure o .env com APP_DB_HOST=127.0.0.1 e com APP_DB_PORT igual à porta do banco disponível no computador. Em seguida, inicie o servidor embutido do PHP:

php -S 127.0.0.1:8081 -t public

Acesse http://localhost:8081. O script Composer start também está disponível, mas usa a porta 80 por definição:

composer run start

O comando interativo opcional do PsySH é:

composer run psy

🛣️ Rotas de exemplo

As rotas são registradas em config/routes.php e resolvidas por app/core/Route.php:

• /: página inicial;
• /login: tela de login;
• /produtos: controlador web de produtos;
• /api/produtos: recurso de produtos da API;
• /api/products: alias em inglês para o mesmo recurso.

O diretório public/ é o document root. A entrada da aplicação é public/index.php.

📂 Estrutura de pastas

.
├── app/
│   ├── controllers/       # Controladores web e da API.
│   │   ├── api/           # Controllers e recursos HTTP da API.
│   │   └── web/           # Controllers das páginas web e autenticação.
│   ├── core/              # Núcleo MVC: inicialização e roteamento.
│   ├── interfaces/        # Contratos das classes e recursos.
│   ├── models/             # Modelos e regras de acesso aos dados.
│   ├── traits/             # Funcionalidades reutilizáveis, como ambiente e logs.
│   └── views/              # Abstração para renderização das respostas.
├── config/
│   └── routes.php          # Registro das rotas web e API.
├── database/
│   ├── Connection.php      # Conexão PDO e exemplo de Singleton.
│   └── dumps/              # Dumps SQL de MariaDB e PostgreSQL.
├── public/
│   ├── index.php           # Front controller da aplicação.
│   └── templates/          # Templates, layouts, páginas e assets.
├── compose.yaml            # Serviços Docker com MariaDB e phpMyAdmin.
├── compose.pgsql.yaml      # Serviços Docker com PostgreSQL e pgAdmin.
├── compose.mariadb.yaml    # Perfil alternativo de MariaDB.
├── Dockerfile              # Imagem PHP com Composer e extensões PDO.
├── composer.json           # Dependências, autoload PSR-4 e scripts.
├── .env.example            # Modelo das variáveis de ambiente.
└── vendor/                 # Dependências instaladas pelo Composer.

🔗 Referências

• PHP.net
• Manual do Composer para PHP
• Documentação do Git
• Documentação do Docker
• Docker Compose
• Padrão Singleton
• PSR-4: Autoloading Specification