Quickly create phar files using Box

Phar is an analog jar from the world of Java, but only with reference to PHP. Phar packs project files into a special archive and allows you to easily transfer and install the application without manipulating the project itself as an executable program.


')
To create phar files in PHP, there is a fairly ragged API , but there is an easier and more convenient way to use the Box project.

JSON file format

The Box project allows you to describe the process of creating a phar file in a convenient JSON format.

The simplest file looks like this:

 { "files": ["src/Put.php"], "main": "bin/main", "output": "example.phar", "stub": true } 

Where

files - files to be included in phar

main - the file that will be executed when calling the phar file

output - the name of the final phar file

stub - for console applications set to true

Here you can see the process of creating a phar-file on the example of a simple project.

Here is a list of all possible box.json parameters with comments.

Let's try to assemble a phar-file using the example of a real project. As an example, take the Nasgrate database migration system . “Traditionally” this system is installed either through cloning the repository from GitHub, or through Composer. We will try to make a separate utility that you can just download and start using nothing at all without knowing about PHP.

Create box.json at the root of the project

 { "chmod": "0755", "directories": ["src","app"], "files": ["README.md"], "main": "bin/nasgrate", "output": "nasgrate.phar", "stub": true } 

directories - this parameter contains a list of directories that will be fully included in the project (in this case, the src and app directories).

files - if you need to include any specific files, list them here.

We could for example rewrite box.json as follows

 { "chmod": "0755", "directories": ["src"], "files": ["app/console.php", "app/index.php", "README.md"], "main": "bin/nasgrate", "output": "nasgrate.phar", "stub": true } 

In addition to these two recording options, there is still the possibility to selectively include files in the project based on filters. For example, if external libraries were actively used in a project and they were located in the vendors folder, we would like to include the files of these libraries in the project, but exclude, for example, all tests. Then the file would look like this.

 { "chmod": "0755", "directories": ["src"], "files": ["app/console.php", "app/index.php", "README.md"], "finder": [ { "name": "*.php", "exclude": [ "tests", "test" ], "in": "vendor" } ], "main": "bin/nasgrate", "output": "nasgrate.phar", "stub": true } 

the finder section in this case says: “include all files with the *.php extension from the vendor directory except for the tests and test folders“.

chmod - allows you to set permissions on the phar file. In this case, we put 0755 to make the file executable.

The remaining parameters have been described above.

Box installation

The easiest (and recommended) installation method

 $ curl -LSs https://box-project.imtqy.com/box2/installer.php | php 

after that box.phar will appear in the current directory.

You can run it as php box.phar , or assign permissions to execute chmod 755 box.phar , rename it to box mv box.phar box and transfer to /usr/local/bin . Then it can be run from anywhere just like box .

Alternative installation via Composer

 $ composer global require kherge/box --prefer-source 

or add it to an existing project

 { "require-dev": { "kherge/box": "~2.5" } } 

Check the installation

 $ box -v 

should display a description of the program and a list of possible options.

Next, you need to check that in your php.ini file the parameter phar.readonly set to 0 , Off or false .

Find out where our file is located, which is relevant specifically for the console (if you run phpinfo (); via Apache, it will show you another php.ini):

 $ php -i | grep php.ini >> Configuration File (php.ini) Path => /usr/local/php5/lib >> Loaded Configuration File => /usr/local/php5/lib/php.ini 

Next, we find the parameter phar.readonly and set it to Off .

 [Phar] ; http://php.net/phar.readonly phar.readonly = Off 

Project compilation

Go to the folder with the project (to the level where our box.json ) and run the compilation

 $ box build -v 

