Tudo começou com um index.asp​

Tudo começou no ano 2000, quando eu trabalhava na Unitech, uma empresa de outsourcing para o governo. Eu fazia parte do setor de Pesquisa e Desenvolvimento, e uma das nossas missões era validar se o .NET 1.0 era um bom caminho para migrar de VB 6.0 para Web Forms. A Unitech era parceira da Microsoft, e por isso tínhamos acesso às versões beta muito antes do lançamento. Fizemos a pesquisa, os testes e as provas de conceito, treinamos e acompanhamos algumas equipes.

A grande mudança chegou quando fui alocado no projeto SOMAR (Sistema Organizado de Matrícula). Até então o sistema era 100% VB6 com Oracle 7.3 e stored procedures, mas a licitação daquele ano exigia a entrega de uma versão web, algo bastante novo na época. Eu já havia trabalhado em uma empresa de web design e tinha escrito o meu próprio CGI em Delphi (CGI era o mecanismo em que o servidor web executava um programa a cada requisição e devolvia ao navegador o que esse programa escrevesse), então me colocaram no projeto como Plano B. O Plano A era entregar o VB6, que já estava pronto, e ter uma versão web apenas como entregável, sem a expectativa de que fosse usada.

Escolhemos o ASP 3.0, que saiu no mesmo ano que o PHP 4, quando as duas tecnologias ainda eram muito primitivas: basicamente includes e comandos para escrever texto na página, com um JavaScript também muito limitado. Mesmo sem a pressão da entrega, resolvi criar algo que fosse fácil para o desenvolvedor e que escondesse a complexidade de misturar HTML com código. Eu já tinha trabalhado com ColdFusion e com CGI, e tudo era muito técnico, com uma curva de aprendizado alta.

Pensei em como um projeto em C se organiza, com o seu main.c e os seus headers, e adaptei a ideia para a nossa realidade em ASP 3.0. Cada página tinha os seus "headers" e uma função principal:

<!-- #include file="bancodedados.inc" -->
<!-- #include file="seguranca.inc" -->
<!-- #include file="menu.inc" -->
<!-- #include virtual="design.inc" -->   <% ' desenha o layout e chama a Main %>
<%
Sub Main
    ' o que esta página faz: uma listagem, um cálculo, um download
End Sub
%>

Os includes guardavam o código específico de cada assunto, como conectar ao banco ou verificar se o usuário tinha permissão de acesso, e a Main de cada página executava apenas o que aquela página deveria fazer. Quem chamava a Main era o design.inc: ele desenhava o layout, aquele quadradão com topo, menu e rodapé, e sabia em que ponto dele o resultado da página deveria aparecer. Com essa técnica, e reaproveitando as stored procedures que já existiam, o nosso time de quatro pessoas entregou o sistema web, que acabou sendo o protagonista do projeto e o primeiro sistema web da Unitech. Depois eu aprimorei a técnica e a repliquei em outros projetos da empresa, com um ganho enorme de produtividade.

O XMLNuke e o que ele me ensinou​

Ao sair da Unitech resolvi investir no meu "framework". Naquela época o Java difundiu massivamente o uso de XML, que tinha a sua camada de formatação, o XSL. Com os dois eu conseguiria isolar a camada de dados da camada de apresentação. Era uma ideia tentadora, e havia poucas opções na época; na onda dos CMS existiam o PHP-Nuke e o PostNuke.

Criei então o XMLNuke. As classes que você escrevia produziam XML, e uma camada de processamento XSL transformava esse XML em HTML. A primeira versão foi em ASP, continuação natural do que eu tinha feito na Unitech, e o projeto está registrado no SourceForge desde maio de 2002. Em 2003 vieram as versões em Java, C# e PHP, todas com o mesmo jeito de programar. Foi no PHP que eu acabei investindo, porque o ASP era bem mais limitado e porque eu tinha decidido apostar no Linux. A versão de 2003 rodava em PHP 4, depois ficou parada por um bom tempo, e eu só a retomei com o PHP 5, em 2006, que foi a versão que amadureceu. O XMLNuke foi também o meu primeiro código open source: começou em CVS, passou para SVN no SourceForge e, muitos anos depois, foi para o GitHub.

De certa forma o XMLNuke antecipava o que hoje fazemos com APIs REST e JSON, em que o código produz dados e a apresentação fica em outra camada. A diferença é que o JSON é muito mais simples e dispensa um framework para ser lido.

O XMLNuke era um monolito imenso, que precisava de uma estrutura de diretórios específica para rodar. Com ele aprendi que um framework não pode ser monolítico nem engessado, que é mais fácil manter vários componentes pequenos e coesos do que um sistema em que tudo está acoplado, porque nele uma mudança pequena acaba quebrando partes que não tinham nada a ver com ela, e que uma especificação padrão e uma boa documentação são tão importantes quanto o código. Matei o XMLNuke e carreguei as lições.

Essas lições viraram componentes menores. Os componentes me ensinaram a reduzir complexidade e a separar responsabilidades, depois pediram imagens Docker para rodar sempre do mesmo jeito, depois pediram automação para publicar, e assim por diante. Em Como eu consigo manter mais de 30 projetos open source eu contei como isso funcionava quando havia dois pilares, os componentes PHP e as imagens Docker. De lá para cá entraram o DockNimbus, o ByJG Docs MCP, o Parolsh e os repositórios de pacotes, e as peças passaram a cobrir o caminho inteiro.

Construir a aplicação​

Depois do XMLNuke eu relutei muito em ter um framework de novo. Mantive apenas componentes separados e completamente independentes. Os primeiros eu extraí do próprio XMLNuke, ainda na época da MaxMilhas, e cada um passou a ter vida própria. Com o tempo percebi que, sempre que eu usava esses componentes, eu seguia a mesma metodologia: um jeito próprio de escrever e de conectar as peças.

Primeiro registrei esse jeito no PHP Rest Reference Architecture, uma arquitetura de referência que definia as guidelines, mas ainda deixava muita coisa solta. Foi com ela que fiz o site do KingPanda (kingpanda.com.br). Este ano, finalmente, transformei a arquitetura de referência em um framework chamado Gluo, que significa "cola" em esperanto, porque é isso que ele faz com os meus componentes.

Um composer create-project byjg/gluo cria um projeto de API REST que é seu, já com autenticação, migrations, ORM, documentação OpenAPI e a estrutura de testes. É a mesma ideia do index.asp de 2000: o desenvolvedor escreve a regra de negócio e encontra o resto resolvido. Hoje o Gluo roda o BoletimDeUrna.com, o site da ByJG (byjg.com.br) e o sistema de busca de CEP que fica nele.

A diferença em relação ao XMLNuke está por baixo. O Gluo cola componentes que continuam independentes, como o RestServer, o MicroOrm, o Serializer, o Migration e o Config. Cada um tem o seu repositório, os seus testes e o seu ciclo de versões, e pode ser usado sozinho em um projeto Laravel ou Symfony. A parte do framework que evolui fica em vendor/ e é atualizada com um composer update, enquanto o projeto gerado pode ser alterado à vontade.

Testar localmente com as minhas imagens​

O projeto já vem com um docker-compose.yml, e um docker compose up -d sobe a API, o banco de dados e o frontend na minha máquina. Os contêineres são construídos a partir das imagens PHP ByJG, que existem nas variantes CLI, FPM, Nginx e Apache para cada versão do PHP. Eu não preciso instalar nada além do Docker.

Essas imagens nasceram de uma dor antiga: a cada troca de máquina eu reconfigurava PHP, extensões e ferramentas, e sempre faltava alguma coisa, além de precisar de várias versões do PHP ao mesmo tempo. Houve também o dia em que eu precisei do PHP 5.6 para um projeto antigo e as distribuições Linux já nem o traziam mais.

O shellscript.download vem da mesma dor. Com ele eu nem preciso ter o PHP instalado: um load.sh php-docker -- 8.4 cria na minha máquina um comando php que, por baixo, roda dentro do contêiner, e eu simplesmente entro no projeto e trabalho. Para ter outra versão ao lado basta repetir o comando com outro número. O Node funciona do mesmo jeito, e para Java e outras ferramentas há scripts que fazem a instalação com um comando. Contei os detalhes em Desenvolvimento PHP Fácil com Docker e VSCode.

Um ponto importante é o contrato OpenAPI, que eu escrevo uma única vez. O próprio código documenta cada endpoint, com atributos acima do método do controller. Um composer openapi extrai esses atributos para um arquivo openapi.json, e a partir daí o mesmo arquivo faz quatro trabalhos: o RestServer monta as rotas da API a partir dele, o Swagger UI serve as páginas de documentação em que dá para experimentar cada endpoint, o atributo #[ValidateRequest] valida o corpo de cada requisição antes de o método executar e devolve um erro 422 quando ele não segue o contrato, e o Swagger Test roda os testes de contrato, comparando cada resposta com o que foi declarado. Rota, documentação, validação e teste saem da mesma fonte, sem reescrever nem duplicar nada.

Publicar: CI/CD e DockNimbus​

O mesmo pipeline que roda os testes constrói a imagem da aplicação. Para os pipelines eu mantenho o k8s-ci, uma imagem com as ferramentas necessárias para construir e publicar.

Faltava o lugar para onde publicar, e o DockNimbus surgiu dessa demanda. Ter VMs em uma nuvem é prático e muito rápido, principalmente em projetos grandes. Em projetos pequenos, porém, sai mais barato alugar um servidor dedicado pequeno, conectado à internet e não gerenciado, em que você recebe apenas a máquina. Toda vez eu tinha que configurar a rede, proteger o que ficaria exposto, instalar o Kubernetes e assim por diante, e quando havia mais de uma máquina a comunicação entre elas também passava pela internet.

O DockNimbus faz essa configuração por mim, com os padrões de segurança que eu aplicaria à mão. Ele transforma máquinas físicas e VMs, de um Raspberry Pi a um servidor x86, em uma plataforma com computação, armazenamento e clusters Docker Swarm e K3s, tudo declarado em um único manifesto, e liga as máquinas por uma malha WireGuard, de modo que o tráfego entre elas segue criptografado mesmo atravessando a internet. A documentação resume a diferença em relação ao Kubernetes assim: o Kubernetes responde "tenho um cluster, como orquestro contêineres nele?", e o DockNimbus responde "tenho máquinas, como transformo isso em uma plataforma?".

Ele funciona bem para instalações pequenas, que é o meu caso. Eu uso o DockNimbus para gerenciar o meu ambiente local e as minhas duas ASUS Spark GB10, e ele também faz o deploy em produção do site da ByJG, do BoletimDeUrna e do servidor MCP da documentação.

Produção: o mesmo Docker, com load balancer​

A imagem que roda em produção é a mesma que eu testei localmente e que passou pelo CI, então não existe diferença entre ambientes para investigar quando algo dá errado.

Na frente das aplicações fica o EasyHAProxy. Eu gosto muito do HAProxy: ele é muito rápido e trabalha também na camada TCP, então pode ficar na frente de um MySQL, por exemplo, e não apenas de aplicações web. A configuração, porém, é bem complicada. Eu queria automatizá-la, e em 2018, quando comecei o projeto, a versão community do HAProxy não tinha nada parecido.

