User Updater Service Documentation in Discourse App

Produce API documentation for:

https://github.com/discourse/discourse/blob/main/app/services/user_updater.rb

GitHub file content

Retrieved content of app/services/user_updater.rb from discourse/discourse@main

UserUpdater Class Documentation

The UserUpdater class in Discourse is designed to encapsulate all the logic needed to update user-related attributes, preferences, and associations within the Discourse platform. This class facilitates the application of various user attributes through a centralized service layer.

Overview

The UserUpdater class allows for the updating of a range of user attributes from basic profile information to user preferences and notification settings. It handles complex logic such as theme updates, category and tag watching/tracking, and ensuring that changes are compliant with system settings and permissions.

Key Components

Constants

• CATEGORY_IDS: Maps user setting attributes related to category notifications (e.g., watched categories, tracked categories) to their corresponding notification levels.
• TAG_NAMES: Similar to CATEGORY_IDS, maps user setting attributes related to tag notifications to their notification levels.
• OPTION_ATTR: An array listing various user options that can be updated, including email settings, theme settings, and UI preferences.

Initialization

The class is initialized with two parameters:

• actor: The user performing the update action.
• user: The user being updated.

Methods

• initialize(actor, user): Constructor for creating an instance of the UserUpdater service.
• update(attributes = {}): Main method for applying updates to the user. Accepts a hash of attributes to be updated.
  • Handles profile updates such as bio, location, and website.
  • Allows updating user preferences related to email, themes, text size, and more.
  • Manages notification preferences for categories and tags.
  • Optionally updates custom fields and user status.

Usage Scenario

The update method is the primary interface for making changes to a user’s settings and preferences. It requires a hash map of attributes that represent the changes to be applied. The service then validates and applies these changes within the constraints of the current system settings and the user’s permissions.

For example, if a user wants to change their email digest preference and their list of watched tags, the calling code would use the update method with the respective attributes:

attributes = {
  email_digests: false,
  watched_tags: 'tag1,tag2'
}
user_updater = UserUpdater.new(actor_user, target_user)
user_updater.update(attributes)

This system allows for a flexible and centralized way of handling user updates, ensuring consistency and adherence to the platform’s rules and permissions.

Important Considerations

• Permission Checks: Updates are subject to permissions checks, ensuring that the actor user has the necessary rights to make the requested changes.
• Discourse Connect: Special handling is applied for users managed through Discourse Connect to ensure that external control over user profiles is respected according to the site settings.
• User Notification Schedule: Manages user-specific notification schedules, allowing users to define when they prefer to receive notifications.
• Event Triggering: Triggers various events within Discourse, enabling plugins or other parts of the application to react to user updates.

This service is a critical component of the Discourse platform, offering a comprehensive and secure approach to managing user data and preferences.