README

A lightweight WordPress library for working with comments and comment metadata. Provides clean APIs for comment operations, search functionality, and value/label formatting perfect for forms and admin interfaces.

Features

• 🎯 Clean API: WordPress-style snake_case methods with consistent interfaces
• 🔍 Built-in Search: Comment search with value/label formatting
• 📋 Form-Ready Options: Perfect value/label arrays for selects and forms
• 🌳 Hierarchical Support: Parent-child comment relationships
• 🔗 Status Management: Easy comment approval, spam, and trash handling
• 📊 Meta Operations: Simple comment meta handling with type safety
• 🚀 Bulk Operations: Process multiple comments efficiently

Requirements

• PHP 7.4 or later
• WordPress 5.0 or later

Installation

composer require arraypress/wp-comment-utils

Basic Usage

Working with Single Comments

use ArrayPress\CommentUtils\Comment;

// Get comment by ID
$comment = Comment::get( 123 );

// Check if comment exists
if ( Comment::exists( 123 ) ) {
	// Comment exists
}

// Get comment content
$content     = Comment::get_content( 123 );
$raw_content = Comment::get_content( 123, true );

// Check comment status
$status      = Comment::get_status( 123 ); // 'approved', 'pending', 'spam', 'trash'
$is_approved = Comment::is_approved( 123 );
$is_spam     = Comment::is_spam( 123 );

// Get author details
$author = Comment::get_author_details( 123 );
// Returns: ['name' => 'John', 'email' => 'john@example.com', 'url' => '...', 'ip' => '...']

$user = Comment::get_author_user( 123 ); // WP_User object if registered user

// Check if by registered user
if ( Comment::is_by_registered_user( 123 ) ) {
	// Comment by logged-in user
}

// Get comment hierarchy
$parent       = Comment::get_parent( 123 );
$children     = Comment::get_children( 123 );
$depth        = Comment::get_depth( 123 );
$has_children = Comment::has_children( 123 );

// Get comment dates
$date      = Comment::get_date( 123, 'Y-m-d' );
$age       = Comment::get_age( 123 ); // Days since comment
$time_diff = Comment::get_time_diff( 123 ); // "2 hours ago"

// Comment meta
$meta_value        = Comment::get_meta( 123, 'featured' );
$meta_with_default = Comment::get_meta_with_default( 123, 'rating', 5 );

// Update meta only if changed
Comment::update_meta_if_changed( 123, 'featured', true );

// Status operations
Comment::approve( 123 );
Comment::mark_as_spam( 123 );
Comment::trash( 123 );

Working with Multiple Comments

use ArrayPress\CommentUtils\Comments;

// Get multiple comments
$comments = Comments::get( [ 1, 2, 3 ] );

// Get comments by post
$post_comments = Comments::get_by_post( 456 );

// Get comments by author email
$author_comments = Comments::get_by_author_email( 'user@example.com' );

// Get comments by status
$spam_comments    = Comments::get_by_status( 'spam' );
$pending_comments = Comments::get_by_status( [ 'pending', 'hold' ] );

// Get recent comments
$recent = Comments::get_recent( 10 );

// Search comments and get options
$options = Comments::search_options( 'great post' );
// Returns: [['value' => 1, 'label' => 'This is a great post about...'], ...]

// Search comments
$search_results = Comments::search( 'wordpress' );

// Bulk operations
$results = Comments::approve( [ 1, 2, 3 ] );
$results = Comments::mark_as_spam( [ 4, 5, 6 ] );
$results = Comments::trash( [ 7, 8, 9 ] );
$results = Comments::delete( [ 10, 11, 12 ], true ); // Force delete

// Get comment counts
$counts      = Comments::get_counts(); // Site-wide
$post_counts = Comments::get_counts( 123 ); // For specific post
// Returns: ['total' => 50, 'approved' => 45, 'awaiting_moderation' => 3, 'spam' => 2, 'trash' => 0]

// Get hierarchical comments
$threaded = Comments::get_hierarchical( 456 );

// Sanitize comment IDs
$clean_ids = Comments::sanitize( [ '1', 'invalid', '3' ] );

Search Functionality

// Basic search
$comments = Comments::search( 'excellent article' );

// Search with custom args
$comments = Comments::search( 'wordpress', [
	'status'  => 'approve',
	'number'  => 5,
	'post_id' => 123
] );

// Get search results as options for forms
$options = Comments::search_options( 'helpful' );

Status Management

// Single comment status changes
Comment::approve( 123 );
Comment::mark_as_spam( 123 );
Comment::trash( 123 );

// Bulk status changes
$results = Comments::approve( [ 1, 2, 3 ] );
$results = Comments::mark_as_spam( [ 4, 5, 6 ] );
$results = Comments::trash( [ 7, 8, 9 ] );

// Check results
foreach ( $results as $comment_id => $success ) {
	if ( $success ) {
		echo "Comment {$comment_id} updated successfully";
	}
}

Key Features

• Value/Label Format: Perfect for forms and selects
• Hierarchical Support: Parent-child comment relationships
• Search Functionality: Built-in comment content search
• Status Management: Easy approval, spam, and trash handling
• Meta Operations: Simple comment meta handling
• Bulk Operations: Process multiple comments efficiently

Requirements

• PHP 7.4+
• WordPress 5.0+

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is licensed under the GPL-2.0-or-later License.

Support

• Documentation
• Issue Tracker