O EasyHAProxy gera essa configuração sozinho. Ele descobre os serviços pelas labels do Docker, pelos serviços do Swarm ou pelo Ingress do Kubernetes, emite os certificados TLS e recarrega o HAProxy sem derrubar conexões. O próprio DockNimbus usa o EasyHAProxy como load balancer.

Projetos independentes, centralizados por automação​

Este é o ponto que o XMLNuke me ensinou pelo caminho mais difícil. Cada projeto tem o seu repositório, os seus testes e os seus releases, e nenhum depende de outro para ser publicado. O que faz deles um ecossistema é a automação.

Quando um projeto recebe um merge ou uma tag, a automação publica o que ele produz, sem nenhum passo manual, e a documentação, os charts e os pacotes vão todos para o mesmo site:

O padrão é o mesmo em todos os projetos e está descrito nas Development Guidelines: nada é publicado antes de os testes passarem, releases são tags com versão semântica e o CI é escrito uma vez e chamado por cada projeto. As razões estão em Princípios Simples Para Não Complicar o Complexo.

Documentação para humanos e para a IA​

A documentação mora no repositório de cada projeto, ao lado do código, e fala apenas daquele projeto. Quem documenta o MicroOrm escreve sobre o MicroOrm, sem precisar conhecer nem descrever o ecossistema. A documentação completa é gerada pela automação: a cada merge o conteúdo de cada projeto é copiado para o opensource.byjg.com, que monta o site inteiro, e o ByJG Docs MCP indexa o site com busca semântica e por palavra-chave. Qualquer assistente que fale MCP consulta esse índice e cita a página de onde tirou a resposta.

Com isso a documentação é escrita uma vez e passa a ter dois leitores. Um agente que precisa adicionar persistência a uma aplicação ByJG encontra o MicroOrm e a forma prevista de usá-lo, em vez de inventar uma camada de dados.

Com o XMLNuke eu aprendi que especificação e documentação importam. Hoje elas são também o contexto que a IA usa para trabalhar nos meus projetos, e cada mudança documentada melhora a próxima resposta.

O shell e o agente no mesmo lugar: Parolsh​

O Parolsh nasceu de outro motivo. Eu prefiro trabalhar no shell na maior parte do tempo. Quando quero ver os logs de um pod, por exemplo, preciso primeiro listar os pods e depois rodar um kubectl logs para o primeiro, outro para o segundo, o terceiro, o quarto. O Claude Code e o Codex fazem esse tipo de investigação, mas neles tudo parte da linguagem natural e a interface toma conta do terminal, de modo que o trabalho acaba indo todo para a conversa e o shell vira coadjuvante.

No Parolsh as duas coisas convivem no mesmo prompt. Com !+kubectl get pods eu rodo o comando, vejo o resultado e ele já segue junto com a minha próxima pergunta. Aí eu peço os logs, pergunto por que os pods estão reiniciando (o que eu faria com um describe) e ainda posso pedir outras análises, o que acelera muito o processo. O Parolsh roda dentro do terminal de sempre, sem interface em tela cheia, e funciona com qualquer agente ACP, como Claude Code, Codex, Qwen Code e Gemini CLI.

O método, para quem quiser reproduzir​

Nada disso depende das ferramentas ByJG. O que eu descrevi é o resultado de um método que serve para qualquer conjunto de projetos:

1. Automatizar o que é repetitivo. Testes, builds, releases, pacotes e a publicação da documentação rodam no CI.
2. Centralizar o que é compartilhado. Um conjunto de workflows, um site de documentação, um conjunto de imagens base.
3. Isolar o que é independente. Cada componente tem repositório, testes e ciclo de versões próprios, e só a automação os une.
4. Usar o mesmo contêiner em todos os ambientes. Desenvolvimento, CI e produção rodam a mesma imagem.
5. Escrever a documentação uma vez, para dois leitores. Cada projeto documenta a si mesmo, e a automação monta a documentação completa. Uma pessoa lê no site e um assistente de IA lê pelo MCP.

Do index.asp até aqui​

O que eu queria em 2000 com um index.asp e meia dúzia de includes é o que eu continuo querendo: que o desenvolvedor escreva o que a página faz e encontre o resto resolvido. O que mudou foi o tamanho do "resto", que hoje inclui o ambiente local, o pipeline, a plataforma, o load balancer, os pacotes e a documentação que a IA consulta.

Cada projeto continua funcionando sozinho, e ninguém precisa adotar tudo. Para começar por uma API, veja o Gluo. Para colocar HTTPS na frente dos seus serviços, o EasyHAProxy. Para transformar máquinas em plataforma, o DockNimbus. Para dar contexto ao seu assistente de IA, o ByJG Docs MCP. O mapa completo está em O Ecossistema ByJG.

Produtividade com IA: o que realmente funciona​

Faz algum tempo que decidi adotar assistentes de programação, e o ganho de produtividade é absurdo. Consegui documentar minhas bibliotecas e projetos em dias, não meses. Resolvi bugs e issues muito mais rápido. Criei até um automatizador de prompts: tenho 50 projetos, todos precisam de documentação e têm o mesmo prompt — então fiz um script que entra em cada projeto, documenta, verifica se estou seguindo os padrões corretamente, roda os testes, o lint, conserta o que precisa. Maravilhoso.

Mas eu sou muito exigente também. Percebi que, quando peço para a IA criar um documento sem qualquer base inicial, o resultado quase sempre traz frases curtas, muitos parágrafos e vários clichês do tipo "O problema não é... é sobre...", "Não é aquilo, é isso" — comentários de encaixe que deixam o conteúdo vazio. Mesmo me incomodando, para documentação técnica o COMO importa mais do que quantidade de texto, então deixei passar. O melhor fluxo que encontrei foi: eu escrevo um rascunho e uso a IA como revisora. Ela aponta erros de grafia e concordância, reescreve trechos que eu sei o que querem dizer, e aí eu posso opinar, questionar e melhorar.

Pair Programming com IA, não delegação total​

Aqui entra o primeiro ponto importante: eu não delego 100% para a IA. Gostaria muito. Mas sempre chega um ponto em que ela se perde. Repete código. Quando o teste não passa, ela escreve assertTrue(true) e anuncia feliz que agora você tem 1.000 testes funcionando. Vai criando monstrinhos lindos, estilo Gremlins. Quando você percebe, está consumindo recursos e gastando tudo o que tem.

Por isso, minha primeira regra com a IA é: Pair Programming. Eu defino a atividade, normalmente com uma especificação, jogo no Claude Code e peço para me dar um plano. A partir daí, vou ajustando esse plano até ter algo que me atenda. Quando aprovo, vou acompanhando exatamente o que está sendo codado, paro, intervenho, pergunto por que fez aquilo, peço para olhar a definição, aponto para a documentação correta.

Não consigo sentar e "relaxar", mas é muito mais rápido e fico 90% satisfeito com o resultado. Para entender isso fora do contexto de tecnologia: se eu dou um carro para alguém que só quer dirigir, não importa o que eu entregue, desde que ela dirija. Mas eu não quero só dirigir — quero tunar o carro, fazer upgrades, integrar sistemas. E é aí que estar lado a lado ajuda muito.

Claro que há situações em que pouco importa como foi feito. Fiz sites no Lovable (vou chegar lá) completamente por ele — e é isso. Não preciso de mais nada. Mas no âmbito profissional, eu quero um produto que eu possa manter, que no final eu entenda, que possa evoluir, que seja escalável e confiável. Nesse momento estou fora da Vibe. Negócio real não é entregar mais por entregar — é entregar mais com qualidade, onde o resultado seja impecável e eu seja o DONO do processo, não a IA.

O projeto real: modernizando o ByJG.com.br​

Então resolvi testar na prática um cenário em que a IA não é apenas meu par de programação. Tenho o site ByJG.com.br, onde mantenho meu portfólio e alguns serviços — sendo que hoje só o de CEP WebService está ativo. Ele foi escrito por volta de 2010, saiu do deploy por git pull e hoje roda em Kubernetes com CI/CD, mas o código é o mesmo de 2010. Nele eu usava meu antigo framework XMLNuke, que aposentei em 2016, mas cujo código serviu de base para criar minha Arquitetura de Referência em PHP para Projetos REST.

Minha meta era:

• Migrar do PHP 5.6 para o 8.5
• MySQL 5.6 para o 9.0
• Evoluir o layout usando algo mais moderno como Vite ou Next
• Mudar autenticação para JWT
• Manter as APIs antigas funcionando, pois ainda tenho usuários que dependem do serviço

Parece simples, mas se eu fosse contratar um time eu precisaria de:

• Um backend capaz de trabalhar com o legado e o novo
• Um frontend que entendesse de design para fazer o site e conectar com as APIs
• Um redator para ajudar a revisar os textos

Então, atuei como Gerente de Produto técnico Hands-On e contratei o seguinte time:

• Claude Code Max como meu Backend (e FullStack)
• Lovable Pro como meu Frontend
• Emergent.sh como meu Frontend alternativo
• ChatGPT Pro como Solutions Architect, Revisor e Editor de Imagens

Paguei por todos esses serviços.

Lovable vs Emergent.sh: o duelo de frontends​

Tanto o Lovable quanto o Emergent.sh fazem design e implementam o website. Passei o mesmo prompt para ambos. O Emergent.sh, na fase de criação, se saiu melhor: perguntava coisas que não estavam bem definidas, o que gostei muito. Isso me ajudou a refinar o prompt para que fosse mais claro e específico, e fiz um novo projeto em ambos. A primeira versão do Emergent, em todas as tentativas, foi excelente.

Emergent.sh

Lovable

Pontos que analisei em cada um:

O código gerado pelo Emergent parece ter saído de um template à moda antiga: tem uma pasta backend, outra frontend, e exige aquela estrutura para funcionar. O backend usa Python e o frontend usa Craco — um framework abandonado, com várias dependências antigas e vulnerabilidades. Quando o Emergent salva o código no git (o bom é que posso enviar para qualquer repositório e branch), o yarn.lock não era incluído. Quando tentava rodar yarn install, nada era instalado por conta das dependências quebradas.

Foi aí que chamei meu backend Claude, e percebi que ele também era Full-Stack. Ele recomendou migrar para o Vite, explicou os motivos e executou a migração rapidamente. No Lovable, não consegui especificar QUAL repositório git usar, mas ele consegue manter o projeto sincronizado tanto se eu mexesse fora quanto dentro do Lovable — e se vira bem com qualquer framework, o que garante boa continuidade. O deploy do front-end no Emergent.sh custa 50 créditos; no Lovable é gratuito.

Meu veredicto: Preciso contratar um designer que faça o Figma — ainda vou procurar. E o Lovable implementa bem. Com o MVP do frontend mais ou menos encaminhado, passo as integrações e o código mais pesado para meu FullStack, o Claude, e retorno ao Lovable para publicar. No projeto ByJG, vou publicar na Cloudflare — mas isso é outra história.

A migração do código legado​

