Error handling

Error Handling in MediaWiki 1.40

1. Introduction

Error handling is a crucial aspect of developing robust and maintainable extensions and applications within the MediaWiki framework. When things go wrong – and they *will* go wrong – a well-implemented error handling system can prevent your code from crashing, provide useful debugging information, and gracefully inform users about issues. This article provides a comprehensive guide to error handling in MediaWiki 1.40, aimed at developers of all skill levels. We will cover the different types of errors, the mechanisms MediaWiki provides for handling them, best practices, and advanced techniques.

1. Understanding Error Types

Before diving into handling errors, it's important to understand the different types of errors you might encounter in a MediaWiki environment. These fall broadly into three categories:

**Syntax Errors:** These are errors in the code itself, such as typos, missing semicolons, or incorrect function calls. These are generally caught during development by your code editor or during the parsing of PHP code. They prevent the script from even beginning to execute.
**Runtime Errors:** These occur while the code is running. They are often caused by unexpected data, incorrect logic, or external factors like database connection issues. Runtime errors can lead to a white screen of death (WSOD) for users if not handled properly. Common examples include:

   * **Division by zero:** Trying to divide a number by zero.
   * **Invalid array access:** Trying to access an element in an array that doesn’t exist.
   * **File not found:**  Trying to include or require a file that doesn't exist.
   * **Database errors:**  Problems connecting to or querying the database (e.g., invalid SQL syntax, table not found).

**Logic Errors:** These are the most difficult to detect. The code runs without crashing, but it produces incorrect results due to a flaw in the program's logic. Thorough testing and debugging are crucial for identifying logic errors. Examples include incorrect calculations, flawed conditional statements, or misunderstanding of API behavior.

1. MediaWiki's Error Handling Mechanisms

MediaWiki provides several mechanisms for handling errors. Understanding these is key to building reliable extensions:

1. 1. 1. `wfError()` and `wfFatalError()`

These are the primary functions for reporting errors in MediaWiki. They are part of the `global` scope and are designed to be used throughout your code.

**`wfError( $message, $category = 'error' )`:** This function logs an error message and displays it to the user (if the user has debugging enabled). It doesn't halt execution; the script continues to run after the error is logged. The `$category` parameter allows you to categorize the error for easier filtering and analysis. Common categories include 'error', 'warning', and 'notice'. Using categories effectively is critical for debugging. This function is suitable for non-critical errors that don’t prevent the application from functioning.
**`wfFatalError( $message, $category = 'fatal' )`:** This function logs a fatal error message and *immediately halts* script execution. It displays a more prominent error message to the user. Use this function for errors that are severe enough to prevent the application from continuing safely. For example, a critical database connection error would warrant a `wfFatalError()`.

Both functions accept a `$message` parameter, which should be a clear and informative description of the error. It's also good practice to include relevant variables or context in the message to aid in debugging.

1. 1. 2. Exceptions

MediaWiki supports PHP's exception handling mechanism. Exceptions are a more structured way to handle errors, particularly runtime errors. Using exceptions allows for more controlled error propagation and recovery.

**`try...catch` Blocks:** Wrap code that might throw an exception in a `try` block. If an exception is thrown, the corresponding `catch` block will be executed.
**`throw new Exception( $message )`:** You can manually throw an exception using the `throw` keyword. This is useful when you detect an error condition that you want to handle in a higher level of the code.
**Custom Exceptions:** You can create your own custom exception classes by extending the base `Exception` class. This allows you to define specific error types for your extension and handle them accordingly. Consider creating custom exceptions for specific failures within your extension, such as `MyExtensionDatabaseException` or `MyExtensionConfigurationException`.

1. 1. 3. `Logger` Class

MediaWiki's `Logger` class (available through `$wgLogger`) provides a more sophisticated way to log errors and other events. It allows you to log messages to different destinations (e.g., files, databases) and at different levels of severity (e.g., debug, info, warning, error, fatal). The Logger class is particularly useful for logging errors that don't necessarily need to be displayed to the user but are important for debugging and monitoring. You can configure the Logger's behavior in `LocalSettings.php`. [Log analysis](https://www.loggly.com/ultimate-guide/log-analysis/) is a crucial skill when using the Logger.

1. 1. 4. `$wgDebugLogFile` and Debugging Configuration