The -v flag allows us to see what happens during the compilation process.

  Removing previously built Phar... * Building... ? Output path: /Users/dlevsha/Sites/nasgrate/nasgrate.phar ? Adding directories... + /Users/dlevsha/Sites/nasgrate/src/config.php + /Users/dlevsha/Sites/nasgrate/src/Driver/Base/Dump.php + /Users/dlevsha/Sites/nasgrate/src/Driver/Base/Generator.php + /Users/dlevsha/Sites/nasgrate/src/Driver/Base/Helper.php + /Users/dlevsha/Sites/nasgrate/src/Driver/Base/Migration.php + /Users/dlevsha/Sites/nasgrate/src/Driver/Mysql/Dump.php + /Users/dlevsha/Sites/nasgrate/src/Driver/Mysql/Generator.php + /Users/dlevsha/Sites/nasgrate/src/Driver/Mysql/Helper.php + /Users/dlevsha/Sites/nasgrate/src/Process/Base.php + /Users/dlevsha/Sites/nasgrate/src/Process/Console.php + /Users/dlevsha/Sites/nasgrate/src/Process/Server.php + /Users/dlevsha/Sites/nasgrate/src/template.sql + /Users/dlevsha/Sites/nasgrate/src/Util/Console.php + /Users/dlevsha/Sites/nasgrate/src/Util/Db.php + /Users/dlevsha/Sites/nasgrate/app/console.php + /Users/dlevsha/Sites/nasgrate/app/index.php ? Adding files... + /Users/dlevsha/Sites/nasgrate/README.md ? Adding main file: /Users/dlevsha/Sites/nasgrate/bin/nasgrate ? Generating new stub... ? Setting file permissions... * Done. 

After that, the file nasgrate.phar will appear in the project directory.

Check that everything compiled properly

 $ ./nasgrate.phar 

will display the utility description

 Nasgrate is a console utility that let you organise database schema migration process at a consistent and easy way. It supports mysql, mssql, postgresql, oracle and other databases Usage: php nasgrate [command] [options] Command: status - displays migration status generate - creates new migration (migration file) up:show - displays (but not executes) SQL-query, executed by migration update ... 

Work with external resources

A feature of the work of phar is that it searches for all the resources inside its archive. In most cases, this is not a problem, since it is for this that we phar and made it independent of the environment. But there are a number of cases when the resources inside the phar archive need to work with external files.

Using the example of Nasgrate, it is necessary to read the configuration from the .environment file, write migration files and state files to an external directory.

If we try to specify a relative path inside the project, such as ../.environment , an error is generated because there is no such file inside phar .

There are two ways to solve this problem:

The first option is to map the external file to the internal space of the phar file.

 Phar::mount('phar://.environment', '/etc/nasgrate/.environment'); 

The problem is that you need to know exactly the absolute path to the file.

The second option is to specify the path from the current location of the phar file. Like that:

 define(DIR_RUN, dirname(Phar::running(false))); 

Then you either use Phar :: mount to put it into the internal phar space phar or simply specify the absolute path to the configuration file. Suppose the configuration file is in the same folder as phar itself

 define(DIR_RUN, dirname(Phar::running(false))); Phar::mount('phar://.environment', DIR_RUN.'/.environment'); 

and then refer to it as a local file, or always refer to the absolute path.

There is one remark, I don’t know this bug or feature, but all the directories connected via Phar::mount are in readonly mode and how to change it is not very clear. When addressing the absolute path of such problems does not arise.

Another kind of obvious point, but worth paying attention to. Phar file contains resources of your project and does not regulate the presence of connected libraries to php itself, its version, etc. That is, if you use some kind of php extension, for example, PDO or even installed something from PECL, or use some features of a particular version of php, your phar will not contain information about the runtime environment. If you use traits from PHP 5.4, for example, and the user is 5.3, then an error will be generated. You should check all required dependencies inside your application.

Related Links:

• Official documentation
• Project Box on GitHub
• Full description of the box.json parameters
• External config files with PHAR archives
• Secure PHAR Automation
• Boxing Up Your Apps as Phars Quickly and Easily with Box
• Article "Creating and using PHAR archives on the IBM website"