<?php

/**
 * Map internal exceptions to safe, identifiable API error messages (details go to error_log).
 */
function qdb_public_error_message(Throwable $e, string $contextLabel = 'Operation'): string
{
    $msg = $e->getMessage();

    if (str_contains($msg, 'Could not acquire lock') || str_contains($msg, 'Could not open lock')) {
        return 'Database is busy. Please try again in a moment.';
    }
    if (str_contains($msg, 'decrypt') || str_contains($msg, 'QDB_MASTER_KEY')) {
        return 'Database configuration error. Contact the server administrator.';
    }
    if (str_contains($msg, 'Could not read') || str_contains($msg, 'Could not write')
        || str_contains($msg, 'Could not save')) {
        return 'Database storage error. Contact the server administrator.';
    }
    if ($e instanceof PDOException) {
        return $contextLabel . ' failed due to a database error.';
    }

    return $contextLabel . ' failed. If this persists, contact support.';
}