PHPackages                             mevdschee/phpfilemerger - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Utility & Helpers](/categories/utility)
4. /
5. mevdschee/phpfilemerger

ActiveProject[Utility & Helpers](/categories/utility)

mevdschee/phpfilemerger
=======================

Intelligently merge PHP files and dependencies into a single file

v1.3.1(1mo ago)91MITPHPPHP ^8.1

Since Mar 13Pushed 1mo agoCompare

[ Source](https://github.com/mevdschee/phpfilemerger)[ Packagist](https://packagist.org/packages/mevdschee/phpfilemerger)[ RSS](/packages/mevdschee-phpfilemerger/feed)WikiDiscussions main Synced 1w ago

READMEChangelog (6)Dependencies (14)Versions (7)Used By (0)

phpfilemerger
=============

[](#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](https://github.com/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](https://www.tqdev.com/2026-merge-php-projects-single-file/)

Use Case
--------

[](#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
------------

[](#requirements)

- PHP 8.1 or higher
- Composer (for building from source)

Installation
------------

[](#installation)

### Download the single-file build (recommended)

[](#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

[](#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

[](#run-without-building)

```
composer install
php src/index.php merge src/index.php
```

Usage
-----

[](#usage)

```
php phpfilemerger.php merge  [options]

```

`merge` is the default command and can be omitted:

```
php phpfilemerger.php  [options]

```

### Arguments

[](#arguments)

ArgumentRequiredDescription`entry`YesPath to the PHP entry point file### Options

[](#options)

OptionShortDefaultDescription`--output``-o``.merged.php`Output file path`--project-root`Auto-detectedProject root (directory containing `composer.json`)`--vendor-dir``/vendor`Vendor directory path`--exclude-entry``false`Exclude the entry point's procedural code from output (output is named `.include.php` by default)`--indent``4`Number of spaces used for indentation in the outputThe project root is auto-detected by walking up the directory tree from the entry point looking for a `composer.json` file.

Examples
--------

[](#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
------------

[](#how-it-works)

1. **Parse**: The entry point is parsed using `nikic/php-parser`. All class references (`extends`, `implements`, trait `use`, `new`, type hints, attributes, etc.) are extracted.
2. **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/`.
3. **Build dependency graph**: The tool recursively processes dependencies, building a graph of all required files.
4. **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.
5. **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
6. **Validate**: `php -l` is run on the output file to verify syntax.

### What the output looks like

[](#what-the-output-looks-like)

```
#!/usr/bin/env php