phpfilemerger
A CLI tool that merges a PHP entry point and all of its class dependencies into
a single self-contained PHP file. It uses a proper AST parser
(nikic/php-parser) rather than naive file
concatenation, producing a correctly ordered, dependency-aware output file.
Blog:
tqdev.com/2026-merge-php-projects-single-file
Use Case
If you maintain a PHP project that you want to distribute as a single file (e.g.
a single-file API or a standalone script), PHP File Merger automates the
process. It statically analyzes your code, resolves all
class dependencies via PSR-4/PSR-0 autoloading, sorts them in dependency order,
and writes a single merged .php file.
Requirements
- PHP 8.1 or higher
- Composer (for building from source)
Installation
Download the single-file build (recommended)
Download the latest phpfilemerger.php from the releases and run it directly:
php phpfilemerger.php merge src/index.php
Build from source
git clone https://github.com/yourname/phpfilemerger
cd phpfilemerger
composer install
./build.sh
This produces phpfilemerger.php in the project root. The build uses
phpfilemerger to merge its own sources, so there is no external build
dependency. build.sh is a thin wrapper around a single self-compilation
command, which you can also run directly:
php src/index.php merge src/index.php --output phpfilemerger.php
Run without building
composer install
php src/index.php merge src/index.php
Usage
php phpfilemerger.php merge <entry> [options]
merge is the default command and can be omitted:
php phpfilemerger.php <entry> [options]
Arguments
| Argument |
Required |
Description |
entry |
Yes |
Path to the PHP entry point file |
Options
| Option |
Short |
Default |
Description |
--output |
-o |
<entry>.merged.php |
Output file path |
--project-root |
|
Auto-detected |
Project root (directory containing composer.json) |
--vendor-dir |
|
<project-root>/vendor |
Vendor directory path |
--exclude-entry |
|
false |
Exclude the entry point's procedural code from output (output is named <entry>.include.php by default) |
--indent |
|
4 |
Number of spaces used for indentation in the output |
The project root is auto-detected by walking up the directory tree from the
entry point looking for a composer.json file.
Examples
Merge src/index.php and all its dependencies into a single file:
php phpfilemerger.php merge src/index.php
# Output: src/index.merged.php
Specify a custom output path:
php phpfilemerger.php merge src/index.php --output dist/app.php
Produce an includeable library file (no entry-point code, only class
definitions):
php phpfilemerger.php merge src/index.php --exclude-entry --output dist/lib.php
How It Works
- Parse: The entry point is parsed using
nikic/php-parser. All class
references (extends, implements, trait use, new, type hints,
attributes, etc.) are extracted.
- Resolve: Each referenced class name is resolved to a file path using
PSR-4/PSR-0 mappings read from
composer.json and the Composer-generated
autoload files in vendor/composer/.
- Build dependency graph: The tool recursively processes dependencies,
building a graph of all required files.
- Sort: Files are sorted in topological order so that hard dependencies
(
extends, implements, trait use) are always placed before the classes
that depend on them.
- Merge: Each file is processed by the AST and its contents are emitted
into the output file, wrapped in an explicit
namespace { ... } block. The
following transformations are applied automatically:
declare(strict_types=1) declarations are stripped (they are illegal inside
the bracketed namespace blocks, so the merged file runs without strict typing)
require vendor/autoload.php statements are removed
- Any
files autoload entries from vendor packages (e.g. global helper
functions) are inlined
- Statically resolvable
require/include calls whose path is built from
__DIR__ (e.g. require __DIR__ . '/bootstrap80.php') are inlined: the
target is emitted once as a closure in its own namespace and the call site
is rewritten to invoke it, preserving conditionals, return values and
require_once semantics
- Files that early-exit with a namespace-scope
return (common in polyfills)
are wrapped in an immediately-invoked closure so the return does not abort
the whole merged file
- Each included file is annotated with a
// file: relative/path.php comment
- Validate:
php -l is run on the output file to verify syntax.
What the output looks like
#!/usr/bin/env php
<?php
// Generated by PHP File Merger
// file: vendor/example/package/src/Helper.php
namespace Example\Package {
function helperFunction() { ... }
}
// file: src/Model/Foo.php
namespace MyApp\Model {
class Foo { ... }
}
// file: src/index.php
namespace {
$app = new \MyApp\Model\Foo();
$app->run();
}
Limitations
- Dynamic class loading:
new $className() and similar dynamic patterns
cannot be statically analyzed and will not be automatically included.
- Multiple namespace blocks per file: files using more than one namespace
block may not be handled correctly. A dynamically-required file that mixes
namespaces is left as-is (its
require is skipped with a warning) rather than
inlined.
include/require statements: calls whose path resolves statically from
__DIR__ are inlined. Anything dynamic (a variable path, a glob, a path that
cannot be resolved at merge time) is skipped with a warning, since relative
paths would break in the merged file.
- Runtime
__DIR__ / __FILE__ resource access: only __DIR__ used inside
a require/include is handled. Code that uses __DIR__/__FILE__ at
runtime to reach non-PHP resource files (templates, data directories,
.json/.dist assets) cannot be bundled into a single file — those resources
are not code. Such paths resolve relative to the merged file and will fail at
runtime. For example, Symfony Console's completion command scans its
Resources/ directory this way, so merging an application that registers it
will fail when that command is constructed.
- Top-level
exit/die: a dependency file that calls exit/die at
namespace scope is skipped with a warning (it would abort the merged file). A
top-level return, by contrast, is now contained by wrapping the file body in
a closure.
Development
# Run tests
vendor/bin/phpunit
# Build the single-file distributable
./build.sh
What about smartinus44/phpfilemerger?
The project smartinus44/phpfilemerger is no longer published, and its exact
behavior is not documented, but this project aims to replace it. The code is not
a fork of smartinus44/phpfilemerger, but deduced from the code written for
PHP‑CRUD‑API, a project that
flattens multiple PHP source files into a single distributable API script.