Add: Controls for publishing WordPress comments to Bluesky (#199)

Author: pfefferle

.github/changelog/add-outgoing-reactions-controls

@@ -0,0 +1,4 @@
+Significance: minor
+Type: added
+
+Add a setting — and a filter for plugins — to keep WordPress comment changes from being published to Bluesky while leaving incoming reactions enabled.

docs/developer-docs.md

@@ -8,6 +8,7 @@
 - [Extending Content Formats](#extending-content-formats)
 - [Custom Post Type Support](#custom-post-type-support)
 - [Publishing Programmatically](#publishing-programmatically)
+- [Outgoing Comment Controls](#outgoing-comment-controls)
 - [Token Encryption](#token-encryption)
 - [Templates and Admin UI](#templates-and-admin-ui)
 
@@ -352,6 +353,38 @@ landing page, so their `source_url` is intentionally empty and
 Integrations can react to each via
 [`atmosphere_reaction_synced`](#public-hooks).
 
+## Outgoing Comment Controls
+
+ATmosphere publishes eligible WordPress comments as Bluesky replies.
+Administrators can turn these writes off under
+**Settings → ATmosphere → Reactions** ("Outgoing replies"). The underlying
+`atmosphere_publish_comments` option defaults to enabled so existing sites
+keep their current behavior.
+
+Host plugins can enforce the boundary with a behavior filter that runs
+*after* the stored preference and has the final say:
+
+```php
+add_filter( 'atmosphere_should_publish_comments', '__return_false' );
+```
+
+The override is on effective behavior, not the option — the saved
+preference stays untouched (and the settings form keeps editing it), so
+removing the filter restores whatever the site had configured. Because the
+filter runs last, it can also force the lane back *on* while the option is
+off.
+
+While comment publishing is disabled, ATmosphere does not create, update,
+or delete Bluesky reply records for WordPress comments, including work that
+was already queued in WP-Cron. Replies that were previously published
+remain unchanged. Post and standard.site document publishing continues
+normally, as does inbound syncing of Bluesky replies, likes, and reposts.
+
+Direct calls to the `Publisher` comment methods return a WP_Error with the
+`atmosphere_comment_publishing_disabled` code while the control is off. Use
+`\Atmosphere\is_comment_publishing_enabled()` when an integration needs to inspect
+the effective state.
+
 ## Token Encryption
 
 OAuth tokens are encrypted at rest with a key derived from the site's `AUTH_KEY` and `AUTH_SALT`. That keeps the key out of the database, but it also means the stored tokens become unreadable when the salts change — after a migration, a regenerated `wp-config.php`, or a security plugin that rotates salts on a schedule. ATmosphere detects that case, flags the connection, and asks the user to reconnect.

docs/php-coding-standards.md

@@ -225,6 +225,7 @@ use function Atmosphere\is_connected;
 ```php
 \apply_filters( 'atmosphere_syncable_post_types',         array( 'post' ) );
 \apply_filters( 'atmosphere_should_publish_comment',      $bool, $comment );
+\apply_filters( 'atmosphere_should_publish_comments',     $bool ); // Feature switch for publishing WP comments to Bluesky; runs after the stored setting, final say. NOT the per-comment `_comment` filter above.
 \apply_filters( 'atmosphere_should_sync_reply',           $bool, $notification, $post_id );
 \apply_filters( 'atmosphere_backfill_query_chunk_size',   500 );
 \apply_filters( 'atmosphere_publish_retry_delays',        array( 60, 300, 900 ) ); // Backoff ladder for failed publish/update cron workers; length = retry budget; empty array disables retries.

includes/class-atmosphere.php

@@ -981,21 +981,21 @@ private static function clear_visibility_cleanup_marker( \WP_Post $post ): void
 	/**
 	 * Schedule AT Protocol record deletion before a post is permanently deleted.
 	 *
-	 * Captures every Bluesky TID (post root + thread replies + outbound
-	 * comment replies) and the document TID from post meta, then
-	 * schedules a single async batch delete via cron. Thread-strategy
-	 * posts read every TID from `Post::META_THREAD_RECORDS`; outbound
-	 * comment replies come from `Publisher::collect_published_comment_tids()`.
+	 * Captures every Bluesky post TID (root + thread replies) and the
+	 * document TID from post meta, then schedules an async batch delete
+	 * via cron. When comment publishing is enabled, outbound comment
+	 * replies are also collected through
+	 * `Publisher::collect_published_comment_tids()`.
 	 *
-	 * Comment TIDs must be collected here, while WP still has the
+	 * Enabled comment TIDs must be collected here, while WP still has the
 	 * comment rows: `wp_delete_post( $id, true )` fires `before_delete_post`
 	 * first and only then iterates child comments, so this is the last
 	 * opportunity to read them.
 	 *
-	 * The trash path (`Publisher::delete_post()`) already cascades
-	 * comment deletes; this keeps the permanent-delete path symmetric
-	 * so unpublishing or hard-deleting a post does not orphan its
-	 * outbound replies on the PDS.
+	 * While comment publishing is enabled, the trash path
+	 * (`Publisher::delete_post()`) also cascades comment deletes. This
+	 * keeps permanent deletion symmetric. When they are disabled, both
+	 * paths preserve existing outbound replies instead.
 	 *
 	 * @param int $post_id Post ID being deleted.
 	 */
@@ -1038,10 +1038,9 @@ public function on_before_delete( int $post_id ): void {
 
 		$doc_tid = (string) \get_post_meta( $post_id, Transformer\Document::META_TID, true );
 
-		$comment_tids = \array_column(
-			Publisher::collect_published_comment_tids( $post_id ),
-			'tid'
-		);
+		$comment_tids = is_comment_publishing_enabled()
+			? \array_column( Publisher::collect_published_comment_tids( $post_id ), 'tid' )
+			: array();
 
 		if ( ! empty( $bsky_tids ) || '' !== $doc_tid || ! empty( $comment_tids ) ) {
 			\wp_schedule_single_event(
@@ -1135,7 +1134,7 @@ public function on_comment_edit( int $comment_id ): void {
 	 * @param int $comment_id Comment ID.
 	 */
 	public function on_comment_before_delete( int $comment_id ): void {
-		if ( ! is_connected() ) {
+		if ( ! is_comment_publishing_enabled() || ! is_connected() ) {
 			return;
 		}
 
@@ -1168,6 +1167,15 @@ public function on_comment_before_delete( int $comment_id ): void {
 	 * @return bool
 	 */
 	public static function should_publish_comment( \WP_Comment $comment ): bool {
+		/*
+		 * Checked first: a disabled site skips the eligibility work (which
+		 * busts the parent post's cache on every comment event) and the
+		 * per-comment filter entirely.
+		 */
+		if ( ! is_comment_publishing_enabled() ) {
+			return false;
+		}
+
 		$should = self::is_comment_eligible( $comment );
 
 		/**
@@ -1273,7 +1281,7 @@ private function schedule_comment_publish( \WP_Comment $comment ): void {
 	 * @param \WP_Comment $comment Comment object.
 	 */
 	private function schedule_comment_delete( \WP_Comment $comment ): void {
-		if ( ! is_connected() ) {
+		if ( ! is_comment_publishing_enabled() || ! is_connected() ) {
 			return;
 		}
 
@@ -1686,6 +1694,10 @@ static function (): void {
 		\add_action(
 			'atmosphere_delete_records',
 			static function ( $bsky_tids, string $doc_tid, $comment_tids = array() ): void {
+				/*
+				 * delete_post_by_tids() drops the comment TIDs itself when
+				 * comment publishing is disabled at execution time.
+				 */
 				$comment_tids = \is_array( $comment_tids ) ? $comment_tids : array();
 				$result       = Publisher::delete_post_by_tids( $bsky_tids, $doc_tid, $comment_tids );
 
@@ -1784,6 +1796,10 @@ static function ( int $comment_id ): void {
 		\add_action(
 			'atmosphere_delete_comment',
 			static function ( int $comment_id ): void {
+				if ( ! is_comment_publishing_enabled() ) {
+					return;
+				}
+
 				$comment = \get_comment( $comment_id );
 				if ( ! $comment instanceof \WP_Comment ) {
 					return;
@@ -1802,7 +1818,7 @@ static function ( int $comment_id ): void {
 		\add_action(
 			'atmosphere_delete_comment_record',
 			static function ( string $tid ): void {
-				if ( '' === $tid ) {
+				if ( ! is_comment_publishing_enabled() || '' === $tid ) {
 					return;
 				}
 
@@ -2208,6 +2224,15 @@ private static function is_transient_publish_error( \WP_Error $error ): bool {
 	 * @param int $comment_id Comment ID just published.
 	 */
 	private static function reconcile_comment_after_publish( int $comment_id ): void {
+		/*
+		 * A switch flipped while applyWrites was in flight cannot undo the
+		 * completed request. Keep the returned record metadata intact and do
+		 * not enqueue a compensating delete while outgoing writes are off.
+		 */
+		if ( ! is_comment_publishing_enabled() ) {
+			return;
+		}
+
 		/*
 		 * Drop the in-process `WP_Comment` cache so a concurrent web
 		 * request that just unapproved or deleted this comment is

includes/class-options.php

@@ -50,32 +50,47 @@ public static function register_settings(): void {
 			'atmosphere',
 			'atmosphere_auto_publish',
 			array(
-				'type'         => 'boolean',
-				'description'  => 'Whether new posts are automatically published to AT Protocol.',
-				'default'      => '1',
-				'show_in_rest' => true,
+				'type'              => 'boolean',
+				'description'       => 'Whether new posts are automatically published to AT Protocol.',
+				'default'           => '1',
+				'show_in_rest'      => true,
+				'sanitize_callback' => array( Sanitize::class, 'boolean_option' ),
+			)
+		);
+
+		\register_setting(
+			'atmosphere',
+			'atmosphere_publish_comments',
+			array(
+				'type'              => 'boolean',
+				'description'       => 'Whether eligible WordPress comments are published as Bluesky replies.',
+				'default'           => '1',
+				'show_in_rest'      => true,
+				'sanitize_callback' => array( Sanitize::class, 'boolean_option' ),
 			)
 		);
 
 		\register_setting(
 			'atmosphere',
 			'atmosphere_sync_reactions',
 			array(
-				'type'         => 'boolean',
-				'description'  => 'Whether Bluesky likes and reposts are imported.',
-				'default'      => '1',
-				'show_in_rest' => true,
+				'type'              => 'boolean',
+				'description'       => 'Whether Bluesky likes and reposts are imported.',
+				'default'           => '1',
+				'show_in_rest'      => true,
+				'sanitize_callback' => array( Sanitize::class, 'boolean_option' ),
 			)
 		);
 
 		\register_setting(
 			'atmosphere',
 			'atmosphere_sync_replies',
 			array(
-				'type'         => 'boolean',
-				'description'  => 'Whether Bluesky replies are imported as comments.',
-				'default'      => '1',
-				'show_in_rest' => true,
+				'type'              => 'boolean',
+				'description'       => 'Whether Bluesky replies are imported as comments.',
+				'default'           => '1',
+				'show_in_rest'      => true,
+				'sanitize_callback' => array( Sanitize::class, 'boolean_option' ),
 			)
 		);