Changeset 3771693 for joinotify/trunk/admin/src/Core/Workflow_Processor.php

Timestamp:

10/28/2026 09:22:17 PM (7 days ago)

Author:

meumouse

Message:

Release 2.6.0

File:

• joinotify/trunk/admin/src/Core/Workflow_Processor.php (modified) (5 diffs)

joinotify/trunk/admin/src/Core/Workflow_Processor.php

@@ -1600 +1600 @@
      * The builder stores one entry per template variable, each carrying where it
      * belongs (`component`, and `sub_type`/`index` for button variables) and the
-     * Joinotify placeholder that fills it. Meta wants those grouped per
-     * component, with lowercase types, and button parameters split by button
-     * index.
+     * Joinotify placeholder that fills it. The placeholders are resolved here;
+     * packing the values into Meta's dialect is components_from_values().
+     *
+     * @since 2.3.0
+     * @version 2.6.0
+     * @param array  $variables | Variable map stored on the action.
+     * @param array  $payload | Runtime trigger payload.
+     * @param string $mode | Placeholder resolution mode ('production' or 'sandbox').
+     * @return array
+     */
+    public static function build_template_components( $variables, $payload, $mode = 'production' ) {
+        if ( ! is_array( $variables ) || empty( $variables ) ) {
+            return array();
+        }
+
+        foreach ( $variables as $position => $variable ) {
+            if ( ! is_array( $variable ) ) {
+                continue;
+            }
+
+            $raw = (string) ( $variable['value'] ?? '' );
+
+            $variables[ $position ]['value'] = 'sandbox' === $mode
+                ? Placeholders::replace_placeholders( $raw, $payload, 'sandbox' )
+                : joinotify_prepare_message( $raw, $payload );
+        }
+
+        return self::components_from_values( $variables );
+    }
+
+
+    /**
+     * Pack variables whose values are already resolved into Meta's `components` payload.
+     *
+     * Meta wants the values grouped per component, with lowercase types, and
+     * button parameters split by button index. Nothing is resolved here: a value
+     * holding `{{ ... }}` goes out as written, which is what lets another plugin
+     * hand over values it resolved with its own placeholders.
      *
      * Header and body parameters of a template created with named variables
@@ -1609 +1644 @@
      * without it, as do button parameters.
      *
-     * Every value travels as a `text` parameter, numbers included: Meta has no
-     * numeric text type, and a digit string is what it expects for an order
-     * number or a count.
-     *
-     * @since 2.3.0
-     * @version 2.4.2
-     * @param array  $variables | Variable map stored on the action.
-     * @param array  $payload | Runtime trigger payload.
-     * @param string $mode | Placeholder resolution mode ('production' or 'sandbox').
+     * Every text value travels as a `text` parameter, numbers included: Meta has
+     * no numeric text type, and a digit string is what it expects for an order
+     * number or a count. A header variable whose `format` is `image`, `video` or
+     * `document` is a media header instead: its value is the file link, or the
+     * id of a file already uploaded to Meta, and a document also carries the
+     * file name read from the link. A `copy_code` button carries its value as
+     * the coupon. The button of an AUTHENTICATION template (`format` `otp`)
+     * repeats the login code, so when it is left empty it takes the first body
+     * value, which is where that code lives.
+     *
+     * A location header is built from its four variables (`format` `location`,
+     * keyed `latitude`, `longitude`, `name`, `address`). A `limited_time_offer`
+     * variable holds when the offer expires — a date, a Unix timestamp in
+     * seconds or milliseconds, or a relative time such as `+2 days` — and goes
+     * out in milliseconds. Variables with a `card` of 0 or more belong to that
+     * carousel card: each card is packed the same way and they all go out in
+     * one `carousel` component, where a quick-reply button left empty sends a
+     * payload naming its card and button.
+     *
+     * @since 2.6.0
+     * @param array $variables | One entry per variable: component, sub_type, index, key, format, card and the resolved value.
      * @return array
      */
