Logger Message Guidelines

Write clear, user-friendly messages for Simple History event logs.

Core Principle: Active Voice

Write as if someone is telling you what they just did.

✅ DO                          ❌ DON'T
─────────────────────────────────────────────
Activated plugin              Plugin was activated
Created menu                  Menu has been created
Updated settings              Settings were updated
Published post                Post has been published

In Logger Classes

public function getInfo() {
    return [
        'messages' => [
            'plugin_activated' => __( 'Activated plugin', 'simple-history' ),
            'plugin_deactivated' => __( 'Deactivated plugin', 'simple-history' ),
            'post_updated' => __( 'Updated post "{post_title}"', 'simple-history' ),
        ],
    ];
}

Message Key Uniqueness

Keys must be globally unique across all loggers (used as RFC 5424 MSGID).

// ✅ Good - descriptive prefix
'plugin_activated', 'theme_switched', 'user_logged_in'

// ❌ Bad - too generic
'activated', 'updated', 'deleted'

Verify uniqueness: grep -r "'your_key'" loggers/

Common Verbs

• Create: Created, Added, Generated
• Modify: Updated, Changed, Edited
• Delete: Deleted, Removed, Trashed
• Toggle: Activated, Deactivated, Enabled, Disabled

Avoid

• ❌ "was [verb]" - passive
• ❌ "has been [verb]" - passive
• ❌ Technical jargon users won't understand

Context Key Naming

Prefix all context keys with the entity name to avoid collisions and keep keys self-documenting.

// ✅ Good - prefixed with entity
'plugin_name', 'plugin_current_version', 'theme_new_version'
'site_health_status', 'site_health_label', 'site_health_badge_label'

// ❌ Bad - too generic
'test', 'label', 'status', 'name', 'version'

Event Details Output

Use the Event Details API for get_log_row_details_output(). Never build raw HTML with SimpleHistoryLogitem__keyValueTable.

use Simple_History\Event_Details\Event_Details_Group;
use Simple_History\Event_Details\Event_Details_Group_Table_Formatter;
use Simple_History\Event_Details\Event_Details_Item;

public function get_log_row_details_output( $row ) {
    $group = new Event_Details_Group();
    $group->set_formatter( new Event_Details_Group_Table_Formatter() );
    $group->add_items(
        array(
            // Read value directly from context key.
            new Event_Details_Item( 'status', __( 'Status', 'simple-history' ) ),
            // Read new/prev pair from context (looks for key_new and key_prev).
            new Event_Details_Item( array( 'setting_name' ), __( 'Setting', 'simple-history' ) ),
        )
    );
    return $group;
}

Formatters:

• Event_Details_Group_Table_Formatter — key-value table (default)
• Event_Details_Group_Diff_Table_Formatter — before/after with diffs
• Event_Details_Group_Inline_Formatter — compact inline text

Manual values (when context keys don't match conventions):

( new Event_Details_Item( null, __( 'Label', 'simple-history' ) ) )
    ->set_new_value( $value )

See docs/architecture/event-details.md for full API reference.

Detailed Resources

• examples.md - Extensive examples across all WordPress contexts
• integration.md - Complete logger class implementation