DatabaseStoreException

Overview

DatabaseStoreException is a custom exception class in the Midnite81\Guardian package. This exception is thrown when there are issues related to database operations within the DatabaseStore class, which is one of the storage options for the Guardian rate limiting system.

Class Details

• Namespace: Midnite81\Guardian\Exceptions\Store

• Extends: StoreException

Purpose

The primary purpose of this exception is to provide specific error handling for database-related issues that may occur when Guardian is using a database for storing rate limiting data. It helps distinguish database-specific errors from other types of storage errors in the Guardian system.

Usage

This exception is typically thrown by the DatabaseStore class when it encounters issues with database operations such as:

• Failed connections

• Query execution errors

• Data integrity issues

Example of where this exception might be thrown (inside DatabaseStore):

try {
    $stmt = $this->pdo->prepare("SELECT * FROM {$this->tableName} WHERE `key` = :key");
    $stmt->execute(['key' => $key]);
    // ... more code ...
} catch (PDOException $e) {
    throw new DatabaseStoreException($e->getMessage(), $e->getCode(), $e);
}

Catching and Handling

When using Guardian with a database store, you should be prepared to catch and handle this exception:

use Midnite81\Guardian\Exceptions\Store\DatabaseStoreException;

try {
    // Your Guardian code using DatabaseStore
    $guardian->send(function() {
        // Your rate-limited code here
    });
} catch (DatabaseStoreException $e) {
    // Log the error
    error_log("Database error in Guardian: " . $e->getMessage());
    
    // Gracefully degrade or use a fallback mechanism
    // For example, you might choose to allow the request in case of storage errors
    return true;
}

Best Practices

1. Always catch this exception when using Guardian with a DatabaseStore.

2. Log the exception details for debugging and monitoring purposes.

3. Implement appropriate fallback mechanisms or graceful degradation when database operations fail.

4. Consider using a different storage mechanism (like Redis or file-based storage) if database issues are frequent.

Error Messages

The error messages for this exception will typically include details about the specific database operation that failed. These can include:

• SQL query errors

• Connection issues

• Constraint violations

For example:

SQLSTATE[HY000]: General error: 1 no such table: guardian_cache

Integration with Guardian

This exception is an integral part of Guardian's error handling system for database storage. It allows the system to differentiate between different types of storage errors and provide more specific error handling and reporting.

Security Considerations

When handling DatabaseStoreException, be careful not to expose sensitive database information in user-facing error messages. Always log the full exception details securely, but provide only general error messages to end-users.

Troubleshooting

If you frequently encounter DatabaseStoreException:

1. Check your database connection settings.

2. Ensure the required tables are properly set up (Guardian should create these automatically, but check if there are permission issues).

3. Verify that your database user has the necessary permissions for the operations Guardian is attempting.

4. Consider increasing your database's max_connections if you're hitting connection limits.

By properly handling DatabaseStoreException, you can ensure that your application gracefully manages database-related issues in the Guardian rate limiting system, maintaining reliability and performance even when database operations fail.