imliam/php-catch-exit

Gracefully handle an unwanted exit statement.

v1.0.0 2018-09-08 16:18 UTC

This package is auto-updated.

Last update: 2024-02-29 03:18:10 UTC


README

Latest Version on Packagist Total Downloads License

Gracefully handle an unwanted exit statement.

🤔 F.A.Q.

Why would you need this?

This shouldn't be needed at all, really. There is virtually no practical reason to have an exit statement over an exception in a modern PHP application, as all frameworks have their own decent, extendable exception handlers that should be taken full advantage of.

That said, a lot of beginners PHP tutorials end up showing the same sort of code for your first database connection:

<?php
$db = mysql_connect(...) or die('Could not connect.');

Luckily this is a thing of the past for the most part, but unfortunately still seems to be a practice some people use. Over the past few years, I still occasionally come across Composer packages that still use exit and die statements when an error occurs.

These packages should be avoided entirely - or better yet, fork or submit a pull-request when they pop up.

So why do this?

This package/function is more of a proof-of-concept to show how these situations can be handled, rather than a serious suggestion of a way to keep working with them.

💾 Installation

You can install the package with Composer using the following command:

composer require imliam/php-catch-exit:^1.0.0

📝 Usage

If you've ever written a basic exit statement before, you'll understand that, if the output buffer is empty at that point, you'll be greeted with a blank white screen in the browser with text given to the statement.

exit('Something went wrong.');

This package adds a single helper function that will accept a closure as the first argument. This closure is where you can add any code that you expect could throw an exit statement - just like the try block of a try-catch statement.

Assuming no exit occurs, you can return a value from this closure and continue your application like normal.

$var = catch_exit(function() {
    return "It's all okay.";
}, ...);

echo $var; // "It's all okay."

Print a string

The second argument of the function can accept a string which will be output to the buffer if an early exit occurs in the closure from the first argument.

This lets you decide what gets shown instead of the previous content, which may be out of your control.

catch_exit(function() {
    exit('Uh-oh!');
}, 'Something went wrong.');

// 'Something went wrong.' is displayed

You can also use this to render a view that can be displayed to the user in case this occurs.

Execute a closure

However, the second argument can also be another closure which will only be executed if there is an early exit occurring in the first closure. It'll also give you access to the current output buffer

Here, you can gracefully handle the way the application shuts down. You may want to perform some actions such as:

  • Log the error that occurred
  • Flash a message to the session to inform the user what happened
  • Render an error page to the user
  • Redirect the user back to the previous page
catch_exit(function() {
    exit('Uh-oh, something went wrong!');
}, function($message) {
    Log::error("The application exited with the following message: '{$message}'");

    return View::make('errors.500')
        ->with('error', 'An unexpected error occurred.');
});

This can also be used to handle fatal errors - such as when a class that doesn't exist is being instantiated or when the request exceeds the maximum execution time for PHP.

catch_exit(function() {
    new ClassThatDoesNotExist();
}, function($message) {
    // ...
});

🔖 Changelog

Please see the changelog file for more information on what has changed recently.

⬆️ Upgrading

Please see the upgrading file for details on upgrading from previous versions.

🎉 Contributing

Please see the contributing file and code of conduct for details on contributing to the project.

🔒 Security

If you discover any security related issues, please email liam@liamhammett.com instead of using the issue tracker.

👷 Credits

♻️ License

The MIT License (MIT). Please see the license file for more information.