Fix PHP Fatal error: creating archive is disabled by the php.ini setting phar.readonly

The ProblemYou are trying to bundle your PHP application into a single executable .phar file. You run your build script, expecting a finished package, but the process crashes immediately. Instead of a file, you get a 10-line stack trace ending in a Phar->__construct exception.

Fatal error: Uncaught UnexpectedValueException: creating archive "project.phar" is disabled by the php.ini setting phar.readonly in /path/to/build-script.php:10

This error hits hardest during local development or inside CI/CD pipelines when automating the distribution of CLI tools. It is a common roadblock when using tools like Box or custom Phar-creation scripts.

Why PHP Blocks Phar CreationThe phar.readonly setting is a built-in safety switch. PHP sets this to 1 (On) by default to prevent scripts from accidentally or maliciously creating Phar files. This protection helps block "Phar Deserialization" attacks, where hackers try to execute malicious code hidden inside a Phar archive.

The catch is that you cannot use ini_set('phar.readonly', 0); inside your script to turn it off. Because this is a high-security setting, PHP ignores any attempts to change it once the script has already started running. You must disable it before the engine fully initializes.

Solution 1: Use a Command Line Override (Best Practice)If you only build archives occasionally, don't change your global system settings. The safest way is to disable the restriction only for the specific command you are running. This keeps your system secure while letting your build script do its job.

Use the -d flag to change the configuration on the fly:

php -d phar.readonly=0 build.phar.php

Here is what those parts do:

• -d: Tells PHP to define a custom configuration for this one execution.- phar.readonly=0: Switches the read-only mode to "Off".- build.phar.php: The name of your specific packaging script.## Solution 2: Update php.ini (Permanent Fix)On a dedicated build server or a local machine where you build Phars daily, a permanent change saves time. You need to find the right configuration file first.

Step 1: Locate your CLI configRun this command to see which file your terminal is actually using:

php --ini

Look for the Loaded Configuration File path. On Ubuntu, it usually looks like /etc/php/8.2/cli/php.ini.

Step 2: Edit the fileOpen that file using sudo and your favorite editor, like Nano or Vim:

sudo nano /etc/php/8.2/cli/php.ini

Step 3: Change the valueFind the [Phar] section. Change the line to look like this:

phar.readonly = Off

Save and exit. You don't need to restart Apache or Nginx because this change only affects the PHP CLI.

Solution 3: Docker and CI/CD WorkaroundsWhen building Phars inside a Docker container or a GitHub Action, you cannot manually edit files. You need a scripted approach.

Using a DockerfileAdd this line to your Dockerfile to inject the setting during the image build phase:

RUN echo "phar.readonly=0" >> /usr/local/etc/php/conf.d/docker-php-ext-phar.ini

Using GitHub ActionsIf you use the popular shivammathur/setup-php action, you can pass the setting directly in your workflow YAML file:

- name: Setup PHP
  uses: shivammathur/setup-php@v2
  with:
    php-version: '8.2'
    ini-values: phar.readonly=0

Testing the FixConfirm the setting is active by running this quick one-liner in your terminal:

php -r "echo 'Readonly is: ' . ini_get('phar.readonly');"

If it returns Readonly is: 0, you are ready to go. You can also run this minimal test script to ensure the Phar object initializes without crashing:

<?php
try {
    $p = new Phar('test.phar');
    echo "Success: Phar archive initialized.";
} catch (Exception $e) {
    echo "Error: " . $e->getMessage();
}

Common Troubleshooting Tips- CLI vs Web: PHP uses different php.ini files for the terminal and the web server. Since you usually build Phars in the terminal, make sure you are editing the cli config, not the fpm or apache2 versions.- File Permissions: Even if phar.readonly is off, the script will fail if it cannot write to the folder. Ensure your user has write access to the destination directory.- Sudo Environments: Running sudo php build.php might use a different environment than your standard user. If you use sudo, verify the setting by running sudo php -i | grep phar.readonly.