Na segunda parte, veio a conversão do código legado para o novo. Antes de passar a missão para o Claude, precisei criar a infraestrutura mínima: instalei o projeto de Referência com algumas classes e testes, coloquei o ambiente para rodar e defini as instruções de como testar e como era a arquitetura. Com ambos os ambientes rodando, parti para dar as instruções ao Claude.

A instrução inicial sempre no modo de Planejamento. Em vez de pedir uma conversão total, identifiquei os blocos comuns e comecei a trabalhar neles. Primeiro pedi para criar o Login, Registro e "Esqueci minha senha". Era crítico porque definiria todo o resto. Quando a API estava implementada, pedi para o Claude gerar um Guia de Implementação do Login com fluxos e como lidar com o JWT. Esse guia usei para implementar as telas no frontend. Funcionou bem.

Um detalhe importante: cada atividade era uma sessão diferente do Claude. Isso o força a pesquisar o código, o que, pelo menos para mim, gerou resultados melhores. Depois disso, repeti o processo nos outros módulos do site.

Muitas vezes, quando ele sugere uma mudança que não entendi ou não achei eficiente, eu rejeito e começo assim: "Pergunta: por que utilizou isso e não aquilo?" ou "Você olhou a documentação na pasta X ou no código ABC?" Isso é uma forma de levá-lo a pesquisar mais sobre o código e sugerir soluções melhores. Há situações em que pesquisei no Google sobre o tema para discutir mais tecnicamente, especialmente quando estava em dúvida. E muitas vezes eu dava uma solução, mas deixava aberto para que ele pudesse sugerir alternativas.

As situações irritantes​

Tem situações bem irritantes: 99% das vezes ele sabe como subir a aplicação e testar, pois isso está nas suas instrucões, mas em 1% das vezes ele se perde e fica num loop tentando resolver o problema da forma errada. Nesse caso, eu interrompo, fecho a sessão e começo uma nova dizendo: "Investigue por que isso não funciona" ou "O código da linha X está com erro; o comportamento esperado é A, B, C."

Algumas vezes ele simplesmente não sabe o que fazer, inventa que completou a tarefa quando na verdade não completou (ainda bem que não é CLT), faz uma gambiarra para dizer que os testes passaram. Enfim, tem que vigiar.

Conclusão​

De qualquer forma, fiquei muito satisfeito com o resultado. E não chamo isso de Vibe Coding — seria injusto. Faz parecer menor do que é.

No final, transformei um site completamente desatualizado em algo assim:

Antes​

Depois​

n8n é uma ferramenta genuinamente forte. Como IDE visual para construção de workflows, ela atinge um raro equilíbrio entre acessibilidade e poder: você pode modelar fluxos complexos orientados a eventos, reagir a webhooks e agendamentos, integrar com APIs, plataformas SaaS e bancos de dados, e ainda descer ao nível de Python ou JavaScript real quando a lógica exige. Do ponto de vista de produtividade e expressividade, é muito bem projetada.

O problema não aparece quando você está criando workflows. Ele aparece no momento em que você tenta rodá-los seriamente em produção.

A primeira vez que encontrei o workflow de promoção recomendado construa localmente, copie o workflow, cole em produção eu imediatamente soube que não poderia aceitar esse modelo. Não porque é inconveniente, mas porque quebra alguns dos princípios mais básicos de operação de sistemas em produção. Deploy manual não é uma preferência estilística; é um risco sistêmico.

Uma vez que workflows são promovidos por copiar e colar, você perde o controle quase instantaneamente. Não há forma confiável de entender exatamente o que mudou, nenhum diff significativo, nenhum registro autoritativo de quem deployou o que e quando, e nenhum estado reprodutível que você possa apontar como "a versão atualmente rodando." Pior ainda, qualquer um com acesso à UI de produção ganha implicitamente a habilidade de fazer deploy de lógica que pode disparar sistemas externos, mover dados ou executar código arbitrário. Isso não é apenas desconfortável; é fundamentalmente incompatível com ambientes que valorizam auditabilidade, rastreabilidade e mudança controlada.

Para mim, isso cruza uma linha firme. Eu opero sob uma regra muito simples: nada chega em produção manualmente. Nem aplicações, nem infraestrutura, e nem workflows. Se um sistema não pode ser deployado através de um processo controlado, revisável e repetível, então não é um sistema que eu possa recomendar ou confiar para automação crítica.

A parte frustrante é que n8n não está longe de fazer isso certo. Por baixo dos panos, expõe uma API capaz que permite que workflows sejam listados, criados, substituídos, ativados e desativados programaticamente. Essa API é poderosa o suficiente para construir um modelo adequado de entrega um que não dependa da UI como superfície de deployment. Mesmo a funcionalidade Git Sync disponível nos planos business e enterprise aponta nessa direção, mas permanece largamente orientada pela UI e não abraça completamente o Git como plano de controle.

O que eu queria era direto e sem novidades pelos padrões modernos de engenharia. Eu queria usar n8n local como IDE, não como mecanismo de deployment. Eu queria que Git fosse a fonte da verdade. Eu queria que lógica de workflow especialmente Python e JavaScript vivesse em arquivos reais ao invés de estar enterrada dentro de blobs JSON escapados. Eu queria pull requests, revisão de código, tags de versão e promoção entre ambientes orientada por CI/CD. Mais importante, eu queria que deployments fossem entediantes, determinísticos e reversíveis.

Essa combinação não existia, então eu a construí.

n8n-gitops não é uma alternativa ao n8n; é uma camada de controle em torno dele. O editor visual permanece exatamente onde brilha projetando workflows. A partir daí, workflows são exportados em modo mirror, garantindo que o repositório sempre reflita o verdadeiro estado da instância e que drift seja eliminado ao invés de tolerado. Código é externalizado em arquivos fonte apropriados, tornando revisões legíveis, ferramentas efetivas e mudanças compreensíveis por humanos. Git se torna o lugar onde decisões são discutidas, aprovações acontecem e versões são definidas.

Deployment então para de ser um ato executado por uma pessoa clicando botões e se torna uma operação executada por um pipeline. Uma tag, branch ou commit específico é deployado em uma instância alvo via API. Rollback não é mais um procedimento especial; é simplesmente fazer redeploy de uma referência anterior. Não há ambiguidade sobre o que está rodando, como chegou lá ou como desfazer.

Essa mudança é o que tornou n8n usável para mim em ambientes reais. Antes disso, n8n parecia uma ferramenta poderosa de prototipagem e automação com ressalvas de produção. Depois disso, torna-se um runtime de workflows que pode ser governado com a mesma disciplina que qualquer outro sistema em produção.

A intenção deste projeto não é competir com n8n ou criticar seu foco em usabilidade. Existe para fazer a ponte entre dois mundos que frequentemente colidem: produtividade low-code e rigor de infraestrutura. n8n otimiza para velocidade e acessibilidade; GitOps otimiza para segurança, visibilidade e confiança. n8n-gitops existe para conectar essas prioridades sem forçá-lo a abrir mão de uma pela outra.

Se um motor de workflows pode disparar movimentação de dinheiro, chamar sistemas externos, mutar dados ou executar código arbitrário, então merece os mesmos padrões de entrega que qualquer serviço que você faz deploy. Este projeto é simplesmente uma aplicação dessa realidade.

Meu primeiro emprego profissional foi como instrutor em uma pequena escola de informática, ensinando DOS, WordStar, SuperCalc e dBASE. Um dia me enviaram para treinar o diretor de uma empresa. Ele olhou para mim - um garoto de 17 anos - e perguntou: "Você veio me treinar? Não acha que é jovem demais?"

Eu respirei fundo e respondi: "Eles me mandaram porque acreditam que sou capaz. Vamos fazer assim: já estou aqui e você reservou o tempo. Vou dar a aula de hoje. Se você não gostar, não paga e outra pessoa vem na próxima semana. Se gostar, eu volto." Ele ficou surpreso, deu um meio sorriso e disse: "Fechado!" No final perguntei: "Posso voltar semana que vem?" A resposta dele: "Sim."

Naquele dia aprendi a transformar um momento difícil em uma oportunidade para provar meu valor. Eu poderia ter aceitado a dúvida dele como derrota; em vez disso, usei para mostrar do que era capaz.

Quando estamos procurando um novo emprego, com contas para pagar e família para cuidar, qualquer desafio pode parecer uma ameaça. É fácil encolher. Mas o mundo não define nossos limites - nós definimos. A confiança para se manter firme, entregar e deixar o resultado falar por si é um músculo. Às vezes a gente esquece. Eu esqueci. Revisitar essa memória me lembra que coragem e preparo vencem a dúvida sempre.

Gerenciar dependências entre múltiplos componentes PHP costumava ser um pesadelo. Quando você tem um ecossistema de mais de 30 pacotes interconectados, manter o controle de qual versão funciona com qual versão do PHP — e quais versões são compatíveis entre si — pode rapidamente se tornar algo incontrolável.

Foi por isso que redesenhei completamente a estratégia de versionamento para todos os componentes PHP ByJG. Este post explica a evolução do sistema de versionamento, como ele funciona hoje e como você pode usá-lo efetivamente em seus projetos.

O Problema: Antes do PHP 7.4​

Antes do PHP 7.4, cada componente do ecossistema ByJG tinha seu próprio esquema de versionamento independente.

Isso criava diversos desafios:

• Inferno de Dependências: Era extremamente difícil identificar quais versões de diferentes componentes eram compatíveis entre si
• Confusão de Versões PHP: Não havia uma maneira clara de saber quais versões do PHP uma versão específica de componente suportava
• Pesadelo de Manutenção: Gerenciar patches e atualizações entre componentes com números de versão diferentes era complexo e propenso a erros
• Experiência Ruim para o Desenvolvedor: Usuários tinham que pesquisar manualmente matrizes de compatibilidade antes de instalar componentes

Por exemplo, você poderia ter:

• byjg/anydataset na versão 3.2.1
• byjg/serializer na versão 2.5.0
• byjg/migration na versão 4.1.2

E tentar descobrir quais versões funcionavam juntas — e com qual versão do PHP — exigia vasculhar documentação ou tentativa e erro.

A Solução: Versionamento Padronizado​

A partir do PHP 7.4, introduzi um sistema de versionamento padronizado em todos os componentes ByJG.

O princípio chave é simples:

A versão principal do componente indica quais versões do PHP ele suporta.

Isso cria um padrão claro e previsível que torna o gerenciamento de dependências significativamente mais fácil.

Matriz de Versão para Suporte PHP​

Isso significa:

• Se você está rodando PHP 8.4, deve usar a versão 6.0 dos componentes ByJG
• Se ainda está no PHP 8.2, pode usar a versão 4.9 ou 5.0
• Se precisa suportar PHP 7.4, a versão 4.9 é sua única opção

Benefícios Dessa Abordagem​

1. Clareza Instantânea: Apenas olhando o número da versão, você sabe quais versões do PHP são suportadas
2. Dependências Consistentes: Todos os componentes com a mesma versão principal são projetados para trabalhar juntos
3. Upgrades Simplificados: Ao atualizar o PHP, você atualiza todos os componentes para a versão correspondente
4. Melhor Manutenção: Separação clara entre linhas de versão torna o patch de versões específicas algo direto

