Messages, Locks, And Errors

Packages should use QUIQQER's message and lock APIs instead of ad-hoc status storage or direct UI notifications.

Messages

Use the message handler for user-facing messages.

QUI::getMessageHandler()->addSuccess('The item was saved.');
QUI::getMessageHandler()->addInformation('The import has started.');
QUI::getMessageHandler()->addAttention('The item requires attention.');
QUI::getMessageHandler()->addError('The item could not be saved.');

add*() methods add messages for the current response. Use send*() methods when a message should be stored for a specific user and shown later.

$User = QUI::getUsers()->get($userId);

QUI::getMessageHandler()->sendInformation(
    $User,
    'The background import has finished.'
);

Do not use messages as logs. Use QUI\System\Log for operational diagnostics and messages only for information that should be visible to users.

JavaScript Messages

Browser controls can use the frontend message handler:

QUI.getMessageHandler().then(function (MH) {
    MH.addSuccess('Saved');
    MH.addError('Could not save the item');
});

Use JavaScript messages for immediate UI feedback after Ajax requests or local interactions.

Locks

Use QUI\Lock\Locker when an object must not be edited or processed concurrently.

$Package = QUI::getPackage('vendor/package');
$key = 'import-' . $importId;

QUI\Lock\Locker::checkLocked($Package, $key);
QUI\Lock\Locker::lock($Package, $key, 600);

try {
    // Run exclusive work.
} finally {
    QUI\Lock\Locker::unlock($Package, $key);
}

Use a package-specific key that identifies the locked object or process. lock() stores the lock in the cache and uses the session lifetime when no lifetime is provided.

For user-facing edit locks, use lockWithPermissions() and unlockWithPermissions() when the operation must also check permissions.

Error Codes

QUIQQER exceptions can carry numeric or symbolic codes. Use stable error codes when callers need to distinguish known failure cases.

throw new QUI\Exception(
    'The item already exists.',
    1108
);

For a package, define package-local constants when the same codes are used in multiple classes:

namespace Vendor\Package;

final class ErrorCodes
{
    public const ITEM_NOT_FOUND = 2101;
    public const ITEM_ALREADY_EXISTS = 2102;
}

Keep error codes stable once they are used by UI code, tests, API consumers, or logs.

Practical Rules

• Use messages for user-visible feedback.
• Use logs for diagnostics.
• Always release locks in a finally block.
• Use short, package-specific lock keys.
• Keep error codes documented in the package when they are part of public behavior.