Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Spatie Ignition for Debugging #256

Merged
merged 11 commits into from
Dec 5, 2024
Prev Previous commit
Next Next commit
Add new readme with instructions
darylldoyle committed Dec 5, 2024
commit 36707ceb0d2e8b2d9aacfd98181db504eeff6bbe
112 changes: 112 additions & 0 deletions docs/debugging-php.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,112 @@
# Integrating Spatie Ignition for Enhanced Error Handling in WordPress

To improve the error-handling experience during development, you can utilize [Spatie Ignition](https://github.com/spatie/ignition). Ignition provides detailed, user-friendly error pages that make debugging more straightforward and more efficient.

This guide will walk you through the steps to set up and use Ignition.

## Prerequisites

* Composer is installed on your system.
* PHP version compatible with Spatie Ignition (check the [Ignition documentation](https://github.com/spatie/ignition) for requirements).

## Installation

To install it, run the following command in your project’s root directory:

```bash
composer require --dev spatie/ignition
```

This command will install the Ignition package into your project’s `vendor` directory.

## Configuration

To enable Ignition, you’ll need to modify your `wp-config.php` file.

### 1. Include the Composer Autoloader

Add the following line to your `wp-config.php` file, right below the `/* Add any custom values between this line and the "stop editing" line. */` line.

```php
/* Add any custom values between this line and the "stop editing" line. */

require_once( dirname( __FILE__ ) . '/wp-content/vendor/autoload.php' );
```

This line ensures that all Composer-managed packages, including Ignition, are autoloaded into your project.

### 2. Register Ignition

After including the autoloader, add the following code to register Ignition:

```php
/* Add any custom values between this line and the "stop editing" line. */

require_once( dirname( __FILE__ ) . '/wp-content/vendor/autoload.php' );

\Spatie\Ignition\Ignition::make()
->setTheme( 'dark' )
->shouldDisplayException( true === WP_DEBUG )
->register();
```

This snippet does the following:

* `setTheme('dark')`: Sets the error page theme to dark. You can change this to ``'light'`` if you prefer.
* `shouldDisplayException( true === WP_DEBUG )`: Configures Ignition to display exceptions only when `WP_DEBUG` is set to `true`.
* `register()`: Finalizes the setup and activates Ignition.

### 3. Ensure `WP_DEBUG` is Enabled

Make sure that `WP_DEBUG` is set to `true` in your `wp-config.php` during development:

```php
define( 'WP_DEBUG', true );
```

## **Usage**

With Ignition set up, any errors or exceptions that occur during development will be displayed using Ignition’s detailed error pages. These pages include:

* **Stack Traces**: Shows the sequence of function calls that led to the error.
* **Code Snippets**: Displays the relevant code around where the error occurred.
* **Contextual Data**: Provides information about variables and the environment at the time of the error.

## Customization

You can further customize Ignition to suit your needs:

### Changing the Theme

If you prefer a different theme, modify the `setTheme` method:

```php
->setTheme( 'light' ) *// Options are 'light' or 'dark'*
```

### Adjusting Error Display Conditions

You can control when errors are displayed by modifying the `shouldDisplayException` method:

```php
->shouldDisplayException( true )
```

Setting this to true will always display exceptions, regardless of the `WP_DEBUG` setting.

## Troubleshooting

### Ignition Not Displaying Errors

* Ensure that the autoloader path in `require_once` is correct.
* Verify that composer install has been run successfully.
* Confirm that `WP_DEBUG` is set to true.

### Composer Autoload File Not Found

* Double-check the path in your `require_once` statement. It should point to the `vendor/autoload.php` file within the `wp-content` directory.

## Additional Resources

* [Spatie Ignition Documentation](https://github.com/spatie/ignition)
* [WordPress Debugging Guide](https://developer.wordpress.org/advanced-administration/debug/debug-wordpress/)