MediaWiki provides a global configuration variable, `$wgDebugLogFile`, which specifies the file where debugging messages are written. You can enable debugging by setting `$wgDebug` to `true` in `LocalSettings.php`. This will cause MediaWiki to log more detailed information about errors and other events to the debug log file. Debugging settings can be adjusted for production environments to minimize performance impact. [Performance tuning](https://www.sitepoint.com/php-performance-tuning/) is important when enabling debugging features.

1. Best Practices for Error Handling

**Be Specific:** Error messages should be as specific as possible. Instead of "An error occurred," use "Failed to connect to the database: Connection refused." Include relevant details like variable values, file paths, and function names.
**Log Everything:** Log all errors, even those that are handled gracefully. This will help you identify patterns and prevent future issues. Utilize the `Logger` class for comprehensive logging.
**Handle Errors Gracefully:** Whenever possible, handle errors in a way that doesn't disrupt the user experience. Display user-friendly error messages and provide options for recovery.
**Don't Expose Sensitive Information:** Avoid displaying sensitive information (e.g., database credentials, internal file paths) in error messages.
**Use Exceptions Appropriately:** Use exceptions for runtime errors that require more controlled error propagation and recovery. Avoid using exceptions for predictable error conditions that can be handled directly.
**Test Your Error Handling:** Thoroughly test your error handling code to ensure that it works as expected. Simulate different error conditions and verify that the application responds correctly. [Unit testing](https://www.guru99.com/php-unit-testing.html) is highly recommended.
**Document Your Error Handling:** Document your error handling strategies so that other developers can understand how to handle errors in your code. [API documentation](https://www.oracle.com/technical-resources/064658.html) is particularly important.
**Centralized Error Handling:** Consider implementing a centralized error handling mechanism that intercepts all errors and logs them to a central location. This will make it easier to monitor and analyze errors across your entire application.
**Avoid `die()` and `exit()`:** These functions abruptly terminate script execution and can leave the application in an inconsistent state. Use `wfFatalError()` or exceptions instead.
**Sanitize Input:** Prevent errors caused by malicious or unexpected input by sanitizing all user-provided data. [Input validation](https://owasp.org/www-project-top-ten/) is a critical security measure.

1. Advanced Techniques

1. 1. 1. Custom Error Handlers

You can define your own custom error handlers to intercept PHP's native error reporting mechanism. This allows you to log errors in a custom format or perform other actions before the error is displayed. Use the `set_error_handler()` function to register your custom error handler.

1. 1. 2. Error Reporting Levels

PHP provides different error reporting levels (e.g., `E_ERROR`, `E_WARNING`, `E_NOTICE`). You can control which error levels are reported using the `error_reporting()` function. Configure these levels carefully to balance debugging needs with performance considerations. [PHP documentation on error reporting](https://www.php.net/manual/en/language.error-reporting.php) provides detailed information.

1. 1. 3. Error Context

When handling errors, it's often helpful to have access to the context in which the error occurred. This includes information such as the file name, line number, and function call stack. PHP's `debug_backtrace()` function can be used to obtain the call stack. The `$wgDebugLogFile` often includes this information automatically.

1. 1. 4. Error Monitoring Services

Consider integrating your MediaWiki instance with an error monitoring service such as Sentry or Rollbar. These services can automatically collect and analyze errors, providing valuable insights into the health of your application. [Sentry documentation](https://docs.sentry.io/) and [Rollbar documentation](https://rollbar.com/docs/) offer detailed setup instructions.

1. 1. 5. Using `wfRunHooks` for Error Handling Interception

MediaWiki's hook system allows you to intercept and modify error handling behavior. You can create a hook that is triggered whenever an error is reported, allowing you to log the error, display a custom message, or perform other actions. Understanding Hooks is crucial for extending MediaWiki functionality.

1. Example Code Snippet

```php <?php

function myExtensionFunction( $input ) {

 try {
   if ( !is_numeric( $input ) ) {
     throw new Exception( 'Input must be a number.' );
   }
   $result = 10 / $input;
   return $result;
 } catch ( Exception $e ) {
   wfError( 'Error in myExtensionFunction: ' . $e->getMessage(), 'my-extension' );
   return false; // Or handle the error in a different way
 }

}

// Example usage $value = 0; $result = myExtensionFunction( $value );

if ( $result === false ) {

 wfError( 'myExtensionFunction failed.', 'my-extension' );

} else {

 echo "Result: " . $result;

}

?> ```

This example demonstrates how to use `try...catch` blocks to handle exceptions and how to use `wfError()` to log errors to the user. The error is categorized as 'my-extension' for easier filtering. This snippet demonstrates the importance of PHP fundamentals when writing extensions.

1. Resources

[MediaWiki Developer Documentation](https://www.mediawiki.org/wiki/Developer_documentation)
[PHP Error Handling](https://www.php.net/manual/en/language.errors.php)
[OWASP Error Handling Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/Error_Handling.html)
[Exception Handling Best Practices](https://www.baeldung.com/java-exception-handling) (Principles applicable to PHP)
[Database Error Handling in PHP](https://www.tutorialspoint.com/php/php_database_error_handling.htm)
[Debugging Techniques for PHP](https://www.ionos.com/digitalguide/server/development/debugging-php-code/)
[Monitoring and Alerting Tools](https://www.datadoghq.com/blog/monitoring-tools/)
[Log Management Solutions](https://www.splunk.com/en_us/data-insights/solutions/log-management.html)
[Understanding Backtraces](https://stackoverflow.com/questions/2896979/what-is-a-backtrace-and-how-can-i-use-it)
[Error Analysis techniques](https://www.bmc.com/blogs/error-analysis/)

MediaWiki Development PHP Debugging Hooks Extensions API Configuration Database Security Performance

Start Trading Now

Sign up at IQ Option (Minimum deposit $10) Open an account at Pocket Option (Minimum deposit $5)

Join Our Community

Subscribe to our Telegram channel @strategybin to receive: ✓ Daily trading signals ✓ Exclusive strategy analysis ✓ Market trend alerts ✓ Educational materials for beginners

Error handling

Start Trading Now

Join Our Community

Navigation menu