array( 'comment_ID' => __( 'Comment ID', 'ai-conduit' ), 'comment_post_ID' => __( 'Post ID', 'ai-conduit' ), 'user_id' => __( 'User ID', 'ai-conduit' ), 'comment_date' => __( 'Date', 'ai-conduit' ), ), 'table' => $wpdb->comments, 'meta_table' => $wpdb->commentmeta, 'meta_fk_column' => 'comment_id', 'id_column' => 'comment_ID', ); } /** * Map field keys to comments table columns. * * @since 1.0.0 * * @return array */ public function get_field_column_map(): array { return array( 'id' => 'comment_ID', 'content' => 'comment_content', 'author_name' => 'comment_author', 'author_email' => 'comment_author_email', 'author_url' => 'comment_author_url', 'date' => 'comment_date', 'status' => 'comment_approved', 'post_id' => 'comment_post_ID', 'parent' => 'comment_parent', ); } /** * Available native comment fields. * * @since 1.0.0 * * @return array */ public function get_available_fields(): array { return array( 'id' => __( 'ID', 'ai-conduit' ), 'content' => __( 'Content', 'ai-conduit' ), 'author_name' => __( 'Author Name', 'ai-conduit' ), 'author_email' => __( 'Author Email', 'ai-conduit' ), 'author_url' => __( 'Author URL', 'ai-conduit' ), 'date' => __( 'Date', 'ai-conduit' ), 'status' => __( 'Status', 'ai-conduit' ), 'post_id' => __( 'Post ID', 'ai-conduit' ), 'parent' => __( 'Parent Comment ID', 'ai-conduit' ), ); } /** * Available standard filters. * * @since 1.0.0 * * @return array */ public function get_available_filters(): array { return array( 'id' => array( 'type' => 'integer', 'description' => __( 'Fetch a specific comment by ID', 'ai-conduit' ), ), 'post_id' => array( 'type' => 'integer', 'description' => __( 'Filter by post ID. Takes priority over post_title if both are provided.', 'ai-conduit' ), ), 'post_title' => array( 'type' => 'string', 'description' => __( 'Filter by post title. Ignored if post_id is also provided.', 'ai-conduit' ), ), 'author_name' => array( 'type' => 'string', 'description' => __( 'Filter by commenter name', 'ai-conduit' ), ), 'author_email' => array( 'type' => 'string', 'description' => __( 'Filter by commenter email', 'ai-conduit' ), ), 'status' => array( 'type' => 'string', 'description' => __( 'Filter by status', 'ai-conduit' ), 'enum' => array( 'approve', 'hold', 'spam', 'trash' ), ), 'date_after' => array( 'type' => 'string', 'description' => __( 'Comments after this date (YYYY-MM-DD)', 'ai-conduit' ), ), 'date_before' => array( 'type' => 'string', 'description' => __( 'Comments before this date (YYYY-MM-DD)', 'ai-conduit' ), ), 'per_page' => array( 'type' => 'integer', 'description' => __( 'Number of results per page', 'ai-conduit' ), 'default' => 10, ), 'page' => array( 'type' => 'integer', 'description' => __( 'Page number for pagination (starts at 1)', 'ai-conduit' ), 'default' => 1, ), 'orderby' => array( 'type' => 'string', 'description' => __( 'Sort by field', 'ai-conduit' ), 'enum' => array( 'comment_date_gmt', 'comment_ID' ), ), 'order' => array( 'type' => 'string', 'description' => __( 'Sort direction', 'ai-conduit' ), 'enum' => array( 'ASC', 'DESC' ), ), ); } /** * Execute the comments query. * * @since 1.0.0 * * @param array $config The block's saved configuration. * @param array $arguments The LLM-provided input arguments. * @return array List of comment data arrays. */ public function execute( array $config, array $arguments ): array { $query_args = $this->build_query_args( $config, $arguments ); $query_args['count'] = true; $total = (int) get_comments( $query_args ); $query_args['count'] = false; $comments = get_comments( $query_args ); $selected_fields = $config['fields'] ?? array_keys( $this->get_available_fields() ); $results = array(); foreach ( $comments as $comment ) { $results[] = $this->extract_fields( $comment, $selected_fields ); } $per_page = $query_args['number']; return array( 'data' => $results, '_pagination' => array( 'page' => max( 1, absint( $arguments['page'] ?? 1 ) ), 'per_page' => $per_page, 'total' => $total, 'total_pages' => $per_page > 0 ? (int) ceil( $total / $per_page ) : 1, ), ); } /** * Build get_comments() arguments from config and LLM arguments. * * @since 1.0.0 * * @param array $config The block's saved configuration. * @param array $arguments The LLM-provided input arguments. * @return array get_comments() compatible arguments. */ private function build_query_args( array $config, array $arguments ): array { $max_per_page = $config['filters']['per_page']['max'] ?? 50; $number = max( 1, min( absint( $arguments['per_page'] ?? 10 ), $max_per_page ) ); $page = max( 1, absint( $arguments['page'] ?? 1 ) ); $query_args = array( 'number' => $number, 'offset' => ( $page - 1 ) * $number, 'orderby' => sanitize_text_field( $arguments['orderby'] ?? 'comment_date_gmt' ), 'order' => sanitize_text_field( $arguments['order'] ?? 'DESC' ), ); if ( ! empty( $arguments['id'] ) ) { $query_args['comment__in'] = array( absint( $arguments['id'] ) ); } // post_id takes priority over post_title. if ( ! empty( $arguments['post_id'] ) ) { $query_args['post_id'] = absint( $arguments['post_id'] ); } elseif ( ! empty( $arguments['post_title'] ) ) { $matched_posts = get_posts( array( 'title' => sanitize_text_field( $arguments['post_title'] ), 'post_type' => 'any', 'post_status' => 'publish', 'posts_per_page' => 1, 'fields' => 'ids', ) ); if ( ! empty( $matched_posts ) ) { $query_args['post_id'] = $matched_posts[0]; } else { // No matching post — return empty results. $query_args['comment__in'] = array( 0 ); } } if ( ! empty( $arguments['author_name'] ) ) { $query_args['search'] = sanitize_text_field( $arguments['author_name'] ); } if ( ! empty( $arguments['author_email'] ) ) { $query_args['author_email'] = sanitize_email( $arguments['author_email'] ); } $allowed_statuses = array( 'approve', 'hold', 'spam', 'trash' ); if ( ! empty( $arguments['status'] ) && in_array( $arguments['status'], $allowed_statuses, true ) ) { $query_args['status'] = $arguments['status']; } else { $query_args['status'] = 'approve'; } $date_query = array(); if ( ! empty( $arguments['date_after'] ) && $this->is_valid_date( $arguments['date_after'] ) ) { $date_query['after'] = sanitize_text_field( $arguments['date_after'] ); } if ( ! empty( $arguments['date_before'] ) && $this->is_valid_date( $arguments['date_before'] ) ) { $date_query['before'] = sanitize_text_field( $arguments['date_before'] ); } if ( ! empty( $date_query ) ) { $query_args['date_query'] = array( $date_query ); } return $query_args; } /** * Extract selected fields from a comment. * * @since 1.0.0 * * @param WP_Comment $comment The comment object. * @param array $selected_fields List of field keys to include. * @return array Associative array of field_key => value. */ private function extract_fields( WP_Comment $comment, array $selected_fields ): array { $item = array(); foreach ( $selected_fields as $field ) { switch ( $field ) { case 'id': $item['id'] = (int) $comment->comment_ID; break; case 'content': $item['content'] = wp_strip_all_tags( $comment->comment_content ); break; case 'author_name': $item['author_name'] = $comment->comment_author; break; case 'author_email': $item['author_email'] = $comment->comment_author_email; break; case 'author_url': $item['author_url'] = $comment->comment_author_url; break; case 'date': $item['date'] = $comment->comment_date; break; case 'status': $item['status'] = $comment->comment_approved; break; case 'post_id': $item['post_id'] = (int) $comment->comment_post_ID; break; case 'parent': $item['parent'] = (int) $comment->comment_parent; break; } } return $item; } }