How to Package and Deploy PHP Applications Using PHAR Archives

Introduction

PHAR (PHP Archive) is a packaging format similar to Java's JAR that bundles an entire PHP application—including source files, configuration, and dependencies—into a single executable archive, simplifying deployment.

Configuration

By default PHAR files are read‑only. To enable writing, edit php.ini and set phar.readonly = 0.

First PHAR File – Project Layout

Create a directory structure like the following:

Place source files in src and reserve build for the generated PHAR. Typical files are: index.php – application entry point common.php – shared library code config.ini – configuration settings

index.php example:

<?php
require_once "phar://myapp.phar/common.php";
$config = parse_ini_file("config.ini");
AppManager::run($config);

common.php example:

<?php
class AppManager {
    public static function run($config) {
        echo "Application is now running with the following configuration... ";
        var_dump($config);
    }
}

config.ini example:

[database]
host=localhost
db=dbname
user=myuser
pass=dbpass

Creating the PHAR File

Place a build script create-phar.php in the project root:

<?php
$srcRoot = "~/myapp/src";
$buildRoot = "~/myapp/build";
$phar = new Phar($buildRoot . "/myapp.phar", FilesystemIterator::CURRENT_AS_FILEINFO | FilesystemIterator::KEY_AS_FILENAME, "myapp.phar");
$phar["index.php"] = file_get_contents($srcRoot . "/index.php");
$phar["common.php"] = file_get_contents($srcRoot . "/common.php");
$phar->setStub($phar->createDefaultStub("index.php"));
copy($srcRoot . "/config.ini", $buildRoot . "/config.ini");

Run the script from the project directory: php create-phar.php The command generates myapp.phar and a copy of config.ini inside the build folder. Deploy both files to the web server’s document root (e.g., htdocs).

Running the PHAR

If the server cannot be configured to route PHAR files to the PHP interpreter, create a simple wrapper run.php:

<?php
require "myapp.phar";

Access run.php via a browser to execute the packaged application.

How PHAR Works

The new Phar() constructor takes three arguments: the archive path, iterator flags (inherited from RecursiveDirectoryIterator), and an internal alias used for includes.

After creation, files are added to the archive via array syntax or helper methods such as buildFromDirectory(), which can recursively add a directory with optional regex filtering.

$phar->buildFromDirectory("/path/to/dir", '/\.php$/');

The setStub() method defines the stub that runs when the PHAR is executed. The default stub generated by createDefaultStub() looks like:

<?php
Phar::mapPhar();
include "phar://myapp.phar/index.php";
__HALT_COMPILER();

Custom stubs can be supplied by reading a separate stub.php file and passing its contents to setStub().

Limitations

PHAR provides a single entry point; you cannot define multiple independent executables within one archive.

In production environments PHAR archives are read‑only; any files that need to be modified at runtime must reside outside the archive for security reasons.

Conclusion

PHAR archives offer a convenient way to bundle and deploy PHP applications with minimal overhead. This article covered the core concepts, step‑by‑step creation of a PHAR, how to run it, the role of the stub file, and important usage constraints.