Improve comments across Personalization Tags classes

[MAILPOET-6328]

packages/php/email-editor/src/Engine/PersonalizationTags/class-html-tag-processor.php

@@ -1,6 +1,6 @@
 <?php
 /**
- * This file is part of the MailPoet plugin.
+ * This file is part of the MailPoet Email Editor package.
  *
  * @package MailPoet\EmailEditor
  */
@@ -15,10 +15,13 @@ use WP_HTML_Text_Replacement;
 /**
  * Class based on WP_HTML_Tag_Processor which is extended to replace
  * tokens with their values in the email content.
+ *
+ * This class was inspired by a concept from the WordPress core,
+ * which could help us to avoid refactoring in the future.
  */
 class HTML_Tag_Processor extends WP_HTML_Tag_Processor {
 	/**
-	 * List of deferred updates.
+	 * List of deferred updates which will be replaced after calling flush_updates().
 	 *
 	 * @var WP_HTML_Text_Replacement[]
 	 */

packages/php/email-editor/src/Engine/PersonalizationTags/class-personalization-tags-registry.php

@@ -1,6 +1,6 @@
 <?php
 /**
- * This file is part of the MailPoet plugin.
+ * This file is part of the MailPoet Email Editor package.
  *
  * @package MailPoet\EmailEditor
  */
@@ -23,6 +23,7 @@ class Personalization_Tags_Registry {
 
 	/**
 	 * Initialize the personalization tags registry.
+	 * This method should be called only once.
 	 *
 	 * @return void
 	 */
@@ -31,7 +32,7 @@ class Personalization_Tags_Registry {
 	}
 
 	/**
-	 * Register a new personalization tag.
+	 * Register a new personalization instance in the registry.
 	 *
 	 * @param Personalization_Tag $tag The personalization tag to register.
 	 * @return void
@@ -45,7 +46,8 @@ class Personalization_Tags_Registry {
 	}
 
 	/**
-	 * Retrieve a personalization tag by its tag.
+	 * Retrieve a personalization tag by its token.
+	 * Example: get_by_token( 'user:first_name' ) will return the instance of Personalization_Tag with identical token.
 	 *
 	 * @param string $token The token of the personalization tag.
 	 * @return Personalization_Tag|null The array data or null if not found.

packages/php/email-editor/src/Engine/class-email-editor.php

@@ -63,9 +63,9 @@ class Email_Editor {
 	private Send_Preview_Email $send_preview_email;
 
 	/**
-	 * Property for Personalization_Tags_Controller instance.
+	 * Property for Personalization_Tags_Controller that allows initializing personalization tags.
 	 *
-	 * @var Personalization_Tags_Registry Personalization tags controller.
+	 * @var Personalization_Tags_Registry Personalization tags registry.
 	 */
 	private Personalization_Tags_Registry $personalization_tags_registry;
 
@@ -78,7 +78,7 @@ class Email_Editor {
 	 * @param Patterns                      $patterns Patterns.
 	 * @param Settings_Controller           $settings_controller Settings controller.
 	 * @param Send_Preview_Email            $send_preview_email Preview email controller.
-	 * @param Personalization_Tags_Registry $personalization_tags_controller Preview email controller.
+	 * @param Personalization_Tags_Registry $personalization_tags_controller Personalization tags registry that allows initializing personalization tags.
 	 */
 	public function __construct(
 		Email_Api_Controller $email_api_controller,

packages/php/email-editor/src/Engine/class-personalizer.php

@@ -1,6 +1,6 @@
 <?php
 /**
- * This file is part of the MailPoet plugin.
+ * This file is part of the MailPoet Email Editor package.
  *
  * @package MailPoet\EmailEditor
  */
@@ -25,9 +25,19 @@ class Personalizer {
 	private Personalization_Tags_Registry $tags_registry;
 
 	/**
-	 * Context for the personalization tags.
+	 * Context for personalization tags.
 	 *
-	 * @var array
+	 * The `context` is an associative array containing recipient-specific or
+	 * campaign-specific data. This data is used to resolve personalization tags
+	 * and provide input for tag callbacks during email content processing.
+	 *
+	 * Example context:
+	 * array(
+	 *     'recipient_email' => 'john@example.com', // Recipient's email
+	 *     'custom_field'    => 'Special Value',    // Custom campaign-specific data
+	 * )
+	 *
+	 * @var array<string, mixed>
 	 */
 	private array $context;
 
@@ -42,9 +52,17 @@ class Personalizer {
 	}
 
 	/**
-	 * Set the context for the personalization.
+	 * Set the context for personalization.
 	 *
-	 * @param array $context The context to set.
+	 * The `context` provides data required for resolving personalization tags
+	 * during content processing. This method allows the context to be set or updated.
+	 *
+	 * Example usage:
+	 * $personalizer->set_context(array(
+	 *     'recipient_email' => 'john@example.com',
+	 * ));
+	 *
+	 * @param array<string, mixed> $context Associative array containing personalization data.
 	 */
 	public function set_context( array $context ) {
 		$this->context = $context;
@@ -61,7 +79,7 @@ class Personalizer {
 		while ( $content_processor->next_token() ) {
 			if ( $content_processor->get_token_type() === '#comment' ) {
 				$token = $this->parse_token( $content_processor->get_modifiable_text() );
-				$tag   = $this->tags_registry->get_by_token( $token['tag'] );
+				$tag   = $this->tags_registry->get_by_token( $token['token'] );
 				if ( ! $tag ) {
 					continue;
 				}
@@ -81,20 +99,20 @@ class Personalizer {
 	}
 
 	/**
-	 * Parse a personalization tag token.
+	 * Parse a personalization tag to the token and attributes.
 	 *
 	 * @param string $token The token to parse.
-	 * @return array{tag: string, attributes: array} The parsed token.
+	 * @return array{token: string, attributes: array} The parsed token.
 	 */
 	private function parse_token( string $token ): array {
 		$result = array(
-			'tag'       => '',
+			'token'     => '',
 			'arguments' => array(),
 		);
 
 		// Step 1: Separate the tag and attributes.
 		if ( preg_match( '/^([a-zA-Z0-9\-\/]+)\s*(.*)$/', trim( $token ), $matches ) ) {
-			$result['tag']     = $matches[1]; // The tag part (e.g., "mailpoet/subscriber-firstname").
+			$result['token']   = $matches[1]; // The tag part (e.g., "mailpoet/subscriber-firstname").
 			$attributes_string = $matches[2]; // The attributes part (e.g., 'default="subscriber"').
 
 			// Step 2: Extract attributes from the attribute string.

packages/php/email-editor/tests/integration/Engine/PersonalizationTags/HTML_Tag_Processor_Test.php

@@ -1,6 +1,6 @@
 <?php
 /**
- * This file is part of the MailPoet plugin.
+ * This file is part of the MailPoet Email Editor package.
  *
  * @package MailPoet\EmailEditor
  */

packages/php/email-editor/tests/integration/Engine/Personalizer_Test.php

@@ -1,6 +1,6 @@
 <?php
 /**
- * This file is part of the MailPoet plugin.
+ * This file is part of the MailPoet Email Editor package.
  *
  * @package MailPoet\EmailEditor
  */

packages/php/email-editor/tests/unit/Engine/PersonalizationTags/Personalization_Tags_Registry_Test.php

@@ -1,6 +1,6 @@
 <?php
 /**
- * This file is part of the MailPoet plugin.
+ * This file is part of the MailPoet Email Editor package.
  *
  * @package MailPoet\EmailEditor
  */