DOCSEARCHbyAlgolia
Submit Docs

PHPacker

website·Indexed 32 days ago

https://phpacker.dev/docs/installation

A tool to package PHP scripts or PHARs into standalone, cross-platform executables. It provides capabilities for building binaries for multiple platforms and architectures, managing custom PHP builds via the php-bin repository, and configuring builds through phpacker.json or PHP INI files.

Tokens
2.1K
Snippets
12
Records
20
Agent score
61%

What's inside PHPacker

  1. Distribute PHPacker binaries via Composer

    To distribute binaries that automatically select the correct version based on the user's platform and architecture, use the phpacker/composer-installer plugin. This plugin replaces the need for a manual bin section in composer.json by using the phpacker.json configuration file to discover executables and create a platform-specific proxy.

    On Windows, the installer automatically generates a .bat file and a Unix-style proxy file to ensure compatibility with Windows, WSL, and Linux VMs.

    # Install the plugin as a regular dependency (not a dev-dependency)
composer require phpacker/composer-installer

  2. PHP extensions in phpacker binaries

    PHPacker uses pre-compiled, statically-compiled PHP binaries that include a set of essential extensions designed for consistent behavior across Windows, macOS, and Linux. These binaries are built using static-php-cli. For custom extension requirements, users can create their own custom PHP binaries.

  3. Package PHP applications into standalone executables with PHPacker

    PHPacker allows developers to package PHP scripts or PHAR files into single, self-contained, cross-platform executables. This eliminates the need for the end-user to have PHP installed on their system, as the PHP runtime is bundled directly with the application. Key capabilities include:

    • Cross-Platform Builds: Create executables for macOS, Linux, and Windows from one codebase.
    • PHP Version Selection: Support for PHP 8.2, 8.3, 8.4, and 8.5.
    • Custom Binaries: Ability to use custom-built PHP binaries with specific extensions.
    • Configuration: Build and INI configurations can be stored in version-controlled files.
    • Distribution: Integration with a Composer Installer to automatically deploy the correct build for the target platform.

  4. Understand phpacker build output structure

    By default, the build process generates executables in the destination directory using the following naming pattern: {dest}/{platform}/{platform}-{architecture}[.exe].

  5. PHP binary build frequency and technology

    PHPacker utilizes static-php-cli to create minimal, statically-linked, self-contained PHP executables for each platform. These binaries are automatically rebuilt weekly to ensure the latest PHP versions are available shortly after release.

  6. Install PHPacker via Composer

    PHPacker can be installed either globally for system-wide use or as a development dependency within a specific project using Composer.
    # Install globally
composer global require phpacker/phpacker

# Install as a project dependency
composer require phpacker/phpacker --dev

  7. Handle file system access in packaged PHPacker apps

    Packaged PHPacker applications (single scripts or PHARs) cannot write files within the application bundle because the executable is a combined single file. Application data must be stored in platform-specific application data directories. Use the following logic to determine the correct path based on the operating system:

    • macOS: ~/Library/Application Support/.app-name
    • Windows: %LOCALAPPDATA%\app-name
    • Linux: ~/.app-name
    use Symfony\Component\Filesystem\Path;

$appName = 'my-app';
// Define APP_DATA constant
define('APP_DATA', match (PHP_OS_FAMILY) {
    'Darwin' => Path::join(getenv('HOME'), 'Library', 'Application', 'Support', ".{$appName}"),
    'Windows' => Path::join(getenv('LOCALAPPDATA'), $appName),
    default => Path::join(getenv('HOME'), ".{$appName}")
});

  8. Handle command line arguments in PHPacker apps

    For robust CLI argument handling in a PHPacker application, it is recommended to use a dedicated library such as symfony/console, laravel-zero, or minicli.

  9. Manage dependencies for PHPacker executables

    When building an executable with PHPacker from a single PHP script, all code must be contained within that file. External dependencies via require or use statements are not supported. For applications requiring external dependencies, package the application as a PHAR archive using a tool like humbug/box before using PHPacker.

  10. Create a custom PHP build with specific extensions

    PHPacker allows the use of custom PHP builds with specific extensions by utilizing the php-bin repository. To create a custom build, follow these steps:

    1. Fork the phpacker/php-bin repository.
    2. Modify the php-extensions.txt file to include the desired supported extensions.
    3. Add your GitHub token to the fork's configuration.
    4. Execute the GitHub Workflows to build the binaries.
    5. Tag a release to finalize the build.

  11. Configure the PHPacker Composer Installer alias

    Define the command name (alias) that users will use to execute your application by adding the phpacker-install key to the extra section of your composer.json file.
    "extra": {
    "phpacker-install": "my-app"
}

  12. Check phpacker supported platforms and PHP versions

    PHPacker supports the following platforms, architectures, and PHP versions (8.2, 8.3, 8.4, 8.5):
    PlatformArchitecturePHP Versions
    macOSarm64, x648.2 - 8.5
    Linuxarm64, x648.2 - 8.5
    Windowsx648.2 - 8.5