Article: Boxing up your Apps as Phars Quickly and Easily with Box

An excerpt from, by @swader

In this tutorial, we’ll use Box to package a PHP application into a Phar, in order to make it easily distributable and globally installable via Composer.

On what?

We need a project for this, and packaging up yet another “Hello World” script would be pointless. We’ll use Webiny’s FolderBuilder, a tool which you can use to plan out the folder structure for your project, interactively drag and drop files and folders, and even export and share these structures with others.

But that’s almost entirely a JavaScript tool, why would we be using Phars for it? Yes, that GUI is JS, but if you look at the repo you’ll notice a PHP script inside which you can run on any folder and get the required JSON generated. This means you can easily generate FolderBuilder compatible structures from existing projects, too, which is super handy for planning a project’s restructuring.

While it’s very simple to just download and run the script from any folder you’d like to parse into JSON, why not make the whole project Phar-distributable and allow for something like:

composer global require webiny/folderbuilder
folderbuilder . > structure.json


Let’s bootstrap a Box project. First, we need to install Box if it’s not already present on our system. I am, of course, using Homestead Improved as usual to keep things isolated from my host OS.

composer global require kherge/box

We could download the phar of Box and use that, but we’re a Composer crowd here, we don’t use those outdated platform-specific methods :wink:

Now that’s done, the box command is accessible from anywhere on our machine:

To package an app with Box, one needs to include a box.json file in the project’s folder. The simplest of these can be seen in the example application:

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

The project we’ll be packaging has a lot of files, but only one we actually need for the Phar to be useful, so to keep it light, we’ll only package that one (and another, but more on that later). In that regard, our json file won’t be all that different (though if you’d like to see a more complex one, see the from Box itself here). Let’s begin!


Note for Vagrant users: when using Vagrant boxes such as Homestead Improved the Phar extension won’t be able to write files for some reason. The solution is to either change the “output” property to a folder outside the shared one, or to do everything outside a shared folder altogether. We’ll take the latter approach in this case and just do everything inside the Vagrant user’s “home” folder.

The first thing we do is, of course, clone the repo:

cd ~
git clone
cd folderbuilder
git checkout 74b234fa33bd69690a2c26df38ef7d188c4e69eb

The last command is necessary so that you end up in a state of the project before I applied the fixes outlined in this post.

Then, we create the file box.json and populate it with:

    "files": ["structure.php"],
    "output": "bin/wfb.phar",
    "stub": true,
    "main": "structure.php"

So what does this mean?

The “files” property lists all the files we want to include in the Phar. “output” is the product of our build, and “main” indicates the entry file. “stub” is required when using CLI apps. The help file says:

“The stub (string, boolean) setting is used to specify the location of a stub file, or if one should be generated. If a path is provided, the stub file will be used as is inside the Phar. If true is provided, a new stub will be generated. If false (or nothing) is provided, the default stub used by the Phar class will be used.” and further explanation can be found here.

We make a bin folder because it’s a common place to put built/compiled resources.

Then, we run:

box build -v

Box will automatically detect the box.json file in the folder and produce output not unlike this one:

? Output path: /home/vagrant/folderbuilder/bin/wfb.phar
? Adding files...
  + /home/vagrant/folderbuilder/structure.php
? Adding main file: /home/vagrant/folderbuilder/structure.php
? Generating new stub...
* Done.

If we now execute the command:

php bin/wfb.phar

The current directory’s structure will be printed on screen in JSON format, just like if we ran php structure.php directly.

Continue reading this article on SitePoint!

This topic was automatically closed 91 days after the last reply. New replies are no longer allowed.