It all started with an index.asp​

It all started in the year 2000, when I worked at Unitech, an outsourcing company serving the government. I was part of the Research and Development group, and one of our missions was to validate whether .NET 1.0 was a good path to migrate from VB 6.0 to Web Forms. Unitech was a Microsoft partner, so we had access to the beta versions long before the release. We did the research, the tests and the proofs of concept, and we trained and followed a few teams.

The big change came when I was assigned to the SOMAR project (Sistema Organizado de Matrícula, the school enrolment system of the state of Bahia). Until then the system was 100% VB6 with Oracle 7.3 and stored procedures, but that year's public tender required a web version to be delivered, which was quite new at the time. I had already worked at a web design company and had written my own CGI in Delphi (CGI was the mechanism in which the web server ran a program on every request and sent back to the browser whatever that program wrote), so they put me on the project as Plan B. Plan A was to deliver the VB6 version, which was already done, and to have a web version only as a deliverable, with no expectation that it would be used.

We chose ASP 3.0, which came out in the same year as PHP 4, when both technologies were still very primitive: basically includes and commands to write text to the page, with a JavaScript that was also very limited. Even without the pressure of the delivery, I decided to create something that was easy for the developer and that hid the complexity of mixing HTML with code. I had already worked with ColdFusion and with CGI, and everything was very technical, with a steep learning curve.

I thought about how a C project is organized, with its main.c and its headers, and adapted the idea to our reality in ASP 3.0. Each page had its "headers" and a main function:

<!-- #include file="bancodedados.inc" -->
<!-- #include file="seguranca.inc" -->
<!-- #include file="menu.inc" -->
<!-- #include virtual="design.inc" -->   <% ' draws the layout and calls Main %>
<%
Sub Main
    ' what this page does: a listing, a calculation, a download
End Sub
%>

The includes held the code specific to each subject, such as connecting to the database or checking whether the user had permission, and the Main of each page ran only what that page was supposed to do. The one calling Main was design.inc: it drew the layout, that big box with a header, a menu and a footer, and knew at which point of it the page's result should appear. With this technique, and reusing the stored procedures that already existed, our team of four people delivered the web system, which ended up being the protagonist of the project and the first web system at Unitech. Later I refined the technique and replicated it in other projects of the company, with a huge gain in productivity.

XMLNuke and what it taught me​

When I left Unitech I decided to invest in my own "framework". At that time Java massively spread the use of XML, which had its formatting layer, XSL. With the two of them I could isolate the data layer from the presentation layer. It was a tempting idea, and there were few options back then; in the CMS wave there were PHP-Nuke and PostNuke.

So I created XMLNuke. The classes you wrote produced XML, and an XSL processing layer transformed that XML into HTML. The first version was in ASP, a natural continuation of what I had done at Unitech, and the project has been registered on SourceForge since May 2002. In 2003 came the versions in Java, C# and PHP, all with the same way of programming. PHP was where I ended up investing, because ASP was far more limited and because I had decided to bet on Linux. The 2003 version ran on PHP 4, then it sat idle for a long time, and I only picked it up again with PHP 5, in 2006, which was the version that matured. XMLNuke was also my first open source code: it started in CVS, moved to SVN on SourceForge and, many years later, went to GitHub.

In a way XMLNuke anticipated what we do today with REST APIs and JSON, where the code produces data and the presentation lives in another layer. The difference is that JSON is much simpler and needs no framework to be read.

XMLNuke was a huge monolith that needed a specific directory structure to run. With it I learned that a framework cannot be monolithic or rigid, that it is easier to maintain several small, cohesive components than a system in which everything is coupled, because there a small change ends up breaking parts that had nothing to do with it, and that a standard specification and good documentation are as important as the code. I killed XMLNuke and carried the lessons with me.

Those lessons became smaller components. The components taught me how to reduce complexity and separate responsibilities, then they asked for Docker images to always run the same way, then they asked for automation to publish, and so on. In How I Manage 30+ Open Source Projects I told how this worked when there were two pillars, the PHP components and the Docker images. Since then DockNimbus, ByJG Docs MCP, Parolsh and the package repositories have joined, and the pieces now cover the whole path.

Build the application​

After XMLNuke I was very reluctant to have a framework again. I kept only separate and completely independent components. The first ones I extracted from XMLNuke itself, back in my MaxMilhas days, and each of them took on a life of its own. Over time I noticed that, whenever I used those components, I followed the same methodology: my own way of writing and connecting the pieces.

First I recorded that way in the PHP Rest Reference Architecture, a reference architecture that defined the guidelines but still left a lot loose. It is what I used to build the KingPanda website (kingpanda.com.br). This year I finally turned the reference architecture into a framework called Gluo, which means "glue" in Esperanto, because that is what it does with my components.

A composer create-project byjg/gluo creates a REST API project that is yours, already with authentication, migrations, ORM, OpenAPI documentation and the test structure. It is the same idea as the index.asp of 2000: the developer writes the business rule and finds the rest already solved. Today Gluo runs BoletimDeUrna.com, the ByJG website (byjg.com.br) and the Brazilian postal code (CEP) lookup service that lives in it.

The difference from XMLNuke is underneath. Gluo glues together components that remain independent, such as RestServer, MicroOrm, Serializer, Migration and Config. Each one has its own repository, its own tests and its own release cycle, and can be used on its own in a Laravel or Symfony project. The part of the framework that evolves lives in vendor/ and is updated with a composer update, while the generated project can be changed freely.

Test locally with my own images​

The project already comes with a docker-compose.yml, and a docker compose up -d brings up the API, the database and the frontend on my machine. The containers are built from the ByJG PHP images, which exist in CLI, FPM, Nginx and Apache variants for each PHP version. I do not need to install anything besides Docker.

Those images were born from an old pain: every time I switched machines I reconfigured PHP, extensions and tools, and something was always missing, besides needing several PHP versions at the same time. There was also the day I needed PHP 5.6 for an old project and the Linux distributions no longer shipped it.

shellscript.download comes from the same pain. With it I do not even need PHP installed: a load.sh php-docker -- 8.4 creates on my machine a php command that, underneath, runs inside the container, and I simply enter the project and work. To have another version side by side I repeat the command with another number. Node works the same way, and for Java and other tools there are scripts that do the installation with one command. I told the details in Easy PHP Development with Docker and VSCode.

An important point is the OpenAPI contract, which I write only once. The code itself documents each endpoint, with attributes above the controller method. A composer openapi extracts those attributes into an openapi.json file, and from then on the same file does four jobs: RestServer builds the API routes from it, Swagger UI serves the documentation pages where each endpoint can be tried out, the #[ValidateRequest] attribute validates the body of each request before the method runs and returns a 422 error when it does not follow the contract, and Swagger Test runs the contract tests, comparing each response with what was declared. Route, documentation, validation and test come from the same source, with nothing rewritten or duplicated.

Deploy: CI/CD and DockNimbus​

The same pipeline that runs the tests builds the application image. For the pipelines I maintain k8s-ci, an image with the tools needed to build and deploy.