-    public static function build_template_components( $variables, $payload, $mode = 'production' ) {
+    public static function components_from_values( $variables ) {
         if ( ! is_array( $variables ) || empty( $variables ) ) {
             return array();
         }
 
-        $grouped = array();
+        $top_level = array();
+        $cards = array();
 
         foreach ( $variables as $variable ) {
@@ -1632 +1680 @@
             }
 
+            $card = (int) ( $variable['card'] ?? -1 );
+
+            if ( $card >= 0 ) {
+                $cards[ $card ][] = $variable;
+            } else {
+                $top_level[] = $variable;
+            }
+        }
+
+        $components = self::group_component_values( $top_level );
+
+        if ( ! empty( $cards ) ) {
+            ksort( $cards );
+            $carousel = array();
+
+            foreach ( $cards as $card_index => $card_variables ) {
+                $carousel[] = array(
+                    'card_index' => (int) $card_index,
+                    'components' => self::group_component_values( $card_variables, (int) $card_index ),
+                );
+            }
+
+            $components[] = array(
+                'type' => 'carousel',
+                'cards' => $carousel,
+            );
+        }
+
+        return $components;
+    }
+
+
+    /**
+     * Group the resolved values of one message (or one carousel card) per component.
+     *
+     * @since 2.6.0
+     * @param array $variables | Variables with their resolved value.
+     * @param int   $card | Carousel card position, -1 outside a carousel.
+     * @return array
+     */
+    protected static function group_component_values( $variables, $card = -1 ) {
+        $grouped = array();
+        $first_body = '';
+
+        foreach ( $variables as $variable ) {
+            if ( 'body' === strtolower( (string) ( $variable['component'] ?? 'body' ) ) ) {
+                $first_body = is_scalar( $variable['value'] ?? '' ) ? (string) ( $variable['value'] ?? '' ) : '';
+
+                break;
+            }
+        }
+
+        foreach ( $variables as $variable ) {
             $component = strtolower( (string) ( $variable['component'] ?? 'body' ) );
 
-            if ( ! in_array( $component, array( 'header', 'body', 'button' ), true ) ) {
+            if ( ! in_array( $component, array( 'header', 'body', 'button', 'limited_time_offer' ), true ) ) {
                 continue;
             }
 
-            $raw = (string) ( $variable['value'] ?? '' );
-            $value = 'sandbox' === $mode
-                ? Placeholders::replace_placeholders( $raw, $payload, 'sandbox' )
-                : joinotify_prepare_message( $raw, $payload );
+            $value = is_scalar( $variable['value'] ?? '' ) ? (string) ( $variable['value'] ?? '' ) : '';
 
             // Buttons are addressed one by one, so they cannot share a bucket.
@@ -1660 +1758 @@
             }
 
+            $format = strtolower( (string) ( $variable['format'] ?? '' ) );
+
+            if ( 'header' === $component && in_array( $format, array( 'image', 'video', 'document' ), true ) ) {
+                $grouped[ $bucket ]['parameters'][] = array(
+                    'type' => $format,
+                    $format => self::media_header_object( $format, $value ),
+                );
+
+                continue;
+            }
+
+            // The four location variables fill one parameter between them.
+            if ( 'header' === $component && 'location' === $format ) {
+                $field = strtolower( trim( (string) ( $variable['key'] ?? '' ) ) );
+
+                if ( ! in_array( $field, array( 'latitude', 'longitude', 'name', 'address' ), true ) ) {
+                    continue;
+                }
+
+                $position = null;
+
+                foreach ( $grouped[ $bucket ]['parameters'] as $existing => $parameter ) {
+                    if ( 'location' === ( $parameter['type'] ?? '' ) ) {
+                        $position = $existing;
+
+                        break;
+                    }
+                }
+
+                if ( null === $position ) {
+                    $grouped[ $bucket ]['parameters'][] = array(
+                        'type' => 'location',
+                        'location' => array(),
+                    );
+                    $position = array_key_last( $grouped[ $bucket ]['parameters'] );
+                }
+
+                $text = self::prepare_template_text( $value );
+
+                // A decimal comma (-23,55) is what many sites store; Meta wants a point.
+                if ( in_array( $field, array( 'latitude', 'longitude' ), true ) ) {
+                    $text = str_replace( ',', '.', $text );
+                }
+
+                // Name and address are optional; an empty one is left out.
+                if ( '' !== $text ) {
+                    $grouped[ $bucket ]['parameters'][ $position ]['location'][ $field ] = $text;
+                }
+
+                continue;
+            }
+
+            if ( 'limited_time_offer' === $component ) {
+                $expiration = self::expiration_ms( $value );
+
+                // A missing or unreadable date would only earn a refusal.
+                if ( null !== $expiration ) {
+                    $grouped[ $bucket ]['parameters'][] = array(
+                        'type' => 'limited_time_offer',
+                        'limited_time_offer' => array( 'expiration_time_ms' => $expiration ),
+                    );
+                }
+
+                continue;
+            }
+
+            if ( 'button' === $component && 'copy_code' === ( $grouped[ $bucket ]['sub_type'] ?? '' ) ) {
+                $grouped[ $bucket ]['parameters'][] = array(
+                    'type' => 'coupon_code',
+                    'coupon_code' => self::prepare_template_text( $value ),
+                );
+
+                continue;
+            }
+
+            if ( 'button' === $component && 'quick_reply' === ( $grouped[ $bucket ]['sub_type'] ?? '' ) ) {
+                $payload = self::prepare_template_text( $value );
+
+                $grouped[ $bucket ]['parameters'][] = array(
+                    'type' => 'payload',
+                    'payload' => '' !== $payload ? $payload : sprintf( 'card_%d_button_%d', max( 0, $card ), (int) ( $variable['index'] ?? 0 ) ),
+                );
+
+                continue;
+            }
+
+            if ( 'otp' === $format && '' === trim( $value ) ) {
+                $value = $first_body;
+            }
+
             $parameter = array(
                 'type' => 'text',
@@ -1677 +1865 @@
         }
 
-        return array_values( $grouped );
+        // A component left without a parameter (an offer with no readable
+        // date) is dropped rather than sent empty.
+        return array_values( array_filter( $grouped, fn( $component ) => ! empty( $component['parameters'] ) ) );
+    }
+
+
+    /**
+     * Read when a limited-time offer expires, in the milliseconds Meta expects.
+     *
+     * Digits are a Unix timestamp: in milliseconds from 13 digits on, in
+     * seconds below. Anything else is read as a date or a relative time in the
+     * site's timezone.
+     *
+     * @since 2.6.0
+     * @param string $value | Resolved expiration.
+     * @return int|float|null Milliseconds since the epoch, or null when it cannot be read.
+     */
+    protected static function expiration_ms( $value ) {
+        $value = trim( (string) $value );
+
+        if ( '' === $value ) {
+            return null;
+        }
+
+        if ( preg_match( '/^\d+$/', $value ) ) {
+            $milliseconds = strlen( $value ) >= 13 ? (float) $value : (float) $value * 1000;
+        } else {
+            try {
+                $date = new \DateTimeImmutable( $value, wp_timezone() );
+            } catch ( \Exception $e ) {
+                return null;
+            }
+
+            $milliseconds = (float) $date->getTimestamp() * 1000;
+        }
+
+        // Milliseconds outgrow a 32-bit integer; only a 64-bit build sends an int.
+        return PHP_INT_SIZE >= 8 ? (int) $milliseconds : $milliseconds;
+    }
+
+
+    /**
+     * Describe the file of a media header the way Meta expects it.
+     *
+     * A value made of digits only is the id of a file uploaded to Meta; anything
+     * else is a link. A document sent by link also carries the file name, which
+     * is what the recipient sees on the attachment.
+     *
+     * @since 2.6.0
+     * @param string $format | image, video or document.
+     * @param string $value | File link or Meta media id.
+     * @return array
+     */
+    protected static function media_header_object( $format, $value ) {
+        $value = trim( (string) $value );
+
+        if ( preg_match( '/^\d+$/', $value ) ) {
+            return array( 'id' => $value );
+        }
+
+        $media = array( 'link' => $value );
+
+        if ( 'document' === $format ) {
+            $path = (string) wp_parse_url( $value, PHP_URL_PATH );
+            $filename = '' !== $path ? rawurldecode( basename( $path ) ) : '';
+
+            if ( '' !== $filename ) {
+                $media['filename'] = $filename;
+            }
+        }
+
+        return $media;
     }