How to debug PHP code under Linux when just an blank page is shown?
When a developer writes C++ or Java code, seeing a stack trace in the console immediately tells you where execution halted. In PHP, however, the default behavior on many Linux systems is to swallow errors and render a pristine white screen. This isn't because your code is broken; it's often because of how the web server is configured to handle production-like environments by default.
To get from "blank page" to "stack trace," you need to modify the PHP configuration file, typically located at /etc/php/8.x/apache2/php.ini (for Apache) or /etc/php/8.x/cli/php.ini (for CLI). Look for the directive display_errors. By default, this is often set to Off, which tells the interpreter to log errors but not output them. Change it to:
display_errors = On
You also need to ensure that error logging isn't silently failing. Find log_errors and set it to On as well. If you are using Apache, you must also verify that the PHP module is actually passing those errors to the server. In your /etc/apache2/sites-available/000-default.conf, ensure there is a line like:
php_flag display_errors On
php_flag log_errors On
Once you reload Apache (sudo systemctl reload apache2), visiting your script with a fatal error should finally reveal the stack trace. This gives you the file path, line number, and the exact code block that crashed, mimicking the debugging experience you are used to from compiled languages.
However, simply turning on display_errors in a production environment is generally considered a bad practice. It exposes sensitive paths and internal logic to anyone who triggers an exception. For local development on Linux, this trade-off is acceptable because you control the machine. In a shared hosting or cloud environment, however, you might want to keep display_errors off but ensure that errors are logged to a file where you can inspect them later.
If your blank page persists even after adjusting these settings, check the error log files themselves. On Debian/Ubuntu systems, these are usually located in /var/log/php-fpm/error.log or /var/log/apache2/error.log. If the web server is configured to suppress HTML output on fatal errors without logging them properly (which can happen if log_errors is missing), you will see nothing in the browser and potentially nothing in the logs.
Another common pitfall involves the PHP handler configuration. If you are using FastCGI Process Manager (php-fpm), ensure the pool configuration (/etc/php/8.x/fpm/pool.d/www.conf) also has display_errors set to On. A mismatch between the Apache config and the php-fpm config will result in errors being logged by one but displayed by neither.
For a more robust debugging workflow that feels closer to modern frameworks, consider integrating a tool like Laravel's Debugbar or using a debugger like Xdebug. Xdebug allows you to step through code line-by-line directly from your browser or IDE, even on Linux. To enable this, add the following lines to your php.ini:
zend_extension=xdebug.so
xdebug.start_with_request=yes
xdebug.mode=debug,develop
Note that enabling Xdebug comes with a performance cost. It slows down execution significantly compared to standard PHP. While this is negligible for local development on a single machine, it can impact high-traffic production servers. Always weigh the benefit of interactive debugging against runtime performance before deploying such changes globally.
Finally, remember that blank pages often stem from exit() calls or fatal errors that occur before any output is generated. If you are seeing a 500 Internal Server Error instead of a blank page, your server is likely configured to return an error document rather than displaying the trace. Check your .htaccess file or virtual host configuration for directives like ErrorDocument 500 /error.php. Ensure these aren't masking the underlying issue you are trying to solve.
By systematically adjusting these configuration flags and understanding where errors are being logged, you transform a confusing blank screen into actionable data. Whether you stick with standard error reporting or integrate Xdebug, the goal remains the same: visibility into what your code is doing when it fails.