Workflow de Desenvolvimento e Estratégia de Branches​

Entender como releases e patches funcionam é crucial tanto para contribuidores quanto para usuários do ecossistema.

A Estratégia da Branch Principal​

O workflow de desenvolvimento segue um padrão direto:

branch main/master
    ↓
Sempre contém a versão mais recente (atualmente 6.0.x)
    ↓
Releases são tagueados diretamente dessa branch

Pontos-Chave:

• A branch main (ou master) sempre contém a versão mais recente do componente
• Todo desenvolvimento de novas funcionalidades acontece na branch main
• Quando um release está pronto, é tagueado diretamente da main (ex: v6.0.0, v6.0.1, etc.)
• Isso garante que a branch main está sempre estável e pronta para release

Branches Específicas de Versão para Patches​

Quando um bug é descoberto em uma versão antiga que ainda precisa de suporte, usamos branches específicas de versão:

Branch 4.9  →  Para patches da versão 4.9.x (PHP 7.4-8.2)
Branch 5.0  →  Para patches da versão 5.0.x (PHP 8.1-8.3)
Branch 6.0  →  Para patches da versão 6.0.x (PHP 8.3-8.5)

Exemplo de Workflow:

1. Um bug crítico é encontrado na versão 5.0.x
2. Crie uma branch de correção a partir da branch 5.0
3. Aplique a correção e faça merge de volta para a branch 5.0
4. Tagueie um novo patch release (ex: v5.0.8)
5. Se aplicável, porte a correção para versões mais novas (6.0 ou main)

Essa abordagem garante:

• Versões antigas permanecem estáveis e podem receber correções críticas
• Sem interferência com o desenvolvimento ativo na branch main
• Separação clara entre manutenção e novas funcionalidades

Melhores Práticas: Usando Componentes em Seu Projeto​

Recomendação #1: Use a Mesma Versão em Todos os Componentes​

Para garantir máxima compatibilidade e evitar conflitos de dependência, sempre use componentes da mesma versão principal.

Má Prática ❌:

{
    "require": {
        "byjg/anydataset": "^5.0",
        "byjg/serializer": "^6.0",
        "byjg/migration": "^4.9"
    }
}

Boa Prática ✅:

{
    "require": {
        "byjg/anydataset": "^6.0",
        "byjg/serializer": "^6.0",
        "byjg/migration": "^6.0"
    }
}

Recomendação #2: Use o Operador Circunflexo (^)​

O operador circunflexo (^) é a maneira recomendada de especificar restrições de versão:

{
    "require": {
        "byjg/anydataset": "^6.0"
    }
}

O que ^6.0 significa:

• Permite qualquer versão >= 6.0.0 e < 7.0.0
• Você receberá atualizações de patch (6.0.1, 6.0.2, etc.) automaticamente
• Você receberá atualizações menores (6.1.0, 6.2.0, etc.) automaticamente
• Você não será automaticamente atualizado para a versão 7.0.0, que seria uma mudança com quebra de compatibilidade

Isso lhe dá o melhor equilíbrio de:

• Estabilidade: Sem mudanças com quebra de compatibilidade de upgrades de versão principal
• Segurança: Atualizações automáticas de patch para correções de bugs
• Funcionalidades: Acesso a novas funcionalidades de versões menores sem intervenção manual

Testando Versões de Desenvolvimento​

Às vezes você precisa testar funcionalidades não lançadas ou ajudar com o desenvolvimento. Existem duas abordagens:

Opção 1: Definir Estabilidade Mínima (Todo o Projeto)​

Essa abordagem diz ao Composer para permitir versões de desenvolvimento para todos os pacotes:

{
    "require": {
        "byjg/anydataset": "^6.0",
        "byjg/serializer": "^6.0"
    },
    "minimum-stability": "dev",
    "prefer-stable": false
}

Como funciona:

• "minimum-stability": "dev" permite ao Composer instalar versões dev
• "prefer-stable": false" diz ao Composer para preferir versões de desenvolvimento sobre estáveis quando disponíveis
• A restrição ^6.0 agora vai corresponder a branches 6.0.x-dev

Quando usar:

• Quando você está ativamente desenvolvendo ou testando múltiplos componentes
• Quando você quer testar o estado mais recente de todo o ecossistema

Cuidado: Isso afeta todas as dependências, não apenas componentes ByJG. Use com cuidado em ambientes de produção.

Opção 2: Fixar Componentes Específicos em Versões Dev​

Essa abordagem é mais direcionada e afeta apenas pacotes específicos:

{
    "require": {
        "byjg/anydataset": "6.0.x-dev",
        "byjg/serializer": "^6.0",
        "byjg/migration": "^6.0"
    }
}

Como funciona:

• "6.0.x-dev" explicitamente solicita a versão de desenvolvimento da branch 6.0
• Outros pacotes continuam usando versões estáveis
• Você pode misturar: testar a versão dev de um componente enquanto mantém outros estáveis

Quando usar:

• Quando testando uma funcionalidade ou correção de bug específica em um único componente
• Quando contribuindo para um componente específico
• Quando você precisa de mais controle sobre quais pacotes usam versões dev

Comandos de Update do Composer​

Após alterar as restrições de versão:

# Atualizar todos os pacotes
composer update

# Atualizar apenas pacotes específicos
composer update byjg/anydataset