What was missing was the place to deploy to, and DockNimbus came out of that need. Having VMs in a cloud is practical and very fast, especially in large projects. In small projects, however, it is cheaper to rent a small dedicated server, connected to the internet and unmanaged, where all you get is the machine. Every time I had to configure the network, protect what would be exposed, install Kubernetes and so on, and when there was more than one machine the communication between them also went over the internet.

DockNimbus does that configuration for me, with the security standards I would apply by hand. It turns physical machines and VMs, from a Raspberry Pi to an x86 server, into a platform with compute, storage and Docker Swarm and K3s clusters, all declared in a single manifest, and it links the machines through a WireGuard mesh, so the traffic between them stays encrypted even when crossing the internet. The documentation sums up the difference from Kubernetes like this: Kubernetes answers "I have a cluster, how do I orchestrate containers on it?", and DockNimbus answers "I have machines, how do I turn them into a working platform?".

It works well for small installations, which is my case. I use DockNimbus to manage my local environment and my two ASUS Spark GB10 machines, and it also deploys to production the ByJG website, BoletimDeUrna and the documentation MCP server.

Production: the same Docker, with a load balancer​

The image that runs in production is the same one I tested locally and that went through CI, so there is no difference between environments to investigate when something goes wrong.

In front of the applications sits EasyHAProxy. I like HAProxy a lot: it is very fast and also works at the TCP layer, so it can sit in front of a MySQL server, for example, and not only in front of web applications. Its configuration, however, is quite complicated. I wanted to automate it, and in 2018, when I started the project, the community version of HAProxy had nothing like it.

EasyHAProxy generates that configuration by itself. It discovers the services from Docker labels, Swarm services or Kubernetes Ingress, issues the TLS certificates and reloads HAProxy without dropping connections. DockNimbus itself uses EasyHAProxy as its load balancer.

Independent projects, centralized by automation​

This is the point XMLNuke taught me the hard way. Each project has its own repository, its own tests and its own releases, and none of them depends on another to be published. What makes them an ecosystem is automation.

When a project is merged or tagged, automation publishes what it produces, with no manual step, and the documentation, the charts and the packages all go to the same site:

The standard is the same in every project and is described in the Development Guidelines: nothing is published before the tests pass, releases are tags with semantic versions, and CI is written once and called by each project. The reasons are in Simple Principles to Avoid Overcomplicating the Complex.

Documentation for humans and for AI​

The documentation lives in each project's repository, next to the code, and talks only about that project. Whoever documents MicroOrm writes about MicroOrm, without needing to know or describe the ecosystem. The complete documentation is generated by automation: on every merge the content of each project is copied to opensource.byjg.com, which assembles the whole site, and ByJG Docs MCP indexes the site with semantic and keyword search. Any assistant that speaks MCP queries that index and cites the page the answer came from.

This way the documentation is written once and gains two readers. An agent that needs to add persistence to a ByJG application finds MicroOrm and the intended way to use it, instead of inventing a data layer.

With XMLNuke I learned that specification and documentation matter. Today they are also the context the AI uses to work on my projects, and each documented change improves the next answer.

The shell and the agent in the same place: Parolsh​

Parolsh was born for another reason. I prefer to work in the shell most of the time. When I want to see the logs of a pod, for example, I first have to list the pods and then run a kubectl logs for the first one, another for the second, the third, the fourth. Claude Code and Codex do this kind of investigation, but in them everything starts from natural language and the interface takes over the terminal, so the work ends up going entirely into the conversation and the shell becomes a supporting actor.

In Parolsh the two live in the same prompt. With !+kubectl get pods I run the command, see the result, and it already goes along with my next question. Then I ask for the logs, ask why the pods are restarting (what I would do with a describe) and can still ask for other analyses, which speeds up the process a lot. Parolsh runs inside the usual terminal, with no full-screen interface, and works with any ACP agent, such as Claude Code, Codex, Qwen Code and Gemini CLI.

The method, for anyone who wants to reproduce it​

None of this depends on the ByJG tools. What I described is the result of a method that works for any set of projects:

1. Automate what is repetitive. Tests, builds, releases, packages and documentation publishing run in CI.
2. Centralize what is shared. One set of workflows, one documentation site, one set of base images.
3. Isolate what is independent. Each component has its own repository, tests and release cycle, and only automation joins them.
4. Use the same container in every environment. Development, CI and production run the same image.
5. Write the documentation once, for two readers. Each project documents itself, and automation assembles the complete documentation. A person reads it on the site and an AI assistant reads it through MCP.

From index.asp to here​

What I wanted in 2000 with an index.asp and half a dozen includes is what I still want: that the developer writes what the page does and finds the rest already solved. What changed was the size of "the rest", which today includes the local environment, the pipeline, the platform, the load balancer, the packages and the documentation the AI consults.

Each project still works on its own, and nobody needs to adopt everything. To start with an API, see Gluo. To put HTTPS in front of your services, EasyHAProxy. To turn machines into a platform, DockNimbus. To give context to your AI assistant, ByJG Docs MCP. The complete map is in The ByJG Ecosystem.

AI Productivity: What Actually Works​

Some time ago I decided to adopt AI coding assistants, and the productivity gain is absurd. I managed to document my libraries and projects in days, not months. I fixed bugs and resolved issues much faster. I even built a prompt automator: I have 50 projects, they all need documentation, and they all share the same prompt — so I wrote a script that goes into each project, documents it, checks that I'm following the right patterns, runs the tests, runs the linter, and fixes what needs fixing. Wonderful.

But I'm also very critical. I noticed that when I ask the AI to create a document without any initial draft, the result almost always has short sentences, lots of paragraphs, and several clichés like "The problem isn't... it's about...", "It's not that, it's this" — filler comments that leave the content hollow. Even though it bothers me, for technical documentation the HOW matters more than word count, so I let it go. The best workflow I found is: I write a rough draft and use the AI as my reviewer. It catches spelling and grammar errors, rewrites passages where I know what I mean but haven't said it clearly, and then I can give opinions, challenge suggestions, and improve.

Pair Programming with AI, Not Full Delegation​

Here's the first important point: I don't delegate 100% to the AI. I wish I could. But there's always a point where it loses the thread. It repeats code. When a test fails, it writes assertTrue(true) and happily announces you now have 1,000 passing tests. It keeps spawning cute little monsters, Gremlins-style. By the time you notice, it's consuming resources and burning through everything you have.

That's why my first rule with AI is: Pair Programming. I define the task — usually with a specification — throw it into Claude Code and ask for a plan. From there, I refine that plan until it gives me something I can work with. Once I approve, I watch exactly what's being coded, stop it, step in, ask why it did something a certain way, ask it to look at the spec, point it to the right documentation.

I can't sit back and "relax," but it's much faster, and I end up 90% happy with the result. To explain this outside of tech: if I hand a car to someone who just wants to drive, it doesn't matter what I give them, as long as they can drive. But I don't just want to drive — I want to tune the car, upgrade it, integrate systems. That's where being side by side helps a lot.

Of course, there are situations where how it was built doesn't matter much. I built some sites on Lovable (I'll get there) entirely through it — and that's it. I don't need anything else. But professionally, I want a product I can maintain, that I understand at the end, that I can evolve, that scales, and that I can rely on. At that point, I'm out of the Vibe. Real business isn't about shipping more for the sake of it — it's about shipping more with quality, where the result is solid and I am the OWNER of the process, not the AI.

