PHP Exception Handling - ErrorException

PHP Exception Handling – PharException

Making our way through our detailed PHP Exception Handling series, today we’ll explore the PharException. Phar is shorthand for PHP Archive. A phar file is a convenient way to compress and store an entire PHP application in a single executable file. This functionality is similar to JAR files found within the Java ecosystem.

Throughout this article we’ll examine what a PharException might be used for, starting with a brief look at where it sits in the PHP Exception Hierarchy. We’ll also dig into how phars are created and executed, so we can show how PharExceptions are most commonly thrown. Let’s get going!

The Technical Rundown

All PHP errors implement the Throwable interface, or are extended from another inherited class therein. The full exception hierarchy of this error is:

Full Code Sample

Below is the full code sample we’ll be using in this article. Feel free to use any or all of the code if you wish to follow along.

When Should You Use It?

Before we can understand what might cause a PharException, we should briefly go over how a phar is created and how it can be executed. To create a phar file we just need to use the Phar class. To start, here we have the createInvalidPhar.php script:

As you can deduce by the file name, this configuration isn’t quite right to create a valid phar file. As it happens, if we execute the above script we get a PharException, indicating we’ve attempted to create an invalid stub for our phar file:

As it happens, a phar archive must be made up of at least three components:

  • A manifest describing the archive contents.
  • The file contents.
  • A simple PHP file called the stub.

The stub can contain just about any code, but, at minimum, it must at least contain an opening PHP tag and the __HALT_COMPILER(); token:

In the createInvalidPhar.php script above, you’ll notice the call to setStub("") attempts to create an empty stub, which is invalid, hence the PharException.

Let’s fix this issue in the createMinimalPhar.php script:

Now that we have the minimal stub contents included, executing this script works fine and a new minimal.phar file is created within the project directory. However, what happens if we try to execute it?

Nothing. While the minimal.phar file contains all the contents of our project directory, it doesn’t have any instruction on what file to run when executed. Let’s add a bit more now in the createBasicPhar.php script:

Here we’ve added a couple more lines to allow the produced phar to be executable. Calling createDefaultStub($indexfile = null) allows us to specify the index (or default) file that will be executed when executing this phar. We also need to make sure it can be executed via the php command from the terminal, so we prefix the stub contents with "#!/usr/bin/env php \n". Everything else is the same as before, so now let’s try executing the basic.phar file that was just created:

The code.php file just creates a few Book objects and outputs them to the log, so that’s what is expected and exactly what we see above. This confirms that we were able to specify the code.php file should be the default file called when our basic.phar file is executed.

Finally, let’s take a look at the createAdvancedPhar.php script:

Here we’re illustrating that, rather than creating a stub via the createDefaultStub() function, we can manually create our own stub file, which we’ve added to stub.php in our project directory. I won’t include the full contents of this file here (scroll up to the full source to see it), but here’s a snippet:

This is basically just the default stub code, placed into the stub.php file. However, the ability to manually create your own stubs opens up a lot of avenues for customizing phar creation. As before, running createAdvancedPhar.php creates a new advanced.phar file, which we can execute as before to produce the same Book collection output we saw from the basic.phar file.

Check out the Airbrake-PHP library, designed to quickly and easily integrate into any PHP project, giving you and your team access to real-time error monitoring and reporting throughout your application’s entire life cycle. With automatic, instantaneous error and exception notifications at your fingertips, you’ll be constantly aware of your application’s health, including any issues that may arise. Best of all, with Airbrake’s robust web dashboard cataloging every error that occurs, you and your team can immediately dive into the exact details of what went wrong, making it easy to quickly recognize and resolve problems.