/box

📦🚀 An application for building and managing PHARs.

Primary LanguagePHPMIT LicenseMIT

Package version Travis Build Status Scrutinizer Code Quality Slack License

Fork of the unmaintained box2 project. This project needs your help!

Roadmap:

Goal

The Box application simplifies the PHAR building process. Out of the box (no pun intended), the application can do many great things:

  • Retrieve information about the PHAR extension or a PHAR file
  • List the contents of a PHAR
  • Verify the signature of an existing PHAR
  • Generate RSA (PKCS#1 encoded) private keys for OpenSSL signing
  • Extract public keys from existing RSA private keys
  • Use Git tags and short commit hashes for versioning.

Table of Contents

  1. Installation
    1. PHAR (preferred but NOT SUPPORTED YET)
    2. Composer
  2. Creating a PHAR
  3. Configuration
    1. Base path
    2. Output
    3. Main
    4. Permissions
    5. Including files
      1. Files (files and files-bin)
      2. Directories (directories and directories-bin)
      3. Finder (finder and finder-bin)
      4. Blacklist (blacklist)
    6. Stub
      1. Stub (stub)
      2. Alias (alias)
      3. Shebang (shebang)
      4. Banner (banner)
      5. Banner file (banner-file)
    7. Compactors (compactors)
    8. Compression algorithm (compression)
    9. Signing algorithm (algorithm)
  4. Contributing
  5. Upgrade
  6. Backward Compatibility Promise (BCP)
  7. Credits

Installation

PHAR (preferred but NOT SUPPORTED YET)

The preferred method of installation is to use the Box PHAR, which can be downloaded from the most recent Github Release. Subsequent updates can be downloaded by running:

box self-update

As the PHAR is signed, you should also download the matching box.phar.pubkey to the same location. If you rename box.phar to box, you should also rename box.phar.pubkey to box.pubkey.

Composer

You can install Box with Composer:

composer global require humbug/box:^3.0@dev

If you cannot install it because of a dependency conflict or you prefer to install it for your project, we recommend you to take a look at bamarni/composer-bin-plugin. Example:

composer require --dev bamarni/composer-bin-plugin
composer bin box require --dev humbug/box:^3.0@dev

Keep in mind however that this library is not designed to be extended.

Creating a PHAR

Creating a PHAR should be as simple as running box compile. It will however assume some defaults that you might want to change. The most basic configuration is the following:

# box.json.dist
{
    "main": "bin/acme.php",
    "output": "bin/acme.phar"
}

You can then find more advanced configuration settings in the configuration documentation. For more information on which command or options is available, you can run:

box help

Contributing

The project provides a Makefile in which the most common commands have been registered such as fixing the coding style or running the test.

make

Upgrade

Check the upgrade guide.

Backward Compatibility Promise (BCP)

The policy is for the major part following the same as [Symfony's one][symfony-bc-policy]. Note that the code marked as @private or @internal are excluded from the BCP.

Credits

Project originally created by: Kevin Herrera (@kherge) which has now been moved under the Humbug umbrella.