# Atualizar todos os pacotes byjg
composer update byjg/*

Estratégia de Migração Entre Versões​

Quando é hora de atualizar para uma nova versão do PHP (e consequentemente uma nova versão de componente), siga esta abordagem:

Passo 1: Verifique Sua Versão Atual do PHP​

php -v

Passo 2: Atualize Seu composer.json​

Altere todas as versões de componentes ByJG para corresponder à sua versão alvo do PHP:

{
    "require": {
        "php": "^8.4",
        "byjg/anydataset": "^6.0",
        "byjg/serializer": "^6.0",
        "byjg/migration": "^6.0",
        "byjg/rest": "^6.0"
    }
}

Passo 3: Execute Composer Update​

composer update

Passo 4: Teste Sua Aplicação​

Execute sua suite de testes para capturar quaisquer mudanças com quebra de compatibilidade:

./vendor/bin/phpunit

Passo 5: Revise os Changelogs​

Verifique os changelogs de cada componente para mudanças com quebra de compatibilidade:

https://opensource.byjg.com/docs/php/[nome-do-componente]/

Ciclo de Vida de Suporte de Versões​

Entender o ciclo de vida de suporte ajuda você a planejar upgrades:

Desenvolvimento Ativo: Novas funcionalidades, melhorias e otimizações Patches de Segurança: Apenas correções de bugs críticos e atualizações de segurança

Exemplo do Mundo Real​

Vamos supor que você está construindo uma nova aplicação de API REST:

Sua Versão do PHP​

$ php -v
PHP 8.4.1

Seu composer.json​

{
    "name": "minhaempresa/api",
    "require": {
        "php": "^8.4",
        "byjg/rest": "^6.0",
        "byjg/anydataset": "^6.0",
        "byjg/migration": "^6.0",
        "byjg/jwt-session": "^6.0",
        "byjg/authuser": "^6.0"
    },
    "require-dev": {
        "phpunit/phpunit": "^11.0"
    }
}

Instalar Dependências​

composer install

Resultado: Composer instala as versões 6.0.x mais recentes de todos os componentes, garantindo:

• ✅ Compatibilidade total com PHP 8.4
• ✅ Todos os componentes funcionam juntos perfeitamente
• ✅ Atualizações automáticas para patches e versões menores
• ✅ Ecossistema estável e testado

Conclusão​

O sistema de versionamento padronizado para componentes PHP ByJG transforma o gerenciamento de dependências de um quebra-cabeça complexo em um processo direto.

Principais Conclusões:

1. Versão do componente = compatibilidade de versão PHP — Versão 6.0 = PHP 8.3/8.4/8.5
2. Sempre use a mesma versão principal em todos os componentes ByJG
3. Use o operador circunflexo (^6.0) para estabilidade e atualizações ótimas
4. Branch main = versão mais recente, branches de versão para patches
5. Duas maneiras de testar versões dev: configurações de estabilidade para todo o projeto ou fixação por pacote

Seguindo essas diretrizes, você terá uma configuração de dependências sustentável e previsível que escala com sua aplicação.

Quer explorar todo o ecossistema? 👉 Visite https://opensource.byjg.com

Precisa verificar quais componentes estão disponíveis? 👉 Navegue pelo catálogo de componentes

Seja você trabalhando com Laravel, Symfony, ou construindo do zero, esses componentes podem ajudá-lo a acelerar o desenvolvimento mantendo qualidade de nível de produção. Pense nisso como uma equipe de pit curada: cada utilitário é leve por si só, mas projetado para se encaixar quando você precisa de todo o pipeline.

O Que Vamos Cobrir​

• Configurar uma estação de trabalho em uma máquina Linux vazia (ou WSL) em minutos
• Entender o catálogo de componentes PHP e quando usar cada peça
• Usar a Arquitetura de Referência PHP REST para criar uma API
• Selecionar imagens Docker fortalecidas para cargas de trabalho de produção
• Operar um fluxo de trabalho realista do dia zero à manutenção contínua

A Jornada: De uma Máquina Vazia à Produção​

Vamos começar do início - uma máquina sem nada instalado - e trabalhar até uma aplicação API completa e pronta para produção.

Passo 1: Configurando seu Ambiente de Desenvolvimento​

Quando você tem uma máquina Linux vazia (ou WSL no Windows), o primeiro desafio é instalar o Docker e PHP sem gastar uma tarde copiando trechos de posts de blog. É aqui que entra o shellscript.download. É um único script de carregamento que fornece instaladores opinativos para que sua equipe possa padronizar toda a stack com comandos de uma linha.

Primeiro, instale o script de carregamento (idempotente e seguro para executar novamente):

/bin/bash -c "$(curl -fsSL https://shellscript.download/install/loader)"

Com o load.sh instalado, você pode instalar ferramentas em etapas separadas. Cada comando verifica pré-requisitos, fixa versões conhecidas e estáveis, e configura serviços da mesma forma em cada servidor.

Instalando o Docker:

load.sh docker

Instalando o PHP 8.4 via Docker:

load.sh php-docker -- 8.4

Instalando o Node.js 22 (para ferramentas modernas de desenvolvimento como Claude Code, Codex, etc.):

load.sh node-docker -- 22

É isso! Em apenas três comandos, você agora tem:

• Docker instalado e executando
• PHP 8.4 pronto para usar via containers Docker
• Node.js 22 para ferramentas modernas de desenvolvimento

A beleza desta abordagem é que tudo roda em containers—sem conflitos de versão, sem inferno de dependências, apenas ambientes limpos e reproduzíveis. Se alguém da sua equipe precisar reconstruir sua estação de trabalho ou se você mudar entre laptops, você está a poucos comandos de ter paridade.

O Ecossistema de Componentes PHP​

Uma vez que seu ambiente está pronto, você ganha acesso a uma extensa coleção de componentes PHP testados em produção que podem ser usados com QUALQUER framework PHP—Laravel, Symfony, Slim, ou sua própria solução customizada. Esses pacotes surgiram de projetos reais de clientes, então cada um resolve um problema operacional específico: configuração, cache, persistência, mensageria, e mais.

Abaixo está um tour guiado agrupado por camada. Use-o como um menu; você pode pegar apenas o que precisa, ou montar a stack completa ao criar um novo serviço.

Componentes de Infraestrutura Essenciais​

Comece com os blocos de construção que mantêm configuração, cache e migrações previsíveis em todos os ambientes.

Cache Engine - Cache compatível com PSR-6 e PSR-16 com múltiplos backends:

• Sistema de arquivos, Redis, Memcached, Session
• Memória compartilhada (ShmOp), TmpFS
• Coleta de lixo integrada e operações atômicas

Config Management - Configuração baseada em ambiente com suporte a injeção de dependência

Migration - Controle de versão de banco de dados com migrações up/down suportando MySQL, PostgreSQL, SQLite, Oracle e SQL Server

Acesso a Dados & ORM​

Em seguida, configure a persistência de dados. A camada AnyDataset oferece acesso unificado a múltiplos bancos de dados, e o Micro-ORM adiciona estrutura suficiente sem prendê-lo em um framework pesado.

Micro-ORM - Mapeamento Objeto-Relacional leve com:

• Query builder
• Suporte ao padrão Active Record
• Suporte ao padrão Repository
• Mapeamento de relacionamentos sem sobrecarga pesada

AnyDataset-DB - Camada de abstração de banco de dados universal suportando múltiplos bancos de dados com uma API consistente

API REST & Web Services​

Com os dados cobertos, exponha-os através de APIs que seguem os contratos que você publica.

RestServer - Crie serviços RESTful com:

• Auto-geração a partir de definições OpenAPI/Swagger
• Múltiplos manipuladores de saída (JSON, XML, HTML)
• Suporte integrado a middleware (CORS, JWT, Static Server)
• Cache de rotas para performance

Swagger Test - Testes de contrato para garantir que sua API corresponda à sua especificação OpenAPI

Segurança & Autenticação​

A autenticação está integrada ao invés de apenas acoplada, para que você possa construir funcionalidades sem reinventar armazenamento de sessão ou fluxos JWT.

AuthUser - Sistema completo de autenticação e autorização de usuários com:

• Gerenciamento de sessões
• Propriedades customizadas
• Múltiplos backends de armazenamento (Database, XML)

JWT Wrapper - Manipulação de JSON Web Token para autenticação stateless

JWT Session - Gerenciamento de sessão baseado em JWT

Crypto - Criptografia simétrica sem senha com geração dinâmica de chaves

Comunicação​

Aplicações modernas raramente operam isoladamente. Esses clientes mantêm a comunicação externa (mail, filas, SMS) consistente.

MailWrapper - Envie e-mails através de múltiplos provedores:

• SMTP (SSL/TLS)
• Amazon SES API
• Mailgun API
• Sendmail

Message Queue Client - Interface unificada para filas de mensagens:

• Suporte a RabbitMQ via rabbitmq-client
• Suporte a Redis Queue via redis-queue-client
• Fácil de implementar conectores customizados

SMS Client - Envie SMS através de vários provedores

Utilitários​

Finalmente, um conjunto de ajudantes focados para tarefas do dia a dia—geração de IDs, manipulação de imagens, conversão e manipulação de URI.

ShortId - Gere IDs curtos, únicos e seguros para URL

ImageUtil - Manipulação e processamento de imagens

Convert - Utilitários de conversão de dados

URI - Manipulação e análise de URI

E muitos mais componentes cobrindo várias necessidades...

Principais Vantagens​

• Agnóstico de Framework: Use qualquer componente independentemente em seus projetos existentes
• Compatível com PSR: Segue os padrões PHP-FIG (PSR-6, PSR-7, PSR-11, PSR-16)
• Bem Documentado: Cada componente tem documentação abrangente com exemplos
• Testado em Produção: Usado em ambientes de produção reais
• Pronto para Composer: Instalação simples via composer require byjg/component-name

Construindo uma Aplicação Completa do Zero​

Embora você possa usar componentes individuais com qualquer framework, e se você quiser criar uma aplicação API completa do zero e manter alta velocidade? É aqui que entra a Arquitetura de Referência PHP REST. Intencionalmente não é outro framework—é um conjunto de opiniões capturadas como código para que você possa fazer fork, adaptá-lo e ainda reconhecer cada parte móvel.

O Que é a Arquitetura de Referência PHP REST?​

A Arquitetura de Referência PHP REST é um template pronto para produção (não um framework) que reúne os melhores componentes do ecossistema ByJG em uma estrutura de aplicação coesa e pronta para uso.

O Que Está Incluído​

O template é dividido em camadas para que você possa continuar ajustando ou afrouxando abstrações dependendo do estágio do seu produto.

Geração de Código & Arquitetura:

• Geração automática de CRUD a partir de tabelas do banco de dados
• Escolha entre Padrão Repository (separação limpa) ou Padrão ActiveRecord (prototipagem rápida)
• Modelos, repositórios, serviços, controllers e testes auto-gerados

Segurança Integrada:

• Sistema de autenticação baseado em JWT
• Controle de Acesso Baseado em Funções (RBAC)
• Endpoints de login prontos para uso

Documentação da API:

• Documentação OpenAPI auto-gerada sincronizada com o código
• Interface Swagger UI interativa para exploração da API
• Testes de contrato para manter os docs sincronizados

Gerenciamento de Banco de Dados:

• Sistema de migração integrado
• MicroORM para acesso leve a dados
• Query builder e mapeamento de relacionamentos

Experiência de Desenvolvimento:

• Containerização Docker (MySQL, PHP-FPM, Nginx)
• Scriptify: terminal PHP interativo e executor de CLI
• Suite abrangente de testes funcionais
• Hot reload durante o desenvolvimento

Pronto para Produção:

• Workflows de CI/CD pré-configurados (GitHub Actions, GitLab CI, Bitbucket Pipelines)
• Configuração baseada em ambiente
• Logging estruturado
• Tratamento e relatório de erros
• Conformidade com padrões PSR-7, PSR-11, PSR-6/16

Começando com a Arquitetura de Referência​

# Instale o template
load.sh php-rest-api -- my-api \
  --namespace=MyCompany \
  --name=mycompany/my-api \
  --install-examples=y

Este único comando cria uma aplicação API completa com:

• Estrutura de projeto seguindo arquitetura limpa
• Migrações de banco de dados prontas
• Sistema de autenticação configurado
• Documentação OpenAPI gerada
• Ambiente Docker configurado
• Pipelines de CI/CD prontos
• Testes configurados

Você pode começar a desenvolver imediatamente com:

cd my-api
docker-compose up -d
composer codegen -- --env=dev --table=users all --save

A partir daqui, você não está procurando stubs ou copiando controllers de projetos anteriores. A geração de código cria scaffolds de endpoints, migrações mantêm o banco de dados sincronizado, e o arquivo OpenAPI permanece acoplado aos handlers reais. Como tudo é compatível com PSR, você pode adicionar qualquer middleware adicional ou reutilizar pacotes familiares.

Implantação em Produção​

O sucesso local é apenas metade da história. Enviar para produção significa escolher imagens em que você pode confiar e uma estratégia de ingress que não vai acordá-lo durante picos de tráfego. O ecossistema inclui imagens Docker curadas e uma camada HAProxy auto-atualizável para que as peças operacionais sejam tão coesas quanto a experiência do desenvolvedor.

Imagens Docker PHP Fortalecidas​

Para implantação em produção, o ecossistema fornece imagens Docker PHP curadas e fortalecidas em segurança suportando:

• Versões PHP: De 5.6 a 8.5 (edge)
• Multi-Arquitetura: AMD64 e ARM64 (Raspberry Pi, AWS Graviton)
• Variantes de Imagem:
  • base - Mínima com mais de 45 extensões PHP (~135MB)
  • cli - Ferramentas de desenvolvimento incluídas (~154MB)
  • fpm - PHP-FPM para configurações customizadas (~139MB)
  • fpm-nginx - Stack LEMP completa (~154MB)
  • fpm-apache - Stack LAMP completa (~154MB)

Recursos de Segurança:

• Executa como usuário não-root (app)
• Inclui SBOM & proveniência de build
• Releases mensais marcadas para estabilidade
• Atualizações regulares de segurança

Exemplo:

docker pull byjg/php:8.4-fpm-nginx-2025.11

Balanceamento de Carga & Ingress​

Para gerenciamento de tráfego em produção, EasyHAProxy fornece configuração dinâmica do HAProxy através de descoberta de serviços. Seja você implantando em Docker Swarm, Kubernetes, ou uma única VM, os mesmos labels configuram certificados, roteamento e estatísticas, o que mantém as operações entediantes (da melhor maneira possível).

Plataformas Suportadas:

• Docker standalone
• Clusters Docker Swarm
• Kubernetes
• Configuração estática manual

Recursos:

• SSL/TLS automático com Let's Encrypt (protocolo ACME)
• Certificados SSL customizados
• Balanceamento de carga entre réplicas
• Recarregamentos de configuração sem downtime
• Suporte a modo TCP
• Painel de estatísticas integrado

Exemplo para Docker Swarm:

docker service create \
  --name my-api \
  --label easyhaproxy.host=api.example.com \
  --label easyhaproxy.ssl.type=letsencrypt \
  mycompany/my-api:latest

O EasyHAProxy detecta automaticamente o serviço, configura o HAProxy, obtém certificados SSL e começa a rotear o tráfego - nenhuma configuração manual necessária!

O Fluxo Completo do Ecossistema​

Veja como tudo se encaixa. O diagrama destaca como um único comando de carregamento se transforma em um template de aplicação, imagens Docker base e, eventualmente, ingress automatizado. Trace as setas para ver como cada peça alimenta o próximo estágio do ciclo de vida:

Fluxo de Trabalho do Mundo Real​

Vamos percorrer um cenário completo do mundo real. Imagine que você tem a tarefa de lançar uma API de comércio antes da próxima sessão de planejamento trimestral. A linha do tempo abaixo espelha como a maioria das equipes realmente se move—há uma explosão de configuração, um bloco de trabalho de funcionalidades, um sprint em automação e, finalmente, uma transferência para operações.

Dia 1: Configuração do Projeto​

# Configure o ambiente (uma vez)
/bin/bash -c "$(curl -fsSL https://shellscript.download/install/loader)"
load.sh docker
load.sh php-docker -- 8.4

# Crie um novo projeto
load.sh php-rest-api -- my-shop-api \
  --namespace=MyShop \
  --name=mycompany/shop-api

cd my-shop-api
docker-compose up -d

Dia 2-10: Desenvolvimento​

# Gere CRUD completo para a tabela de produtos
composer codegen -- --env=dev --table=products all --save

# Adicione notificações por e-mail usando MailWrapper
composer require byjg/mailwrapper

# Adicione processamento de fila para tarefas assíncronas
composer require byjg/redis-queue-client

# Execute os testes
composer test

Durante esta fase você está iterando rapidamente: adicione capacidades via Composer, apoie-se no CRUD gerado para evitar trabalho repetitivo e mantenha a confiança alta com a suite de testes integrada.

Semana 2: Configuração de CI/CD​

• Envie para GitHub
• Workflows de CI/CD já configurados (GitHub Actions)
• Testes automáticos em cada PR
• Build da imagem Docker no merge para main

Não há correria para montar workflows—o template já incluiu .github/workflows (e equivalentes para GitLab/Bitbucket), então habilitar CI é uma questão de conectar secrets e deixar o pipeline executar.

Mês 1: Implantação em Produção​

# Baixe a imagem pronta para produção
docker pull byjg/php:8.4-fpm-nginx-2025.11

# Construa a imagem da sua aplicação usando-a como base
docker build -t mycompany/shop-api:1.0.0 .

# Implante no Docker Swarm com EasyHAProxy
docker service create \
  --name shop-api \
  --replicas 3 \
  --label easyhaproxy.host=api.shop.com \
  --label easyhaproxy.ssl.type=letsencrypt \
  --label easyhaproxy.port=8080 \
  mycompany/shop-api:1.0.0

No momento em que você implanta, você já sabe qual tag de imagem Docker está mirando, e o EasyHAProxy mantém a configuração de ingress consistente. Escalar para mais réplicas ou apontar um hostname de staging para o mesmo serviço é uma mudança de label, não uma edição manual do HAProxy.

Sua API agora está:

• Executando com 3 réplicas para alta disponibilidade
• Balanceamento de carga automático
• Protegida com SSL Let's Encrypt
• Monitorada via estatísticas do HAProxy
• Pronta para escalar

Por Que Este Ecossistema?​

Depois de seguir o fluxo de trabalho vale a pena dar um passo atrás. Por que investir nesta coleção ao invés de misturar pacotes aleatórios do Packagist? Estas são as âncoras que mantêm a experiência coesa:

1. Consistência Entre Ambientes​

As mesmas imagens Docker rodam em desenvolvimento, CI/CD e produção - eliminando problemas de "funciona na minha máquina".

2. Desenvolvimento Rápido​

Vá da ideia para uma API funcionando em minutos, não dias. A geração de código cuida do boilerplate enquanto você foca na lógica de negócio.

3. Qualidade de Nível de Produção​

Autenticação, autorização, logging, tratamento de erros e testes integrados significam que você começa com melhores práticas, não dívida técnica.

4. Liberdade de Framework​

Use componentes individualmente em projetos existentes ou adote a arquitetura de referência completa para novos projetos.

5. Práticas Modernas de DevOps​

Pronto para CI/CD, containerizado, com infraestrutura como código. Implante em qualquer plataforma de orquestração de containers.

6. Sem Aprisionamento de Fornecedor​

É um template, não um framework. Você é dono do código. Modifique qualquer coisa que precisar.

7. Documentação Abrangente​

Cada componente está documentado com exemplos em opensource.byjg.com

Resumo dos Componentes do Ecossistema​

Se você só puder lembrar de cinco links, faça-os serem estes:

Começando​

Pronto para construir sua próxima aplicação PHP com este ecossistema? Veja como começar, dependendo de onde seu projeto está atualmente:

1. Para Projetos Existentes: Navegue pela biblioteca de componentes e adicione componentes individuais via Composer

2. Para Novas APIs: Use o template Arquitetura de Referência PHP REST

3. Para Configuração de Ambiente: Visite shellscript.download para scripts de instalação

4. Para Produção: Confira Imagens Docker PHP e EasyHAProxy

Conclusão​

O ecossistema PHP ByJG fornece uma solução completa e coesa para desenvolvimento PHP moderno - do seu primeiro comando em uma máquina vazia até uma aplicação API escalável e pronta para produção.

Ao combinar:

• Configuração de ambiente simples
• Componentes modulares e reutilizáveis
• Templates prontos para produção
• Imagens Docker fortalecidas
• Balanceamento de carga automatizado

Você pode focar em construir funcionalidades ao invés de infraestrutura, mantendo qualidade de nível profissional ao longo de todo o ciclo de vida do desenvolvimento.

Seja você construindo um pequeno microsserviço ou uma aplicação complexa, este ecossistema tem as ferramentas que você precisa para ter sucesso.

Explore o ecossistema:

• Documentação: https://opensource.byjg.com
• GitHub: https://github.com/byjg
• Scripts de Configuração: https://shellscript.download

Boa codificação!

Manter mais de 30 projetos open source é quase como tocar uma orquestra sozinho. Cada projeto tem suas particularidades, dependências, pipelines, documentações e testes — e, ainda assim, todos precisam funcionar em harmonia.
Em uma empresa com 30 microserviços, é comum ter algo como 2 a 4 DevOps, 3 a 5 Product Owners e 50 a 100 desenvolvedores.
Eu faço isso praticamente sozinho.

Parece impossível? Vamos entender como esse ecossistema funciona, e como a automação, padronização e um bom uso de Inteligência Artificial tornam isso não apenas viável, mas prazeroso.

O Que Eu Mantenho​

Meu foco é em dois grandes pilares:

• Um ecossistema de componentes PHP — que inclui desde micro-ORMs e serializers até integrações REST completas.
• Um conjunto de imagens Docker — utilizadas tanto em desenvolvimento quanto em produção, que garantem consistência e reprodutibilidade em qualquer ambiente.

Esses projetos se interconectam, formando uma arquitetura modular e reutilizável. Assim, qualquer componente pode ser usado de forma independente em outros frameworks, mas também todos podem trabalhar juntos dentro do meu ecossistema principal.

Criando um Ambiente de Developer Experience​

O primeiro passo foi resolver o que mais me atrapalhava: o setup de desenvolvimento.
Cada nova máquina exigia configurar dezenas de dependências — PHP, extensões, Composer, ferramentas de teste, etc. Sempre faltava alguma coisa.

A solução foi criar imagens Docker padronizadas.
Hoje eu mantenho imagens PHP para diferentes usos:

• CLI
• FPM
• FPM com Nginx
• Exemplos prontos com Docker Compose

Essas imagens são utilizadas em ambientes de desenvolvimento, CI/CD e produção, o que elimina variações e “works on my machine”.

Mas o desafio maior era lidar com várias versões do PHP em uma mesma máquina. Como já usava Docker, decidi: o ambiente de desenvolvimento também rodaria em containers.
Padronizei tudo em Linux e fui testando ferramentas até criar o projeto shellscript.download.

Hoje, para preparar meu ambiente, basta rodar:

load.sh php-docker -- 8.4

E tudo está pronto — do PHP ao Composer e extensões, em minutos.

Automação e Padronização de Processos​

Ter 30 projetos é como ter 30 microserviços: cada um com sua documentação, arquitetura, dependências e ciclo de vida.
A chave é automação.

Desde 2013, venho aperfeiçoando cada projeto individualmente, mantendo testes automatizados, cobertura de código significativa e integração contínua.

Mas havia um problema: a documentação.
Manter docs espalhadas entre repositórios é um pesadelo. Precisava centralizar tudo sem duplicar trabalho.

A Solução​

Criei um pipeline que, ao dar merge em um PR, copia automaticamente a documentação do projeto para um repositório central — o byjg.github.io.
Esse repositório organiza o conteúdo dentro da estrutura do Docusaurus e dispara um build automático no Cloudflare Pages, publicando tudo em https://opensource.byjg.com.

Assim, cada commit documentado já atualiza o site principal automaticamente — sem manutenção manual e sem custo adicional.

No final, foquei em três princípios:

1. Automatizar o que é repetitivo
2. Centralizar o que é compartilhado
3. Isolar o que é independente

Criando um Ecossistema Sustentável​

Meus componentes PHP seguem rigorosamente os padrões PSR, usam Composer para versionamento e podem ser integrados em qualquer framework.
Cada projeto possui exemplos, testes e instruções de uso.

Com o tempo, percebi que a soma desses componentes formava uma base sólida para algo maior.
Assim nasceu o PHP Rest Reference Architecture — um projeto que combina os principais componentes do ecossistema em uma estrutura pronta para uso:

• CI/CD configurado
• Suporte completo a OpenAPI
• Autenticação e autorização integradas
• Migração de banco de dados
• Injeção de dependência
• Docker e scripts de build

Com um único comando, posso criar um projeto PHP REST funcional em minutos:

load.sh php-rest-api -- <folder> --namespace=<name> --name=<name/name> --install-examples=n

Essa automação permite que qualquer pessoa crie uma API completa com base em boas práticas e arquitetura limpa — sem reinventar a roda.

Preparando para Produção​

As imagens Docker que uso em desenvolvimento são as mesmas usadas em CI/CD e produção.
Elas são publicadas no Container Registry, o que me permite promover versões entre ambientes (dev → staging → production) com total rastreabilidade.

Para o balanceamento de carga, criei o projeto Easy HAProxy — uma versão simplificada e poderosa do HAProxy que se auto-configura com base nos labels Docker.

Ele suporta SSL, evita downtime, e elimina a necessidade de editar manualmente arquivos de configuração.
Basta subir o container e deixar ele cuidar do resto.

Inteligência Artificial: O Meu Novo “Estagiário”​

A IA tem sido minha aliada em várias frentes — e, honestamente, um verdadeiro game changer.

Documentação​

Criei prompts personalizados que cobrem 95% das minhas necessidades: desde gerar guias consistentes até evitar erros de formatação que quebram o Docusaurus.

Design e Frontend​

Meu foco sempre foi backend, e antes a criação de interfaces era lenta.
Hoje descrevo o que quero, e a IA gera a base da interface — me permitindo focar em lógica e integração.

Desenvolvimento Assistido​

Uso o Claude Code como meu principal assistente técnico, o ChatGPT como segunda opinião, e o Junie (PHPStorm) para refino de código.
Nunca deixo a IA agir totalmente sozinha — eu a trato como um pair programmer júnior: reviso, oriento e ajusto o caminho.
Peço planos, discuto soluções e tomo as decisões finais.

Isso multiplicou minha produtividade sem comprometer a qualidade.

O Que Está Por Trás de Tudo Isso​

Infraestrutura​

• Imagens Docker otimizadas
• Balanceamento de carga com Easy HAProxy
• Imagem Builder para CI/CD

Automação​

• Pipelines CI/CD padronizados
• Reaproveitamento de workflows entre projetos
• Ansible e Terraform para provisionamento
• Scripts Python para gerenciamento do GitHub

Conclusão​

Manter dezenas de projetos open source não é uma questão de tempo, é uma questão de sistema.
Quando cada parte do processo é automatizada, documentada e integrada, o trabalho escala naturalmente.

O segredo está em criar um ecossistema coeso, onde cada componente se apoia no outro — e onde o desenvolvedor se torna não apenas o autor, mas o orquestrador de um ambiente autossustentável.

No final do dia, eu foco em um projeto por vez, faço o melhor possível, e deixo que a automação e a padronização cuidem do resto.
E é assim que, quase sozinho, mantenho 30+ projetos vivos, documentados e evoluindo continuamente.

Quer ver tudo isso em ação?
👉 Explore em https://opensource.byjg.com

O Que Você Vai Conseguir​

Ao final deste tutorial, você terá:

• PHP rodando inteiramente em containers Docker
• Suporte completo de debugging com Xdebug no VSCode
• Capacidade de executar scripts PHP individuais
• Servidor de desenvolvimento PHP embutido
• Zero instalação de PHP no seu sistema host

Pré-requisitos​

• Docker instalado e rodando
• Visual Studio Code instalado
• Familiaridade básica com linha de comando

Passo 1: Instalar PHP via Docker Wrapper​

Vamos usar o shellscript.download, uma coleção de scripts prontos para uso que facilitam a instalação.

Primeiro, instale o Loader:

/bin/bash -c "$(curl -fsSL https://shellscript.download/install/loader)"

E então execute este único comando para instalar o PHP 8.4 via Docker:

load.sh php-docker -- 8.4

Isso cria um script wrapper em ~/.shellscript/bin/php8.4 que executa o PHP dentro de um container Docker. A beleza desta abordagem é que o PHP roda em completo isolamento. Seu sistema host permanece limpo!

O script também adiciona ~/.shellscript/bin ao seu PATH, então você pode:

• Chamar php8.4 diretamente de qualquer lugar no seu terminal
• Usar php como um alias (automaticamente aponta para sua versão padrão do PHP)

Teste:

php8.4 --version
php --version  # Usa o alias

load.sh php-docker -- 8.3
load.sh php-docker -- 8.2

Passo 2: Instalar Extensões do VSCode​

Você precisa de duas extensões para desenvolvimento PHP com debugging:

1. PHP Debug por Xdebug

   • ID da Extensão: xdebug.php-debug
   • Fornece integração com Xdebug para debugging de código PHP

2. PHP Intelephense (recomendado) ou PHP IntelliSense

   • ID da Extensão: bmewburn.vscode-intelephense-client
   • Fornece inteligência de código, autocompletar e mais

Instale-as via VSCode:

1. Pressione Ctrl+Shift+X (ou Cmd+Shift+X no Mac) para abrir Extensões
2. Busque por "PHP Debug" e instale
3. Busque por "PHP Intelephense" e instale

Passo 3: Configurar as Definições do VSCode​

Abra suas configurações do VSCode (.vscode/settings.json no seu projeto ou configurações globais) e adicione:

{
    "php.executables": {
        "8.4": "/home/SEU_USUARIO/.shellscript/bin/php8.4"
    },
    "php.version": "8.4",
    "php.debug.port": [9003]
}

"php.executables": {
    "8.3": "/home/SEU_USUARIO/.shellscript/bin/php8.3"
},
"php.version": "8.3",

Passo 4: Configurar as Configurações de Launch​

Crie ou atualize .vscode/launch.json na raiz do seu projeto:

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Listen for Xdebug",
            "type": "php",
            "request": "launch",
            "port": 9003,
            "pathMappings": {
                "/workdir": "${workspaceFolder}"
            }
        },
        {
            "name": "PHP Debug Current Script",
            "type": "php",
            "request": "launch",
            "program": "${file}",
            "cwd": "${fileDirname}",
            "port": 9003,
            "pathMappings": {
                "/workdir": "${workspaceFolder}"
            },
            "runtimeArgs": [
                "-dxdebug.start_with_request=yes"
            ],
            "env": {
                "XDEBUG_MODE": "debug,develop",
                "XDEBUG_CONFIG": "client_port=9003"
            }
        },
        {
            "name": "PHP Run Open Script",
            "type": "php",
            "request": "launch",
            "program": "${file}",
            "cwd": "${fileDirname}",
            "noDebug": true,
            "pathMappings": {
                "/workdir": "${workspaceFolder}"
            }
        },
        {
            "name": "PHP Built-in Server",
            "type": "php",
            "request": "launch",
            "runtimeArgs": [
                "-S",
                "localhost:8080",
                "-t",
                "/workdir"
            ],
            "port": 9003,
            "pathMappings": {
                "/workdir": "${workspaceFolder}"
            },
            "noDebug": false,
            "serverReadyAction": {
                "pattern": "Development Server \\(http://localhost:([0-9]+)\\) started",
                "uriFormat": "http://localhost:%s",
                "action": "openExternally"
            }
        },
        {
            "name": "PHP Built-in Server (no debug)",
            "type": "php",
            "request": "launch",
            "runtimeArgs": [
                "-S",
                "localhost:8080",
                "-t",
                "/workdir"
            ],
            "noDebug": true,
            "serverReadyAction": {
                "action": "openExternally"
            }
        },
        {
            "name": "PHPUnit All Tests",
            "type": "php",
            "request": "launch",
            "program": "${workspaceFolder}/vendor/bin/phpunit",
            "cwd": "${workspaceFolder}",
            "port": 9003,
            "pathMappings": {
                "/workdir": "${workspaceFolder}"
            },
            "env": {
                "XDEBUG_MODE": "debug,develop",
                "XDEBUG_CONFIG": "client_port=9003"
            }
        },
        {
            "name": "PHPUnit Current File",
            "type": "php",
            "request": "launch",
            "program": "${workspaceFolder}/vendor/bin/phpunit",
            "args": [
                "${file}"
            ],
            "cwd": "${workspaceFolder}",
            "port": 9003,
            "pathMappings": {
                "/workdir": "${workspaceFolder}"
            },
            "env": {
                "XDEBUG_MODE": "debug,develop",
                "XDEBUG_CONFIG": "client_port=9003"
            }
        },
        {
            "name": "PHPUnit All Tests (no debug)",
            "type": "php",
            "request": "launch",
            "program": "${workspaceFolder}/vendor/bin/phpunit",
            "cwd": "${workspaceFolder}",
            "noDebug": true,
            "pathMappings": {
                "/workdir": "${workspaceFolder}"
            }
        },
        {
            "name": "PHPUnit Current File (no debug)",
            "type": "php",
            "request": "launch",
            "program": "${workspaceFolder}/vendor/bin/phpunit",
            "args": [
                "${file}"
            ],
            "cwd": "${workspaceFolder}",
            "noDebug": true,
            "pathMappings": {
                "/workdir": "${workspaceFolder}"
            }
        }
    ]
}

Passo 5: Testar Sua Configuração​

Crie um arquivo de teste simples test.php:

<?php

function greet($name) {
    $greeting = "Olá, $name!";
    return $greeting;
}

function calculate($a, $b) {
    $sum = $a + $b;
    $product = $a * $b;
    return [
        'sum' => $sum,
        'product' => $product,
        'average' => $sum / 2
    ];
}

echo "=== Testando Configuração PHP ===\n\n";

$name = "Desenvolvedor";
echo greet($name) . "\n\n";

$result = calculate(10, 5);
echo "Cálculos para 10 e 5:\n";
echo "Soma: {$result['sum']}\n";
echo "Produto: {$result['product']}\n";
echo "Média: {$result['average']}\n\n";

echo "Versão do PHP: " . phpversion() . "\n";
echo "Xdebug carregado: " . (extension_loaded('xdebug') ? 'Sim' : 'Não') . "\n";

Usando Sua Nova Configuração​

Executando um Script Sem Debugging​

1. Abra test.php
2. Pressione F5 ou clique no botão Run
3. Selecione "PHP Run Open Script"
4. Veja a saída no Debug Console

Fazendo Debug de um Script​

1. Defina um breakpoint clicando à esquerda do número da linha (tente na linha com $greeting = ...)
2. Pressione F5
3. Selecione "PHP Debug Current Script"
4. A execução pausará no seu breakpoint
5. Inspecione variáveis, avance no código passo a passo, etc.

Executando o Servidor Embutido​

1. Crie um arquivo index.php na raiz do seu projeto
2. Pressione F5
3. Selecione "PHP Built-in Server" ou "PHP Built-in Server (no debug)"
4. Seu navegador abrirá automaticamente em http://localhost:8080
5. Defina breakpoints nos seus arquivos PHP e atualize a página para fazer debug

Como Funciona​

A mágica acontece no script wrapper criado pelo shellscript.download. Ele:

1. Converte caminhos de arquivo absolutos para caminhos relativos
2. Monta seu diretório de projeto como /workdir no container Docker
3. Executa o PHP dentro do container com Xdebug configurado
4. Usa --network host para que o Xdebug possa se conectar de volta ao VSCode

Tudo isso acontece de forma transparente. Você apenas escreve código PHP e faz debug como se o PHP estivesse instalado localmente!

Benefícios Desta Abordagem​

✅ Sistema Limpo: Nenhuma instalação de PHP poluindo seu sistema
✅ Múltiplas Versões: Execute diferentes versões do PHP para diferentes projetos
✅ Ambiente Consistente: Mesmo ambiente PHP em diferentes máquinas
✅ Debug Completo: Suporte completo ao Xdebug com breakpoints, inspeção de variáveis, etc.
✅ Atualizações Fáceis: Atualize o PHP apenas mudando o script wrapper
✅ Dependências Isoladas: Cada container é isolado com suas próprias extensões

Solução de Problemas​

"Could not connect to debugging client"​

Certifique-se de que o VSCode está escutando o Xdebug. Você deve ver "Listening to Xdebug on port 0.0.0.0:9003" no Debug Console quando iniciar o debugging.

"Address already in use" ao iniciar o servidor​

O servidor ainda está rodando de uma execução anterior. Pare-o clicando no ícone de lixeira no terminal onde ele está rodando, ou pressione Ctrl+C.

Problemas de caminho​

Certifique-se de que seu pathMappings mapeia corretamente /workdir para a pasta do seu workspace. Isso diz ao Xdebug como traduzir caminhos do container para seus caminhos locais.

Conclusão​

Com esta configuração, você tem um ambiente profissional de desenvolvimento PHP que é:

• Fácil de configurar (apenas alguns minutos!)
• Fácil de manter
• Portável entre máquinas
• Completamente isolado do seu sistema host

Sem mais conflitos de dependências, sem mais problemas de "funciona na minha máquina", e sem mais instalações complexas de PHP. Apenas puro desenvolvimento PHP containerizado e eficiente!

Bom código! 🚀

Elime tudo o que é desnecessário - EASY​

EASY é um mantra que carrego comigo. Código tem que ser EASY. EASY é um jogo de palavras em ingles que eu criei e que significa FACIL e também a sigla de Eliminate all Stupidy Yields. Se está difícil, está errado. Se você está quebrando a cabeça horas e horas para fazer algo funcionar, provavelmente o problema não é a sua persistência, é a sua abordagem. Complexidade excessiva não é sinônimo de genialidade, é só desperdício de energia. Quando percebo que entrei nesse ciclo, eu paro. Literalmente. Fecho a IDE, vou descansar, e no dia seguinte volto zerado. Muitas vezes com git checkout -- . e uma tela em branco. E não tenho vergonha de dizer: foi assim que encontrei algumas das minhas melhores soluções.

KISS – Keep It Stupidly Simple​

KISS significa "mantenha isso estupidamente simples". Existe uma beleza em soluções simples que só quem já lutou contra a complexidade consegue enxergar. O pipe no Linux é uma dessas obras de arte: a saída de um comando vira a entrada de outro. Nada mais elegante. O mesmo vale para uma hash function que resolve problemas enormes em O(1). Então, não se engane: mais linhas de código não significam mais robustez. Muitas vezes, é só sinal de que você não quis simplificar.

DRY – Don’t Repeat Yourself​

Aqui não tem meio termo. "não repita você mesmo". Código duplicado é uma dívida que cobra juros altos. Se você copia e cola, está plantando uma bomba-relógio para a manutenção futura. E não é só uma questão técnica, é uma questão de postura: você está dizendo para si mesmo que prefere o atalho ao invés de encarar a arquitetura de frente. O preço vem depois, e geralmente é você mesmo que paga.

Pra sorrir, tem que fazer sorrir​

Essa frase do filme Tropa de Elite pode soar estranha aqui, mas faz todo sentido. Quer que o banco de dados te dê respostas rápidas? Então aprenda a fazer ele sorrir também. Conheça os índices, entenda como os dados são armazenados, como as queries são otimizadas. O ponto é simples: se você não entende a ferramenta que usa, não adianta esperar que ela resolva seus problemas. É como colocar um novato para pilotar um avião: não vai acabar bem.

Testes, testes, testes​

Se tem algo que separa programadores medianos de programadores confiáveis é o hábito de testar. Não estou falando de “rodar em staging” ou “mandar pra produção e ver se funciona”. Estou falando de criar testes que garantam a saúde do seu código. Ter bons testes é dormir tranquilo. É poder refatorar sem medo. Eu já fiz mudanças gigantes em código legado com confiança total porque sabia que a bateria de testes estava lá para me proteger. E vou te dizer: não existe liberdade maior para um programador do que essa.

Problema é Covarde​

O problema é covarde porque ele nunca aparece sozinho. Ele sempre vem em bando. O bug que estourou na aplicação pode estar ligado a uma query lenta, que por sua vez está ligada a um índice mal configurado, que na verdade começou quando o servidor de logs estava atrasado em processar eventos. Quando isso acontece, não basta olhar só para a sua parte do código. É preciso ter domínio do sistema como um todo: do código à infraestrutura, dos logs aos gráficos de monitoramento. E mais do que isso, é preciso ter uma equipe preparada para atuar junto, cada um enxergando o pedaço que domina, mas com a visão coletiva de onde está a raiz. Resolver problemas não é sobre ser herói sozinho. É sobre ter consciência de que o problema é covarde. E por isso você precisa estar preparado para enfrentá-lo em grupo.

Fechando a conta​

No fundo, nada disso é revolucionário. São princípios simples, quase banais. Mas se você os ignora, é questão de tempo até cair no buraco da complexidade desnecessária. Escrever sistemas complexos não é sobre mostrar que você sabe complicar. É sobre ter disciplina para simplificar, clareza para enxergar o essencial e coragem para recomeçar quando o caminho está errado.

Introduction​

OpenSource ByJG is a toolbox of small, framework-agnostic components you can mix and match as you like. The project leans heavily into the KISS principle (“keep it simple”), prioritizing short, composable libraries over heavyweight frameworks — you can see that spirit across its PHP component catalog and philosophy pages.

Among these, byjg/serializer shines as a pragmatic way to move data between objects, arrays and wire formats (JSON, XML, YAML) — including handy copy/mapping helpers when shapes don’t match 1:1.

It installs with one line:

composer require byjg/serialize

The library converts any object/array/stdClass to array, and then formats that to JSON, XML, YAML, or plain text. It also parses from JSON/YAML/PHP-serialized strings into arrays, and lets you filter/transform fields and even read PHP 8 attributes on the fly. Under the hood, it sticks to lean dependencies (json, symfony/yaml, simplexml). Opensource ByJG

Basic: from anything to anything​

Let’s start with a tiny model and go through the everyday moves.

<?php

use ByJG\Serializer\Serialize;

final class User
{
    public function __construct(
        private int $id,
        private string $name,
        private ?string $email = null,
    ) {}

    public function getId(): int { return $this->id; }
    public function getName(): string { return $this->name; }
    public function getEmail(): ?string { return $this->email; }
}

$user = new User(1, 'João', null);

// 1) Object → array
$asArray = Serialize::from($user)->toArray();

// 2) Array → YAML (JSON/XML similar)
$yaml = Serialize::from($asArray)->toYaml();

// 3) PHP’s own serialized string (use PHP core for output)
$phpSerialized = serialize($asArray);

// 4) Back from a PHP-serialized string → array
$backToArray = Serialize::fromPhpSerialize($phpSerialized)->toArray();

The calls above mirror the documented API for converting “from anything to array”, formatting arrays and objects to JSON/XML/YAML, and parsing from JSON/YAML/PHP serialized strings back to arrays.

Another examples:

<?php
use ByJG\Serializer\Serialize;

// From PHP's native serialize()
$serialized = serialize(['a' => 1, 'b' => 2]);
$parsed = Serialize::fromPhpSerialize($serialized)->toArray();
// [ 'a' => 1, 'b' => 2 ]

// From JSON
$json = '{"foo": "bar"}';
$parsedJson = Serialize::fromJson($json)->toYaml();
// foo: bar

// From YAML
$yaml = "foo: bar\nanswer: 42\n";
$parsedYaml = Serialize::fromYaml($yaml)->toJson();
// {"foo":"bar","answer":42}

Useful modifiers at a glance

<?php
use ByJG\Serializer\Serialize;

$result = Serialize::from($customer)
    ->withDoNotParseNullValues()  // drop nulls
    ->withOnlyString()            // coerce values to strings
    ->withMethodPattern('/([^A-Za-z0-9])/') // customize getter->property mapping
    ->toArray();

Other outputs

<?php
use ByJG\Serializer\Serialize;

echo Serialize::from(['k' => 'v'])->toJson();
echo Serialize::from(['k' => 'v'])->toXml();
echo Serialize::from(['k' => 'v'])->toPlainText();

Read PHP 8 Attributes and transform values​

You can parse attributes and transform each property as you go — a powerful hook for masking, formatting, or adding metadata.

<?php

use ByJG\Serializer\Serialize;

#[Attribute]
final class Label {
    public function __construct(public string $text) {}
}

final class Product {
    #[Label('SKU')]
    public string $id = 'A-123';

    #[Label('Pretty name')]
    public string $name = 'Fuzzy Panda';
}

$prod = new Product();

$out = Serialize::from($prod)->parseAttributes(
    // Callback receives ($attributeInstance, $value, $keyName, $propertyName, $getterName)
    function ($attr, $value, $key, $prop, $getter) {
        // If the attribute exists, append its label
        return $attr ? "{$value} ({$attr->text})" : $value;
    },
    Label::class // Only parse this attribute type
    // , $flags (optional)
);

print_r($out);
// [ 'id' => 'A-123 (SKU)', 'name' => 'Fuzzy Panda (Pretty name)' ]

This callback-based attribute parsing is part of the Serialize API.

ObjectCopy: move data between arrays and objects​

ObjectCopy moves data between arrays/objects, even when property names differ. You can rename properties, switch case styles, and alter values on the fly.

Here a basic example:

<?php
use ByJG\Serializer\ObjectCopy;

class UserDto
{
    public int $id;
    public string $name;
}

$payload = ['id' => 10, 'name' => 'Ana'];
$dto = new UserDto();
ObjectCopy::copy($payload, $dto);
// $dto->id === 10; $dto->name === 'Ana'

And another copying from one DTO into another DTO

<?php
use ByJG\Serializer\ObjectCopy;

class SourceDto { public int $idModel = 1; public string $clientName = 'John'; }
class TargetDto { public int $idModel; public string $clientName; }

$source = new SourceDto();
$target = new TargetDto();
ObjectCopy::copy($source, $target);

Advanced: camelCase to snake_case

<?php
use ByJG\Serializer\ObjectCopy;
use ByJG\Serializer\Property\CamelToSnakeCase;

class Source
{
    public int $idModel = 1;
    public string $clientName = 'John';
    public int $age = 30;
}

class Target
{
    public int $id_model;
    public string $client_name;
    public int $age;
}

$source = new Source();
$target = new Target();
ObjectCopy::copy($source, $target, new CamelToSnakeCase());

Advanced: snake_case to camelCase

<?php
use ByJG\Serializer\ObjectCopy;
use ByJG\Serializer\Property\SnakeToCamelCase;

class Source { 
    public int $id_model = 1; 
    public string $client_name = 'John'; 
    public int $age = 30; 
}
class Target { 
    public int $idModel; 
    public string $clientName; 
    public int $age; 
}

$source = new Source();
$target = new Target();
ObjectCopy::copy($source, $target, new SnakeToCamelCase());

Advanced: map different property names explicitly

<?php
use ByJG\Serializer\ObjectCopy;
use ByJG\Serializer\Property\DifferentTargetProperty;

class Source { 
    public int $id_model = 1; 
    public string $client_name = 'John'; 
    public int $age = 30; 
}
class Target { 
    public int $SomeId; 
    public string $SomeName; 
    public int $SomeAge; 
}

$source = new Source();
$target = new Target();

ObjectCopy::copy(
    $source,
    $target,
    new DifferentTargetProperty([
        'id_model' => 'SomeId',
        'client_name' => 'SomeName',
        'age' => 'SomeAge',
    ])
);

Advanced: apply value conversions while copying

<?php
use ByJG\Serializer\ObjectCopy;

$payload = [
    'birth_date' => '2024-12-31',
    'amount' => 123.45,
    'name' => 'john',
];

class InvoiceDto
{
    public \DateTimeImmutable $birthDate;
    public int $amountCents;
    public string $name;
}

$target = new InvoiceDto();

$changeValue = function (string $sourceName, string $targetName, $value) {
    if ($targetName === 'birthDate') {
        return new \DateTimeImmutable($value);
    }
    if ($targetName === 'amountCents') {
        return (int) round($value * 100);
    }
    if ($targetName === 'name') {
        return ucfirst($value);
    }
    return $value;
};

ObjectCopy::copy($payload, $target, null, $changeValue);

Other special conversion cases

• Provide your own property pattern callback to dynamically match names (prefixes, different setters, etc.).
• Combine a property pattern and a value transformer in the same copy call.
• Use ObjectCopyInterface to add copyFrom/copyTo to your DTOs, so they can ingest/emit data directly.

<?php
use ByJG\Serializer\ObjectCopy;
use ByJG\Serializer\ObjectCopy as ObjectCopyBase; // if you prefer extending

class MyDto extends ObjectCopyBase {}

$dto = new MyDto();
$dto->copyFrom(['id' => 1, 'name' => 'Alice']);  // from array/object to this DTO
$dto->copyTo($another);                           // from this DTO into another object/array

Wrap-up

If you need pragmatic, framework-agnostic data shaping in PHP, byjg/serializer delivers:

• Serialize to read and emit arrays/JSON/YAML/XML and parse PHP-serialized data—with handy modifiers.
• ObjectCopy to move data between arrays and objects, rename or retarget fields, switch case styles, and transform values inline.

Explore the full docs for more patterns and edge cases:

• https://opensource.byjg.com/docs/php/serializer/serialize
• https://opensource.byjg.com/docs/php/serializer/objectcopy
• https://opensource.byjg.com/docs/php/serializer/objectcopyinterface