The Real Project: Modernizing ByJG.com.br​

So I decided to test in practice a scenario where AI isn't just my pair programmer. I have the site ByJG.com.br, where I host my portfolio and some services — only the CEP WebService is still active today. It was written around 2010, originally deployed via git pull, and now runs on Kubernetes with CI/CD — but the code is the same as 2010. It used my old XMLNuke framework, which I retired in 2016, but whose code served as the foundation for my PHP Reference Architecture for REST projects.

My goals were:

• Migrate from PHP 5.6 to 8.5
• MySQL 5.6 to 9.0
• Modernize the layout using something like Vite or Next
• Switch authentication to JWT
• Keep the old APIs working, since I still have users who depend on the service

Sounds simple, but if I were hiring a team I'd need:

• A backend developer able to work with both the legacy and the new code
• A frontend developer who understands design, to build the site and wire up the APIs
• A technical writer to help review the copy

So I acted as a Hands-On Technical Product Manager and hired this team:

• Claude Code Max as my Backend (and FullStack)
• Lovable Pro as my Frontend
• Emergent.sh as my alternative Frontend
• ChatGPT Pro as Solutions Architect, Reviewer, and Image Editor

I paid for all of these services.

Lovable vs Emergent.sh: The Frontend Showdown​

Both Lovable and Emergent.sh handle design and implement the website. I gave them the same prompt. Emergent.sh performed better in the creation phase: it asked clarifying questions about things that weren't well defined, which I really appreciated. That helped me sharpen the prompt to be clearer and more specific, and I started a new project in both. The first version from Emergent, in every attempt, was excellent.

Emergent.sh

Lovable

Points I evaluated in each:

The code generated by Emergent looks like it came from an old-school template: there's a backend folder, a frontend folder, and the whole thing requires that exact structure to work. The backend uses Python and the frontend uses Craco — an abandoned framework with several outdated dependencies and known vulnerabilities. When Emergent saved the code to git (to its credit, I could push to any repository and branch), the yarn.lock wasn't included. When I tried running yarn install, nothing installed because of the broken dependencies.

That's when I called in my backend Claude, and realized he was also Full-Stack. He recommended migrating to Vite, explained why, and executed the migration quickly. With Lovable, I couldn't specify WHICH git repository to use, but it keeps the project in sync whether I modify things outside of it or inside Lovable — and it handles any framework well, which makes for good project continuity. Deploying the front-end on Emergent.sh costs 50 credits; on Lovable it's free.

My verdict: I still need to find a designer who works with Figma. And Lovable implements well. With the frontend MVP roughly in shape, I hand the integrations and heavier code to my FullStack, Claude, then go back to Lovable to publish. For the ByJG project specifically, I'll be publishing to Cloudflare — but that's another story.

Migrating the Legacy Code​

The second part was the conversion from legacy to new code. Before handing the mission to Claude, I had to set up the minimal infrastructure: I installed the Reference project with some classes and tests, got the environment running, and defined instructions for how to test and how the architecture was organized. With both environments running, I started giving Claude its instructions.

The initial instruction always goes in Planning mode. Instead of asking for a full conversion, I identified the common blocks and worked through them one at a time. First I asked it to build Login, Registration, and "Forgot my password." That was critical because it would define everything else. Once the API was implemented, I asked Claude to generate a Login Implementation Guide covering the flows and how to handle JWT. I used that guide to implement the frontend screens. It worked smoothly.

One important detail: each task was a separate Claude session. That forces it to search through the code from scratch, which, at least in my experience, produces better results. After that, I repeated the process for the other modules of the site.

Often, when it suggests a change I don't understand or don't think is efficient, I reject it and start like this: "Question: why did you use this instead of that?" or "Did you look at the documentation in folder X or in code ABC?" That's a way to push it to dig deeper into the codebase and suggest better solutions. There are situations where I Googled the topic to have a more technical discussion, especially when I wasn't sure. And many times I'd offer a solution but leave it open for the AI to suggest alternatives.

The Frustrating Situations​

There are some genuinely frustrating situations: 99% of the time it knows how to start the application and run tests, but in 1% of cases it gets lost and ends up in a loop trying to solve the problem the wrong way. When that happens, I stop it, close the session, and start a new one saying: "Investigate why this isn't working" or "The code at line X has an error; the expected behavior is A, B, C."

