Last Updated – May 2024
The Loader is able to display information about various errors and issues related to encoded files. These are thrown in the form of a PHP error. Sometimes, you will want to customize what each error message says, or have the error display in a more elaborate or aesthetically pleasing way. Which is why in this tutorial, we will be looking at how to specify custom error messages and how to use callback files.
Custom Error Messages
Custom error messages can be set on encoded files which will override the default messages provided by the Loader. This is useful for specifying additional information to the users of your scripts, such as instructions to follow, or stating websites to visit for support.
Before we begin, we shall specify that the encoded files require a license to be present (This is covered in the ‘Setting up Licensing’ tutorial). We shall then encode and attempt to run the file without a valid license file present. When we do, we are presented with the following message:
This is the default message that the Loader provides when a license is required but is not present. Now, if we wanted to modify the message so that it said something specific, we can do this in the “Project” > “Project Settings” > “Messages” tab.
As we can see, a custom error message has been specified. This will be what the user sees when they attempt to run the file without a license file present. Now we just need to re-encode the file and attempt to re-run the encoded file.
As we can see, the new custom error message is now being displayed for the same type of error as before. However, we can see that we now have our new error message displaying instead of the old one.
Callback Files
For instances where we want to do something more elaborate than simply displaying a PHP error message, we can specify a callback file. This file contains a function to call in the event of an error being produced, and gives much more flexibility over what the user will see.
Note: The callback file and any files that it uses must not require a license file or have any other restrictions that would stop them from running. In the event that they do, the callback file will simply produce a blank page, as it will be unable to access the callback function.
First, we need to specify the function. We’ll keep the behaviour simple for the sake of demonstration. The function must always be prototyped as function ioncube_event_handler($err_code, $params), as this is what the loader will attempt to call in the event of an error being produced.
<?php
function ioncube_event_handler($err_code, $params)
{
echo "<html><body>An error has occurred:<br><br>";
switch ($err_code)
{
case ION_LICENSE_NOT_FOUND:
echo "A license could not be found.";
break;
default:
echo "An unknown error occurred.";
break;
}
echo "</body></html>";
}
?>
Note the switch statement in the function. Various macros are defined with the Loader for convenience when handling errors. A full list of these macros can be found in the User Guide that can be found at http://www.ioncube.com/USER-GUIDE.pdf
Next, we need to tell the encoded files where the callback file is. This can be specified in the same screen as before, on the “Project” > “Project Settings” > “Messages” tab.
Once this has been done, we simply re-encode the files and trigger one of the errors (Don’t forget that callback files should not have any dependencies or restrictions set that may stop them from running properly). Doing so, we get the following output:
As we can see, the function we have specified has been executed, and the output has been selected appropriately from the error that was passed into it. And that’s all there is to customizing and beautifying your error messages. Remember that error message creation is not just restricted to license-related issues. Take a look through the list of available errors and see what kind of other things you can do.
