Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.n3wmedia.com/llms.txt

Use this file to discover all available pages before exploring further.

​
Version Management

FrankPHP now includes a lightweight version management workflow designed for the way the framework is actually shipped: as a simple Zip download rather than through GitHub, Composer packages, or a deployment pipeline. This feature gives you a basic form of release management inside the framework itself. It stays true to the FrankPHP approach: no dependencies, no complex pipelines, no external release tooling. Just plain PHP scripts, a few predictable files, and a repeatable workflow you can follow every time you prepare a release.

​
What it does

The version management feature gives you four practical things:
  1. A single source of truth for the current version
  2. A structured release manifest that records what changed
  3. A snapshot-based diff system so future releases can be compared properly
  4. A clean packaging workflow for building a release Zip without leaking local-only files
In practice, that means you can move from “I think I changed a few files” to “I know what changed, what version this is, and what should go into the Gumroad Zip.”
This is not intended to be enterprise release engineering. It is a simple, durable release workflow for a lightweight PHP framework.

​
The files this feature adds

​
VERSION

A plain text file containing the current version number only. Example: 
1.1.0
This is the single source of truth for the framework version. Both the release manifest generator and the release build process read from this file.

​
CHANGELOG.md

A human-readable summary of what was added, changed, and fixed in each release. This is the file you update for yourself, your customers, and your future documentation. It explains the release in normal language.

​
RELEASE_MANIFEST.json

A structured, AI-friendly release record. This file is generated as a draft and then reviewed by hand. It is especially useful when you come back later and want to understand what changed in a release without scanning the whole codebase. It typically includes:
  • version
  • release_date
  • summary
  • changes.added
  • changes.changed
  • changes.removed
  • route_changes
  • database_changes
  • breaking_changes
  • ai_notes

​
tools/generate_release_manifest.php

This script creates a draft RELEASE_MANIFEST.json and stores a snapshot of the current release so the next release has something concrete to compare against. It works by:
  • reading the current version from VERSION
  • scanning the project files
  • comparing them with the previous release snapshot
  • extracting route changes from bootstrap.php
  • extracting basic schema signals from sql/schema.sql
  • writing a new draft RELEASE_MANIFEST.json
  • storing release snapshot data under releases/{version}/

​
releases/{version}/

This folder stores the internal snapshot for each release. It exists so FrankPHP can compare the current state of the framework against the last known release. That is what makes the generated manifest more useful over time. This folder is for your internal release process. It should normally not be included in the customer Zip.

​
tools/build_release.php

This script builds a clean distributable release folder and Zip. It creates a dist/ build using exclusion rules so local-only files such as .env, internal release snapshots, editor files, and tooling directories do not accidentally end up in the customer package.

​
Why this fits FrankPHP

FrankPHP is deliberately explicit. It avoids abstraction layers, hidden magic, and dependency-heavy workflows. This release system follows the same principle.
  • No Composer packages
  • No Node tooling
  • No CI/CD requirement
  • No GitHub dependency
  • No release SaaS
  • No “pipeline” you need to understand before you can ship a Zip
Instead, the release workflow is just:
  • update the version
  • generate the manifest
  • review the outputs
  • build the release Zip
That is enough structure to make releases safer and more repeatable, without turning the framework into something heavier than it needs to be.

​
How to use it

This is the workflow to follow every time you prepare a release.

​
Step 1: Update VERSION

Open the VERSION file and change it to the new release number. Example: 
1.1.0
The VERSION file must be saved as plain text and contain only the version number. Do not save it as rich text.

​
Step 2: Generate the release manifest

Run: 
php tools/generate_release_manifest.php
This will:
  • create or update RELEASE_MANIFEST.json
  • store a snapshot under releases/{version}/
  • compare the current codebase to the previous release snapshot when one exists

​
First run behaviour

On the first run, there is no previous snapshot yet. That is expected. In that case, the script creates the baseline snapshot for the current version. From that point onward, future runs can compare against it.

​
Step 3: Review RELEASE_MANIFEST.json

Do not treat the generated manifest as final. It is a draft. You should always review and usually update:
  • summary
  • breaking_changes
  • ai_notes
You should also quickly sanity-check:
  • changes
  • route_changes
  • database_changes
The machine should record the facts. You should provide the meaning.

​
Step 4: Update CHANGELOG.md

Add the new release entry in plain language. This is the human-readable record of the release.

​
Step 5: Keep CODEBASE.md in sync

If the framework conventions, workflow, or release process changed, update CODEBASE.md so future AI pair-coding sessions have an accurate framework-level reference. This is particularly useful when the change is architectural rather than just functional.

​
Step 6: Build the release Zip

Run: 
php tools/build_release.php
This creates a clean release under dist/ and then builds the Zip. Typical output: 
/dist/frankphp-1.1.0/
/dist/frankphp-1.1.0.zip
The build script excludes local-only and internal files such as:
  • .env
  • releases/
  • tools/
  • editor junk files
  • temporary logs or caches

​
Step 7: Inspect the built Zip

Before uploading to Gumroad, confirm the Zip contains what you expect. At minimum, check that it includes the framework itself plus your release metadata files:
  • VERSION
  • CHANGELOG.md
  • CODEBASE.md
  • RELEASE_MANIFEST.json
If the Zip contains only release-safe files and no local credentials, the build is ready to upload.

​
What to update by hand

The generated manifest reduces the chance of missing something, but there are still some fields that should be reviewed manually.

​
Always update by hand

  • summary
  • breaking_changes
  • ai_notes

​
Usually just review

  • changes
  • route_changes
  • database_changes

​
Usually leave generated

  • version
  • release_date
  • previous_version
  • generator
If you will forget this later, follow this exact order:
  1. Change VERSION
  2. Run php tools/generate_release_manifest.php
  3. Review and edit RELEASE_MANIFEST.json
  4. Update CHANGELOG.md
  5. Update CODEBASE.md if framework conventions changed
  6. Run php tools/build_release.php
  7. Inspect dist/{product}-{version}.zip
  8. Upload the Zip to Gumroad
That is the whole workflow.

​
Final reminder

This feature is meant to make releases more reliable, not more complicated. If you stick to the workflow above, FrankPHP gives you a simple built-in release process with:
  • a real version number
  • a record of what changed
  • basic release history
  • a clean packaging step
All without dependencies, external services, or a complex toolchain.