Sometimes it simply doesn't know what to do, claims to have finished a task when it actually hasn't (good thing it's not on payroll), and hacks something together to make the tests pass. In short — you have to keep watch.

Conclusion​

Either way, I'm very happy with the results. And I don't call this Vibe Coding — that would be unfair. It makes it sound like less than it is.

In the end, I took a site that was completely behind the times and turned it into this:

Before​

After​

n8n is a genuinely strong tool. As a visual IDE for building workflows, it strikes a rare balance between accessibility and power: you can model complex event-driven flows, react to webhooks and schedules, integrate with APIs, SaaS platforms, and databases, and still drop down into real Python or JavaScript when the logic demands it. From a productivity and expressiveness standpoint, it is very well designed.

The problem does not appear when you are creating workflows. It appears the moment you try to run them seriously in production.

The first time I encountered the recommended promotion workflow build locally, copy the workflow, paste it into production I immediately knew I could not accept that model. Not because it is inconvenient, but because it breaks some of the most basic principles of operating production systems. Manual deployment is not a stylistic preference; it is a systemic risk.

Once workflows are promoted by copy and paste, you lose control almost instantly. There is no reliable way to understand exactly what changed, no meaningful diff, no authoritative record of who deployed what and when, and no reproducible state you can point to as "the version currently running." Even worse, anyone with access to the production UI implicitly gains the ability to deploy logic that can trigger external systems, move data, or execute arbitrary code. That is not just uncomfortable; it is fundamentally incompatible with environments that value auditability, traceability, and controlled change.

For me, this crosses a hard line. I operate under a very simple rule: nothing reaches production manually. Not applications, not infrastructure, and not workflows. If a system cannot be deployed through a controlled, reviewable, and repeatable process, then it is not a system I can confidently recommend or rely on for critical automation.

The frustrating part is that n8n is not far from doing this right. Under the hood, it exposes a capable API that allows workflows to be listed, created, replaced, activated, and deactivated programmatically. That API is powerful enough to build a proper delivery model one that does not rely on the UI as a deployment surface. Even the Git Sync feature available in business and enterprise plans hints in this direction, but it remains largely UI-driven and does not fully embrace Git as the control plane.

What I wanted was straightforward and unremarkable by modern engineering standards. I wanted to use local n8n as an IDE, not as a deployment mechanism. I wanted Git to be the source of truth. I wanted workflow logic especially Python and JavaScript to live in real files instead of being buried inside escaped JSON blobs. I wanted pull requests, code review, version tags, and CI/CD-driven promotion across environments. Most importantly, I wanted deployments to be boring, deterministic, and reversible.

That combination did not exist, so I built it.

n8n-gitops is not an alternative to n8n; it is a control layer around it. The visual editor remains exactly where it shines designing workflows. From there, workflows are exported in mirror mode, ensuring that the repository always reflects the true state of the instance and that drift is eliminated rather than tolerated. Code is externalized into proper source files, making reviews readable, tooling effective, and changes understandable by humans. Git becomes the place where decisions are discussed, approvals happen, and versions are defined.

Deployment then stops being an act performed by a person clicking buttons and becomes an operation executed by a pipeline. A specific tag, branch, or commit is deployed to a target instance via the API. Rollback is no longer a special procedure; it is simply redeploying a previous reference. There is no ambiguity about what is running, how it got there, or how to undo it.

This shift is what made n8n usable for me in real environments. Before this, n8n felt like a powerful prototyping and automation tool with production caveats. After this, it becomes a workflow runtime that can be governed with the same discipline as any other production system.

The intent of this project is not to compete with n8n or criticize its focus on usability. It exists to bridge two worlds that often collide: low-code productivity and infrastructure rigor. n8n optimizes for speed and approachability; GitOps optimizes for safety, visibility, and trust. n8n-gitops exists to connect those priorities without forcing you to give one up for the other.

If a workflow engine can trigger money movement, call external systems, mutate data, or execute arbitrary code, then it deserves the same delivery standards as any service you deploy. This project is simply an enforcement of that reality.

My first professional job was as an instructor in a small computer school, teaching DOS, WordStar, SuperCalc, and dBASE. One day I was sent to train a company director. He looked at me - a 17-year-old kid - and asked: "You're here to train me? Don't you think you're too young?"

I took a breath and answered: "They sent me because they believe I'm capable. Let's do this: I'm already here and you blocked the time. I'll teach today's lesson. If you don't like it, you don't pay and someone else comes next week. If you like it, I'll be back."

He looked surprised, smirked, and said: "Deal!" At the end I asked, "Can I come next week?" His answer: "Yes."

That day I learned how to turn a difficult moment into an opportunity to prove my value. I could have accepted his doubt as defeat; instead, I used it to show what I could do.

When we're hunting for a new job, bills to pay and family responsibilities can make every challenge feel like a threat. It's easy to shrink. But the world doesn't get to define our limits: we do. The confidence to stand your ground, deliver, and let the result speak for itself is a muscle. We all forget it sometimes. I did. Revisiting that memory reminds me that courage and preparation beat doubt every time.

Managing dependencies across multiple PHP components used to be a nightmare. When you have an ecosystem of 30+ interconnected packages, keeping track of which version works with which PHP version — and which versions are compatible with each other — can quickly become overwhelming.

That's why I completely redesigned the versioning strategy for all ByJG PHP components. This post explains the evolution of the versioning system, how it works today, and how you can use it effectively in your projects.

The Problem: Before PHP 7.4​

Before PHP 7.4, each component in the ByJG ecosystem had its own independent versioning scheme.

This created several challenges:

• Dependency Hell: It was extremely difficult to identify which versions of different components were compatible with each other
• PHP Version Confusion: There was no clear way to know which PHP versions a specific component version supported
• Maintenance Nightmare: Managing patches and updates across components with different version numbers was complex and error-prone
• Poor Developer Experience: Users had to manually research compatibility matrices before installing components

For example, you might have:

• byjg/anydataset at version 3.2.1
• byjg/serializer at version 2.5.0
• byjg/migration at version 4.1.2

And trying to figure out which versions worked together — and with which PHP version — required digging through documentation or trial and error.

The Solution: Standardized Versioning​

Starting with PHP 7.4, I introduced a standardized versioning system across all ByJG components.

The key principle is simple:

The component major version indicates which PHP versions it supports.

This creates a clear, predictable pattern that makes dependency management significantly easier.

Version to PHP Support Matrix​

This means:

• If you're running PHP 8.4, you should use version 6.0 of ByJG components
• If you're still on PHP 8.2, you can use version 4.9 or 5.0
• If you need to support PHP 7.4, version 4.9 is your only option

Benefits of This Approach​

1. Instant Clarity: Just by looking at the version number, you know which PHP versions are supported
2. Consistent Dependencies: All components with the same major version are designed to work together
3. Simplified Upgrades: When upgrading PHP, you upgrade all components to the corresponding version
4. Better Maintenance: Clear separation between version lines makes patching specific versions straightforward

Development Workflow and Branch Strategy​

Understanding how releases and patches work is crucial for both contributors and users of the ecosystem.

The Main Branch Strategy​

The development workflow follows a straightforward pattern:

main/master branch
    ↓
Always contains the latest version (currently 6.0.x)
    ↓
Releases are tagged directly from this branch

Key Points:

• The main (or master) branch always contains the latest version of the component
• All new feature development happens on the main branch
• When a release is ready, it's tagged directly from main (e.g., v6.0.0, v6.0.1, etc.)
• This ensures the main branch is always stable and ready for release

Version-Specific Branches for Patches​

When a bug is discovered in an older version that still needs support, we use version-specific branches:

Branch 4.9  →  For patching version 4.9.x (PHP 7.4-8.2)
Branch 5.0  →  For patching version 5.0.x (PHP 8.1-8.3)
Branch 6.0  →  For patching version 6.0.x (PHP 8.3-8.5)

Workflow Example:

1. A critical bug is found in version 5.0.x
2. Create a fix branch from the 5.0 branch
3. Apply the fix and merge it back to the 5.0 branch
4. Tag a new patch release (e.g., v5.0.8)
5. If applicable, port the fix to newer versions (6.0 or main)

This approach ensures:

• Older versions remain stable and can receive critical fixes
• No interference with active development on the main branch
• Clear separation between maintenance and new features

Best Practices: Using Components in Your Project​

Recommendation #1: Use the Same Version Across All Components​

To ensure maximum compatibility and avoid dependency conflicts, always use components from the same major version.

Bad Practice ❌:

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

Good Practice ✅:

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

Recommendation #2: Use the Caret Operator (^)​

The caret operator (^) is the recommended way to specify version constraints:

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

What ^6.0 means:

• Allows any version >= 6.0.0 and < 7.0.0
• You'll receive patch updates (6.0.1, 6.0.2, etc.) automatically
• You'll receive minor updates (6.1.0, 6.2.0, etc.) automatically
• You won't automatically upgrade to version 7.0.0, which would be a breaking change

This gives you the best balance of:

• Stability: No breaking changes from major version upgrades
• Security: Automatic patch updates for bug fixes
• Features: Access to new minor version features without manual intervention

Testing Development Versions​

Sometimes you need to test unreleased features or help with development. There are two approaches:

Option 1: Set Minimum Stability (Project-Wide)​

This approach tells Composer to allow development versions for all packages:

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

How it works:

• "minimum-stability": "dev" allows Composer to install dev versions
• "prefer-stable": false" tells Composer to prefer development versions over stable ones when available
• The ^6.0 constraint will now match 6.0.x-dev branches

When to use:

• When you're actively developing or testing multiple components
• When you want to test the bleeding edge of the entire ecosystem

Caution: This affects all dependencies, not just ByJG components. Use with care in production environments.

Option 2: Pin Specific Components to Dev Versions​

This approach is more targeted and only affects specific packages:

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

How it works:

• "6.0.x-dev" explicitly requests the development version of the 6.0 branch
• Other packages continue to use stable versions
• You can mix and match: test one component's dev version while keeping others stable

When to use:

• When testing a specific feature or bug fix in a single component
• When contributing to a specific component
• When you need more control over which packages use dev versions

Composer Update Commands​

After changing version constraints:

# Update all packages
composer update

# Update only specific packages
composer update byjg/anydataset

# Update all byjg packages
composer update byjg/*

Migration Strategy Between Versions​

When it's time to upgrade to a new PHP version (and consequently a new component version), follow this approach:

Step 1: Check Your Current PHP Version​

php -v

Step 2: Update Your composer.json​

Change all ByJG component versions to match your target PHP version:

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

Step 3: Run Composer Update​

composer update

Step 4: Test Your Application​

Run your test suite to catch any breaking changes:

./vendor/bin/phpunit

Step 5: Review Changelogs​

Check the changelogs of each component for breaking changes:

https://opensource.byjg.com/docs/php/[component-name]/

Version Support Lifecycle​

Understanding the support lifecycle helps you plan upgrades:

Active Development: New features, improvements, and optimizations Security Patches: Critical bug fixes and security updates only

Real-World Example​

Let's say you're building a new REST API application:

Your PHP Version​

$ php -v
PHP 8.4.1

Your composer.json​

{
    "name": "mycompany/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"
    }
}

Install Dependencies​

composer install

Result: Composer installs the latest 6.0.x versions of all components, ensuring:

• ✅ Full compatibility with PHP 8.4
• ✅ All components work together seamlessly
• ✅ Automatic updates for patches and minor versions
• ✅ Stable, tested ecosystem

Conclusion​

The standardized versioning system for ByJG PHP components transforms dependency management from a complex puzzle into a straightforward process.

Key Takeaways:

1. Component version = PHP version compatibility — Version 6.0 = PHP 8.3/8.4/8.5
2. Always use the same major version across all ByJG components
3. Use the caret operator (^6.0) for optimal stability and updates
4. Main branch = latest version, version branches for patches
5. Two ways to test dev versions: project-wide stability settings or per-package pinning

By following these guidelines, you'll have a maintainable, predictable dependency setup that scales with your application.

Want to explore the entire ecosystem? 👉 Visit https://opensource.byjg.com

Need to check which components are available? 👉 Browse the component catalog

Whether you're working with Laravel, Symfony, or building from scratch, these components can help you accelerate development while maintaining production-grade quality. Think of it as a curated pit crew: each utility is lightweight on its own, yet designed to snap together when you need the whole pipeline.

What We'll Cover​

• Standing up a workstation on a blank Linux machine (or WSL) in minutes
• Understanding the PHP component catalog and when to reach for each piece
• Using the PHP REST Reference Architecture to bootstrap an API
• Selecting hardened Docker images for production workloads
• Operating a realistic workflow from day zero to ongoing maintenance

The Journey: From Blank Machine to Production​

Let's start from the very beginning - a machine with nothing installed - and work our way up to a complete, production-ready API application.

Step 1: Setting Up Your Development Environment​

When you have a blank Linux machine (or WSL on Windows), the first challenge is getting Docker and PHP installed without spending an afternoon copying snippets from blog posts. This is where shellscript.download comes in. It's a single loader script that ships opinionated installers so your team can standardize the whole stack with one-liners.

First, install the loader script (idempotent and safe to rerun):

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

With load.sh in place you can install tools in separate steps. Each command checks pre-requisites, pins known-good versions, and configures services the same way on every server.

Installing Docker:

load.sh docker

Installing PHP 8.4 via Docker:

load.sh php-docker -- 8.4

Installing Node.js 22 (for modern development tools like Claude Code, Codex, etc.):

load.sh node-docker -- 22

That's it! In just three commands, you now have:

• Docker installed and running
• PHP 8.4 ready to use via Docker containers
• Node.js 22 for modern development tools

The beauty of this approach is that everything runs in containers—no version conflicts, no dependency hell, just clean, reproducible environments. If someone on your team needs to rebuild their workstation or if you move between laptops, you're a few commands away from parity.

The PHP Components Ecosystem​

Once your environment is ready, you gain access to an extensive collection of production-tested PHP components that can be used with ANY PHP framework—Laravel, Symfony, Slim, or your own custom solution. These packages grew out of real client projects, so each one solves a specific operational problem: configuration, caching, persistence, messaging, and more.

Below is a guided tour grouped by layer. Use it as a menu; you can grab only what you need, or assemble the full stack when greenfielding a service.

Core Infrastructure Components​

Start with the building blocks that keep configuration, caching, and migrations predictable across environments.

Cache Engine - PSR-6 and PSR-16 compliant caching with multiple backends:

• File system, Redis, Memcached, Session
• Shared memory (ShmOp), TmpFS
• Built-in garbage collection and atomic operations

Config Management - Environment-based configuration with dependency injection support

Migration - Database version control with up/down migrations supporting MySQL, PostgreSQL, SQLite, Oracle, and SQL Server

Data Access & ORM​

Next, wire up data persistence. The AnyDataset layer gives you unified access to multiple databases, and Micro-ORM adds just enough structure without trapping you in a heavy framework.

Micro-ORM - Lightweight Object-Relational Mapping with:

• Query builder
• Active Record pattern support
• Repository pattern support
• Relationship mapping without heavy overhead

AnyDataset-DB - Universal database abstraction layer supporting multiple databases with a consistent API

REST API & Web Services​

With data covered, expose it through APIs that follow the contracts you publish.

RestServer - Create RESTful services with:

• Auto-generation from OpenAPI/Swagger definitions
• Multiple output handlers (JSON, XML, HTML)
• Built-in middleware support (CORS, JWT, Static Server)
• Route caching for performance

Swagger Test - Contract testing to ensure your API matches your OpenAPI specification

Security & Authentication​

Authentication is baked in rather than bolted on, so you can build features without reinventing session storage or JWT flows.

AuthUser - Complete user authentication and authorization system with:

• Session management
• Custom properties
• Multiple storage backends (Database, XML)

JWT Wrapper - JSON Web Token handling for stateless authentication

JWT Session - JWT-based session management

Crypto - Passwordless symmetric encryption with dynamic key generation

Communication​

Modern apps rarely operate in isolation. These clients keep outbound communication (mail, queues, SMS) consistent.

MailWrapper - Send emails through multiple providers:

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

Message Queue Client - Unified interface for message queuing:

• RabbitMQ support via rabbitmq-client
• Redis Queue support via redis-queue-client
• Easy to implement custom connectors

SMS Client - Send SMS through various providers

Utilities​

Finally, a set of focused helpers for everyday tasks—ID generation, image manipulation, conversion, and URI handling.

ShortId - Generate short, unique, URL-safe IDs

ImageUtil - Image manipulation and processing

Convert - Data conversion utilities

URI - URI manipulation and parsing

And many more components covering various needs...

Key Advantages​

• Framework Agnostic: Use any component independently in your existing projects
• PSR Compliant: Follows PHP-FIG standards (PSR-6, PSR-7, PSR-11, PSR-16)
• Well Documented: Every component has comprehensive documentation with examples
• Production Tested: Used in real-world production environments
• Composer Ready: Simple installation via composer require byjg/component-name

Building a Complete Application from Scratch​

While you can use individual components with any framework, what if you want to create a complete API application from scratch and keep velocity high? This is where the PHP REST Reference Architecture comes in. It's intentionally not another framework—it is a set of opinions captured as code so you can fork it, tailor it, and still recognize every moving part.

What is the PHP REST Reference Architecture?​

The PHP REST Reference Architecture is a production-ready template (not a framework) that brings together the best components from the ByJG ecosystem into a cohesive, ready-to-use application structure.

What's Included​

The template is broken into layers so you can keep tightening or loosening abstractions depending on the stage of your product.

Code Generation & Architecture:

• Automatic CRUD generation from database tables
• Choice between Repository Pattern (clean separation) or ActiveRecord Pattern (rapid prototyping)
• Auto-generated models, repositories, services, controllers, and tests

Security Built-In:

• JWT-based authentication system
• Role-Based Access Control (RBAC)
• Ready-to-use login endpoints

API Documentation:

• Auto-generated OpenAPI documentation synchronized with code
• Interactive Swagger UI for API exploration
• Contract testing to keep docs in sync

Database Management:

• Built-in migration system
• MicroORM for lightweight data access
• Query builder and relationship mapping

Development Experience:

• Docker containerization (MySQL, PHP-FPM, Nginx)
• Scriptify: interactive PHP terminal and CLI runner
• Comprehensive functional test suite
• Hot reload during development

Production Ready:

• Pre-configured CI/CD workflows (GitHub Actions, GitLab CI, Bitbucket Pipelines)
• Environment-based configuration
• Structured logging
• Error handling and reporting
• PSR-7, PSR-11, PSR-6/16 standards compliance

Getting Started with Reference Architecture​

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

This single command creates a complete API application with:

• Project structure following clean architecture
• Database migrations ready
• Authentication system configured
• OpenAPI documentation generated
• Docker environment set up
• CI/CD pipelines ready
• Tests configured

You can start developing immediately with:

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

From here, you're not hunting for stubs or copying controllers from earlier projects. Code generation scaffolds endpoints, migrations keep the database in sync, and the OpenAPI file stays coupled to actual handlers. Because everything is PSR-compliant, you can drop in any additional middleware or reuse familiar packages.

Production Deployment​

Local success is only half the story. Shipping to production means choosing images you can trust and an ingress strategy that won't wake you up during traffic spikes. The ecosystem includes curated Docker images and a self-updating HAProxy layer so operational pieces feel as cohesive as the developer experience.

Hardened PHP Docker Images​

For production deployment, the ecosystem provides curated, security-hardened PHP Docker images supporting:

• PHP Versions: From 5.6 to 8.5 (edge)
• Multi-Architecture: AMD64 and ARM64 (Raspberry Pi, AWS Graviton)
• Image Variants:
  • base - Minimal with 45+ PHP extensions (~135MB)
  • cli - Development tools included (~154MB)
  • fpm - PHP-FPM for custom setups (~139MB)
  • fpm-nginx - Complete LEMP stack (~154MB)
  • fpm-apache - Complete LAMP stack (~154MB)

Security Features:

• Runs as non-root user (app)
• Includes SBOM & build provenance
• Monthly tagged releases for stability
• Regular security updates

Example:

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

Load Balancing & Ingress​

For production traffic management, EasyHAProxy provides dynamic HAProxy configuration through service discovery. Whether you deploy to Docker Swarm, Kubernetes, or a single VM, the same labels configure certificates, routing, and stats, which keeps operations boring (in the best possible way).

Supported Platforms:

• Docker standalone
• Docker Swarm clusters
• Kubernetes
• Manual static configuration

Features:

• Automatic SSL/TLS with Let's Encrypt (ACME protocol)
• Custom SSL certificates
• Load balancing across replicas
• Zero-downtime configuration reloads
• TCP mode support
• Built-in statistics dashboard

Example for Docker Swarm:

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

EasyHAProxy automatically detects the service, configures HAProxy, obtains SSL certificates, and starts routing traffic - no manual configuration needed!

The Complete Ecosystem Flow​

Here's how everything fits together. The diagram highlights how a single loader command cascades into an application template, Docker base images, and eventually automated ingress. Trace the arrows to see how each piece feeds the next stage of the lifecycle:

Real-World Workflow​

Let's walk through a complete real-world scenario. Imagine you're tasked with launching a commerce API before the next quarterly planning session. The timeline below mirrors how most teams actually move—there's a burst of setup, a block of feature work, a sprint on automation, and finally a handoff to operations.

Day 1: Project Setup​

# Set up environment (one time)
/bin/bash -c "$(curl -fsSL https://shellscript.download/install/loader)"
load.sh docker
load.sh php-docker -- 8.4

# Create new project
load.sh php-rest-api -- my-shop-api \
  --namespace=MyShop \
  --name=mycompany/shop-api

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

Day 2-10: Development​

# Generate complete CRUD for products table
composer codegen -- --env=dev --table=products all --save

# Add email notifications using MailWrapper
composer require byjg/mailwrapper

# Add queue processing for async tasks
composer require byjg/redis-queue-client

# Run tests
composer test

During this phase you're iterating quickly: add capabilities via Composer, lean on generated CRUD to avoid repetitive work, and keep confidence high with the baked-in test suite.

Week 2: CI/CD Setup​

• Push to GitHub
• CI/CD workflows already configured (GitHub Actions)
• Automatic testing on every PR
• Docker image build on merge to main

There is no scramble to stitch together workflows—the template checked in .github/workflows (and equivalents for GitLab/Bitbucket), so enabling CI is a matter of connecting secrets and letting the pipeline run.

Month 1: Production Deployment​

# Pull production-ready image
docker pull byjg/php:8.4-fpm-nginx-2025.11

# Build your application image using it as base
docker build -t mycompany/shop-api:1.0.0 .

# Deploy to Docker Swarm with 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

By the time you deploy, you already know which Docker image tag you're targeting, and EasyHAProxy keeps ingress configuration consistent. Scaling to more replicas or pointing a staging hostname at the same service is a label change, not a manual HAProxy edit.

Your API is now:

• Running with 3 replicas for high availability
• Load balanced automatically
• Secured with Let's Encrypt SSL
• Monitored via HAProxy stats
• Ready to scale

Why This Ecosystem?​

After following the workflow it's worth stepping back. Why invest in this collection instead of mixing random packages from Packagist? These are the anchors that keep the experience cohesive:

1. Consistency Across Environments​

The same Docker images run in development, CI/CD, and production - eliminating "works on my machine" issues.

2. Rapid Development​

Go from idea to working API in minutes, not days. Code generation handles boilerplate while you focus on business logic.

3. Production-Grade Quality​

Built-in authentication, authorization, logging, error handling, and testing mean you start with best practices, not technical debt.

4. Framework Freedom​

Use components individually in existing projects or adopt the full reference architecture for new projects.

5. Modern DevOps Practices​

CI/CD ready, containerized, with infrastructure as code. Deploy to any container orchestration platform.

6. No Vendor Lock-In​

It's a template, not a framework. You own the code. Modify anything you need.

7. Comprehensive Documentation​

Every component is documented with examples at opensource.byjg.com

Ecosystem Components Summary​

If you only remember five links, make them these:

Getting Started​

Ready to build your next PHP application with this ecosystem? Here's how to start, depending on where your project currently sits:

1. For Existing Projects: Browse the component library and add individual components via Composer

2. For New APIs: Use the PHP REST Reference Architecture template

3. For Environment Setup: Visit shellscript.download for installation scripts

4. For Production: Check out PHP Docker Images and EasyHAProxy

Conclusion​

The ByJG PHP ecosystem provides a complete, cohesive solution for modern PHP development - from your first command on a blank machine to a production-ready, scalable API application.

By combining:

• Simple environment setup
• Modular, reusable components
• Production-ready templates
• Hardened Docker images
• Automated load balancing

You can focus on building features instead of infrastructure, while maintaining professional-grade quality throughout the entire development lifecycle.

Whether you're building a small microservice or a complex application, this ecosystem has the tools you need to succeed.

Explore the ecosystem:

• Documentation: https://opensource.byjg.com
• GitHub: https://github.com/byjg
• Setup Scripts: https://shellscript.download

Happy coding!

Maintaining more than 30 open source projects is a bit like conducting an orchestra alone.
Each project has its own particularities, dependencies, pipelines, documentation, and tests — and yet all of them need to work in harmony.

In a company with 30 microservices, it’s common to have something like 2 to 4 DevOps, 3 to 5 Product Owners, and 50 to 100 developers.
I do this mostly by myself.

It sounds impossible, but it isn’t.
Let’s walk through how this ecosystem works — and how automation, standardization, and good use of Artificial Intelligence make it not only viable, but actually enjoyable.

What I Maintain​

My open source work is centered around two big pillars:

• An ecosystem of PHP components — from micro-ORMs and serializers to complete REST integrations.
• A set of Docker images — used both in development and production, ensuring consistency and reproducibility across environments.

These projects interconnect, forming a modular and reusable architecture.
Any component can be used independently in other frameworks, but they also fit together nicely inside my main ecosystem.

Creating a Developer Experience Environment​

The first thing I had to fix was what slowed me down the most: the development setup.
Every time I changed machines, I had to configure dozens of dependencies — PHP, extensions, Composer, test tools, etc.
Something was always missing.

The solution was to create standardized Docker images.
Today I maintain PHP images for several purposes:

• CLI
• FPM
• FPM with Nginx
• Docker Compose examples

These images are used in development, CI/CD, and production, which eliminates environment drift and the classic “works on my machine”.

But the bigger challenge was running multiple PHP versions on the same machine.
Since I was already using Docker, I decided the development environment should also run in containers.

I standardized everything on Linux and kept experimenting with tools while I was coding, until I created another open source project: https://shellscript.download.

With it, my environment can be set up with a single command:

load.sh php-docker -- 8.4

After that, I have everything ready — PHP, Composer, extensions, tools — in a few minutes.

Automation and Process Standardization​

Having 30 projects is like having 30 microservices:
each one with its own documentation, architecture, dependencies, and lifecycle.

The key is automation.

Since 2013, I’ve been continuously improving each project, always keeping:

• Automated tests
• Meaningful code coverage
• Continuous Integration hooked into everything

But there was another pain point: documentation.
Keeping docs scattered across repositories is a nightmare.
I needed to centralize documentation without maintaining it in two places.

The Solution​

I created a pipeline that, whenever a PR is merged, automatically copies that project’s documentation into a central repository: byjg.github.io.

That repository organizes the content inside a Docusaurus structure and triggers an automatic build on Cloudflare Pages, publishing everything at https://opensource.byjg.com.

So, every documented commit can automatically update the main site — with no manual maintenance and zero additional hosting cost.

In the end, I focused on three principles:

1. Automate what is repetitive
2. Centralize what is shared
3. Isolate what is independent

Building a Sustainable Ecosystem​

My PHP components strictly follow PSR standards, use Composer for package management, and can be integrated into any framework.
Each project includes examples, tests, and usage instructions.

Over time, I realized that the collection of components formed a solid foundation for something bigger.
That’s when the PHP Rest Reference Architecture was born — a project that combines the main components of the ecosystem into a ready-to-use structure:

• Preconfigured CI/CD
• Full OpenAPI support for REST endpoints
• Built-in authentication and authorization
• Database migration
• Dependency injection
• Docker and build scripts

With a single command, I can create a fully functional PHP REST project in minutes:

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

This automation allows anyone to create a complete API based on clean architecture and good practices — without reinventing the wheel.

Getting Ready for Production​

The Docker images I use in development are the same ones used in CI/CD and in production.
They are pushed to a Container Registry, which lets me promote versions across environments (dev → staging → production) with full traceability.

For load balancing, I created the Easy HAProxy project — a simplified and powerful HAProxy setup that self-configures based on Docker service labels.

It supports SSL, avoids downtime, and removes the need to manually edit configuration files.
You just run the container and let it handle everything.

Artificial Intelligence: My New “Intern”​

Artificial Intelligence has become my ally in several areas — and honestly, it’s a game changer.

Documentation​

I created custom prompts that cover about 95% of my documentation needs:
from writing consistent guides to avoiding formatting issues that might break Docusaurus.

Design and Frontend​

My strength has always been backend work.
Before, building UI screens felt slow and painful.

Now, I describe what I want, and the AI generates the basic layout or page for me — and I plug it into my backend.
This lets me focus more on logic and integration instead of CSS details.

Assisted Development​

I use Claude Code as my main coding assistant, ChatGPT as a second opinion or idea generator, and Junie (PHPStorm) for in-IDE help.

I never let AI run completely unattended: I treat it like a very smart junior developer.
I review what it does, guide it, and change direction when needed.

Often, I start by asking for a plan before touching any code.
Then I authorize each step, adjust, and refine.

This approach has significantly multiplied my productivity — without sacrificing quality.

What’s Behind All This​

Infrastructure​

• Optimized Docker images
• Load balancing with Easy HAProxy
• Builder image for CI/CD

Automation​

• Standardized CI/CD pipelines
• Reused workflows shared across projects
• Ansible and Terraform to configure environments
• Python scripts to configure GitHub repositories and settings

Conclusion​

Maintaining dozens of open source projects is not a matter of time, it’s a matter of system.
When each part of the process is automated, documented, and integrated, the work scales naturally.

The secret is to build a cohesive ecosystem where each component supports the others — and where the developer becomes not just the author of the code, but the orchestrator of a self-sustaining environment.

At the end of the day, I focus on one project at a time, do the best I can on it, and let automation and standardization handle the rest.

And that’s how I manage to keep 30+ projects alive, documented, and constantly evolving — almost on my own.

Want to see all of this in action?
👉 Check out https://opensource.byjg.com

What You'll Get​

By the end of this tutorial, you'll have:

• PHP running entirely in Docker containers
• Full debugging support with Xdebug in VSCode
• Ability to run individual PHP scripts
• Built-in PHP development server
• Zero PHP installation on your host machine

Prerequisites​

• Docker installed and running
• Visual Studio Code installed
• Basic familiarity with command line

Step 1: Install PHP via Docker Wrapper​

We'll use shellscript.download, a collection of curated ready-to-use scripts that make installation a breeze.

First, install the Loader:

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

And then run this single command to install PHP 8.4 via Docker:

load.sh php-docker -- 8.4

This creates a wrapper script at ~/.shellscript/bin/php8.4 that runs PHP inside a Docker container. The beauty of this approach is that PHP runs in complete isolation. Your host system stays clean!

The script also adds ~/.shellscript/bin to your PATH, so you can:

• Call php8.4 directly from anywhere in your terminal
• Use php as an alias (automatically points to your default PHP version)

Try it out:

php8.4 --version
php --version  # Uses the alias

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

Step 2: Install VSCode Extensions​

You need two extensions for PHP development with debugging:

1. PHP Debug by Xdebug

   • Extension ID: xdebug.php-debug
   • Provides Xdebug integration for debugging PHP code

2. PHP Intelephense (recommended) or PHP IntelliSense

   • Extension ID: bmewburn.vscode-intelephense-client
   • Provides code intelligence, autocompletion, and more

Install them via VSCode:

1. Press Ctrl+Shift+X (or Cmd+Shift+X on Mac) to open Extensions
2. Search for "PHP Debug" and install
3. Search for "PHP Intelephense" and install

Step 3: Configure VSCode Settings​

Open your VSCode settings (.vscode/settings.json in your project or global settings) and add:

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

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

Step 4: Configure Launch Configurations​

Create or update .vscode/launch.json in your project root:

{
    "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}"
            }
        }
    ]
}

Step 5: Test Your Setup​

Create a simple test file test.php:

<?php

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

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

echo "=== Testing PHP Setup ===\n\n";

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

$result = calculate(10, 5);
echo "Calculations for 10 and 5:\n";
echo "Sum: {$result['sum']}\n";
echo "Product: {$result['product']}\n";
echo "Average: {$result['average']}\n\n";

echo "PHP Version: " . phpversion() . "\n";
echo "Xdebug loaded: " . (extension_loaded('xdebug') ? 'Yes' : 'No') . "\n";

Using Your New Setup​

Running a Script Without Debugging​

1. Open test.php
2. Press F5 or click the Run button
3. Select "PHP Run Open Script"
4. See the output in the Debug Console

Debugging a Script​

1. Set a breakpoint by clicking to the left of a line number (try line with $greeting = ...)
2. Press F5
3. Select "PHP Debug Current Script"
4. Execution will pause at your breakpoint
5. Inspect variables, step through code, etc.

Running the Built-in Server​

1. Create an index.php file in your project root
2. Press F5
3. Select "PHP Built-in Server" or "PHP Built-in Server (no debug)"
4. Your browser will automatically open to http://localhost:8080
5. Set breakpoints in your PHP files and refresh the page to debug

How It Works​

The magic happens in the wrapper script created by shellscript.download. It:

1. Converts absolute file paths to relative paths
2. Mounts your project directory as /workdir in the Docker container
3. Runs PHP inside the container with Xdebug configured
4. Uses --network host so Xdebug can connect back to VSCode

All of this happens transparently. You just write PHP code and debug as if PHP were installed locally!

Benefits of This Approach​

✅ Clean System: No PHP installation cluttering your system
✅ Multiple Versions: Run different PHP versions for different projects
✅ Consistent Environment: Same PHP environment across different machines
✅ Full Debugging: Complete Xdebug support with breakpoints, variable inspection, etc.
✅ Easy Updates: Update PHP by just changing the wrapper script
✅ Isolated Dependencies: Each container is isolated with its own extensions

Troubleshooting​

"Could not connect to debugging client"​

Make sure VSCode is listening for Xdebug. You should see "Listening to Xdebug on port 0.0.0.0:9003" in the Debug Console when you start debugging.

"Address already in use" when starting server​

The server is still running from a previous launch. Stop it by clicking the trash icon in the terminal where it's running, or press Ctrl+C.

Path issues​

Ensure your pathMappings correctly maps /workdir to your workspace folder. This tells Xdebug how to translate container paths to your local paths.

Conclusion​

With this setup, you have a professional PHP development environment that's:

• Easy to set up (just a few minutes!)
• Easy to maintain
• Portable across machines
• Completely isolated from your host system

No more dependency conflicts, no more "works on my machine" problems, and no more complex PHP installations. Just pure, containerized PHP development bliss!

Happy coding! 🚀

Eliminate All Stupid Yields - EASY​

This is a mantra I carry with me. Code and live should be EASY. It it's hard, It is wrong. If you’ve been banging your head against a problem for hours, the issue is usually not your persistence. it’s your approach. Excessive complexity is not a sign of brilliance; it’s just wasted energy. Whenever I find myself in this cycle, I stop. Literally. I close the IDE, take a break, and come back the next day with a clear head. Often, that means running git checkout -- . and starting fresh with a blank page. And I’m not ashamed to say it: some of my best solutions were born exactly this way.

KISS – Keep It Stupidly Simple​

There’s a beauty in simple solutions that only those who’ve wrestled with complexity can truly appreciate. The Linux pipe is a masterpiece: the output of one command becomes the input of another. Elegant, minimal, brilliant. Or think of a hash function solving massive problems in O(1). Don’t fool yourself: more lines of code don’t mean more robustness. Many times, it just means you refused to simplify.

DRY – Don’t Repeat Yourself​

There’s no middle ground here. Duplicated code is a debt that charges high interest. If you copy and paste, you’re planting a ticking time bomb for future maintenance. And it’s not just a technical issue—it’s a mindset issue. You’re basically telling yourself that you’d rather take the shortcut than face the architecture properly. But the bill always comes due, and most of the time, you’re the one who pays it.

To Smile, You Have to Make It Smile​

This line from Tropa de Elite movie (Squad Elite) might sound odd here, but it fits perfectly. Want your database to return results quickly? Then help it smile back at you. Learn how indexes work, how data is stored, how queries are optimized. The point is simple: if you don’t understand the tool you’re using, don’t expect it to magically solve your problems. It’s like putting someone who’s never flown before in the cockpit of an airplane—it won’t end well.

Tests, Tests, Tests​

If there’s one thing that separates average developers from reliable ones, it’s the habit of testing. And no, I don’t mean “deploying to staging” or, worse, “pushing to production and seeing what happens.” I mean building tests that actually ensure the health of your code. Good tests let you sleep at night. They give you the freedom to refactor without fear. I’ve made massive changes in legacy code with total confidence because I knew the test suite had my back. And trust me: there’s no greater freedom for a developer than that.

The Problem Is a Coward​

A problem is a coward because it never shows up alone. It always brings friends. That bug in the application might be tied to a slow query, which is linked to a missing index, which actually started because the log server was lagging behind in processing events. When this happens, it’s not enough to look only at your piece of the code. You need to have a solid grasp of the whole system: from code to infrastructure, from logs to monitoring dashboards. And even more importantly, you need a team ready to act together — each one seeing their part, but with a shared vision of where the root cause really lies. Solving problems is not about being the lone hero. It’s about recognizing that the problem is a coward. And because of that, you should be ready to fight it as a team.

Wrapping It Up​

In the end, none of this is revolutionary. These are simple, almost trivial principles. But ignore them, and it’s only a matter of time before you fall into the trap of unnecessary complexity. Building complex systems isn’t about proving that you can complicate things. It’s about having the discipline to simplify, the clarity to see what really matters, and the courage to start over when you realize you’ve gone down the wrong path.

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