Changeset 3790681

Timestamp:

11/08/2026 08:24:24 AM (5 hours ago)

Author:

aribhour

Message:

ew: "Document Timing" and "Document Delay (seconds)"

Location:

linet-erp-woocommerce-integration/trunk

Files:

• classes/class-wc-li-invoice-manager.php (modified) (3 diffs)
• classes/class-wc-li-settings.php (modified) (1 diff)
• readme.txt (modified) (2 diffs)
• woocommerce-linet.php (modified) (2 diffs)

linet-erp-woocommerce-integration/trunk/classes/class-wc-li-invoice-manager.php

@@ -8 +8 @@
 {
 
+  // Document Timing setting values
+  const TIMING_IMMEDIATE = 'immediate';
+  const TIMING_DELAYED = 'delayed';
+
+  const DEFAULT_DELAY = 60;
+
+  // Action Scheduler hook and group for the delayed documents
+  const QUEUE_HOOK = 'linet_auto_send_invoice';
+  const QUEUE_GROUP = 'linet';
+
+  // A queued document still pending this long after its due time is reported as stuck
+  const STUCK_GRACE = 600;
+
+  // How far back failed queued documents are reported
+  const FAILED_LOOKBACK = WEEK_IN_SECONDS;
+
+  // Order meta "_linet_auto_doc_{status}" holds the doc id the queue created for that status
+  const AUTO_DOC_META = '_linet_auto_doc_';
+
+  const NOTICE_TRANSIENT = 'wc_linet_queue_health';
+
   /**
    * @var WC_LI_Settings
@@ -49 +70 @@
         //var_dump($do_doc);
         //var_dump("woocommerce_order_status_$skey");
-        add_action("woocommerce_order_status_$skey", array($this, 'auto_send_invoice'));
-      }
+        add_action("woocommerce_order_status_$skey", array($this, 'on_order_status'), 10, 2);
+      }
+    }
+
+    // Always registered, so documents queued before the timing was switched back
+    // to immediate still get created
+    add_action(self::QUEUE_HOOK, array($this, 'run_queued_invoice'), 10, 3);
+
+    if (is_admin()) {
+      add_action('admin_notices', array($this, 'queue_health_notice'));
     }
 
@@ -285 +314 @@
 
   /**
+   * The Document Timing setting: immediate (the original behaviour) or delayed.
+   *
+   * @return string
+   */
+  public static function doc_timing()
+  {
+    $timing = get_option('wc_linet_doc_timing', self::TIMING_IMMEDIATE);
+    return self::TIMING_DELAYED === $timing ? self::TIMING_DELAYED : self::TIMING_IMMEDIATE;
+  }
+
+  /**
+   * The delay in seconds for delayed documents.
+   *
+   * @return int
+   */
+  public static function doc_delay()
+  {
+    $delay = get_option('wc_linet_doc_delay', '');
+    if ('' === $delay || !is_numeric($delay)) {
+      return self::DEFAULT_DELAY;
+    }
+    return max(0, (int) $delay);
+  }
+
+  /**
+   * True when delayed documents can actually be queued.
+   *
+   * @return bool
+   */
+  public static function queue_available()
+  {
+    return function_exists('as_schedule_single_action') && function_exists('as_has_scheduled_action');
+  }
+
+  /**
+   * Runs on every mapped woocommerce_order_status_{status} hook.
+   *
+   * Immediate timing behaves exactly like before. Delayed timing queues the
+   * document, so other plugins that set the status first and save their meta
+   * after it are done by the time the document is built.
+   *
+   * @param int           $order_id
+   * @param WC_Order|null $order
+   *
+   * @return bool
+   */
+  public function on_order_status($order_id, $order = null)
+  {
+    if (self::TIMING_DELAYED !== self::doc_timing() || !self::queue_available()) {
+      return $this->auto_send_invoice($order_id);
+    }
+
+    if (!$order instanceof WC_Order) {
+      $order = wc_get_order($order_id);
+    }
+    if (!$order) {
+      return false;
+    }
+
+    // The status is captured now: by the time the job runs the order may have moved on
+    // and the document type must be the one mapped to the status that triggered it.
+    // prev_doc lets the job notice a document created in the meantime (manually for example).
+    $args = array(
+      'order_id' => (int) $order->get_id(),
+      'status' => $order->get_status(),
+      'prev_doc' => (string) $order->get_meta('_linet_doc_id', true),
+    );
+
+    if (as_has_scheduled_action(self::QUEUE_HOOK, $args, self::QUEUE_GROUP)) {
+      return false;
+    }
+
+    $run_at = time() + self::doc_delay();
+    as_schedule_single_action($run_at, self::QUEUE_HOOK, $args, self::QUEUE_GROUP);
+
+    $order->add_order_note(
+      sprintf(
+        /* translators: 1: order status, 2: date and time */
+        __('LINET: Doc. for status %1$s scheduled for %2$s', 'linet-erp-woocommerce-integration'),
+        $args['status'],
+        wp_date(get_option('date_format') . ' ' . get_option('time_format'), $run_at)
+      )
+    );
+
+    return true;
+  }
+
+  /**
+   * Action Scheduler callback for a delayed document.
+   *
+   * @param int    $order_id
+   * @param string $status   status that triggered the document
+   * @param string $prev_doc _linet_doc_id of the order when it was queued
+   *
+   * @throws Exception when Linet answered with an error, so the action shows as failed
+   */
+  public function run_queued_invoice($order_id, $status, $prev_doc = '')
+  {
+    $order = wc_get_order($order_id);
+    if (!$order) {
+      return;
+    }
+
+    $status = sanitize_key($status);
+    $prev_doc = (string) $prev_doc;
+
+    // Guard: this status already got its document from the queue
+    if ('' !== (string) $order->get_meta(self::AUTO_DOC_META . $status, true)) {
+      $order->add_order_note(sprintf(
+        __('LINET: Skipped scheduled doc. for status %s, it was already created', 'linet-erp-woocommerce-integration'),
+        $status
+      ));
+      return;
+    }
+
+    // Guard: a document was created after this one was queued and not by the queue
+    // (the manual order action for example)
+    $current_doc = (string) $order->get_meta('_linet_doc_id', true);
+    if ('' !== $current_doc && $current_doc !== $prev_doc && !$this->is_queue_doc($order, $current_doc)) {
+      $order->add_order_note(sprintf(
+        __('LINET: Skipped scheduled doc. for status %1$s, doc. %2$s was created after it was scheduled', 'linet-erp-woocommerce-integration'),
+        $status,
+        $current_doc
+      ));
+      return;
+    }
+
+    $doctype = (int) get_option("wc_linet_sync_orders_wc-$status");
+    if (0 === $doctype) {
+      $order->add_order_note(sprintf(
+        __('LINET: Skipped scheduled doc. for status %s, the status is no longer mapped to a doc. type', 'linet-erp-woocommerce-integration'),
+        $status
+      ));
+      return;
+    }
+
+    $result = $this->auto_send_invoice($order_id, $doctype);
+
+    // Reload: send_invoice saved its meta on its own copy of the order
+    $order = wc_get_order($order_id);
+    $new_doc = (string) $order->get_meta('_linet_doc_id', true);
+
+    if ('' !== $new_doc && $new_doc !== $current_doc) {
+      $order->update_meta_data(self::AUTO_DOC_META . $status, $new_doc);
+      $order->save();
+      delete_transient(self::NOTICE_TRANSIENT);
+      return;
+    }
+
+    // send_invoice returns true after an error answer from Linet (it already mailed and
+    // noted it). Throwing marks the action failed so it shows up in the queue warning.
+    if (true === $result) {
+      throw new Exception(sprintf('Linet did not create a doc. for order %d (status %s), see the order notes', (int) $order_id, $status));
+    }
+  }
+
+  /**
+   * True when the doc id was created by the queue for one of the order statuses.
+   *
+   * @param WC_Order $order
+   * @param string   $doc_id
+   *
+   * @return bool
+   */
+  private function is_queue_doc($order, $doc_id)
+  {
+    foreach (array_keys(wc_get_order_statuses()) as $key) {
+      $skey = str_replace('wc-', '', $key);
+      if ($doc_id === (string) $order->get_meta(self::AUTO_DOC_META . $skey, true)) {
+        return true;
+      }
+    }
+    return false;
+  }
+
+  /**
+   * Counts of stuck (pending well past their time) and recently failed queued documents.
+   * Cached for a few minutes, this runs on admin pages.
+   *
+   * @return array{stuck:int,failed:int}
+   */
+  private static function queue_health()
+  {
+    $health = get_transient(self::NOTICE_TRANSIENT);
+    if (is_array($health)) {
+      return $health;
+    }
+
+    $query = array(
+      'hook' => self::QUEUE_HOOK,
+      'group' => self::QUEUE_GROUP,
+      'per_page' => 100,
+    );
+
+    $health = array(
+      'stuck' => count(as_get_scheduled_actions($query + array(
+        'status' => 'pending',
+        'date' => time() - self::STUCK_GRACE,
+        'date_compare' => '<=',
+      ), 'ids')),
+      'failed' => count(as_get_scheduled_actions($query + array(
+        'status' => 'failed',
+        'modified' => time() - self::FAILED_LOOKBACK,
+        'modified_compare' => '>=',
+      ), 'ids')),
+    );
+
+    set_transient(self::NOTICE_TRANSIENT, $health, 5 * MINUTE_IN_SECONDS);
+
+    return $health;
+  }
+
+  /**
+   * Admin warning when delayed documents are not getting created.
+   */
+  public function queue_health_notice()
+  {
+    if (!current_user_can('manage_woocommerce')) {
+      return;
+    }
+
+    $delayed = self::TIMING_DELAYED === self::doc_timing();
+
+    if (!function_exists('as_get_scheduled_actions')) {
+      if ($delayed) {
+        echo '<div class="notice notice-warning"><p>' . esc_html__('Linet: Document Timing is set to Delayed but the WooCommerce background queue (Action Scheduler) is not available, documents are created immediately.', 'linet-erp-woocommerce-integration') . '</p></div>';
+      }
+      return;
+    }
+
+    $health = self::queue_health();
+    if (0 === $health['stuck'] && 0 === $health['failed']) {
+      return;
+    }
+
+    $messages = array();
+
+    if ($health['stuck'] > 0) {
+      $url = admin_url('admin.php?page=wc-status&tab=action-scheduler&status=pending&s=' . self::QUEUE_HOOK);
+      $messages[] = sprintf(
+        /* translators: 1: count, 2: minutes */
+        esc_html__('%1$d Linet documents are waiting more than %2$d minutes past their scheduled time. The WooCommerce background queue is not running, check that WP-Cron (or a server cron) is working.', 'linet-erp-woocommerce-integration'),
+        $health['stuck'],
+        self::STUCK_GRACE / MINUTE_IN_SECONDS
+      ) . ' <a href="' . esc_url($url) . '">' . esc_html__('View pending documents', 'linet-erp-woocommerce-integration') . '</a>';
+    }
+
+    if ($health['failed'] > 0) {
+      $url = admin_url('admin.php?page=wc-status&tab=action-scheduler&status=failed&s=' . self::QUEUE_HOOK);
+      $messages[] = sprintf(
+        /* translators: %d: count */
+        esc_html__('%d scheduled Linet documents failed in the last 7 days. See the order notes, then use the "Send Doc. to Linet" order action if needed.', 'linet-erp-woocommerce-integration'),
+        $health['failed']
+      ) . ' <a href="' . esc_url($url) . '">' . esc_html__('View failed documents', 'linet-erp-woocommerce-integration') . '</a>';
+    }
+
+    echo '<div class="notice notice-warning"><p>' . implode('</p><p>', $messages) . '</p></div>';
+  }
+
+  /**
    * Get invoice by order
    *

linet-erp-woocommerce-integration/trunk/classes/class-wc-li-settings.php

@@ -214 +214 @@
         ),
         'description' => __('Send orders with a total of 0 (fully covered by a coupon or gift card) to Linet', 'linet-erp-woocommerce-integration'),
+      ),
+
+      'doc_timing' => array(
+        'title' => __('Document Timing', 'linet-erp-woocommerce-integration'),
+        'default' => WC_LI_Invoice_Manager::TIMING_IMMEDIATE,
+        'type' => 'select',
+        'options' => array(
+          WC_LI_Invoice_Manager::TIMING_IMMEDIATE => __('Immediately on status change', 'linet-erp-woocommerce-integration'),
+          WC_LI_Invoice_Manager::TIMING_DELAYED => __('Delayed (background queue)', 'linet-erp-woocommerce-integration'),
+        ),
+        'description' => __('Immediately creates the document the moment the order status changes. Delayed queues it in the WooCommerce background queue (Action Scheduler) and creates it after the delay below, so other plugins (payment gateways for example) can finish saving their order data first', 'linet-erp-woocommerce-integration'),
+      ),
+
+      'doc_delay' => array(
+        'title' => __('Document Delay (seconds)', 'linet-erp-woocommerce-integration'),
+        'default' => (string) WC_LI_Invoice_Manager::DEFAULT_DELAY,
+        'type' => 'text',
+        'description' => __('Used only when Document Timing is Delayed. Seconds to wait after the status change before creating the document. Default 60', 'linet-erp-woocommerce-integration'),
       ),
 

linet-erp-woocommerce-integration/trunk/readme.txt

@@ -4 +4 @@
 Requires at least: 6.0
 Tested up to: 7.0
-Stable tag: 3.6.45
+Stable tag: 3.6.46
 License: GPLv2 or later
 Requires PHP: 7.4
@@ -48 +48 @@
 
 == Changelog ==
+
+= 2026.11.08 - version 3.6.46 =
+
+* New: "Document Timing" and "Document Delay (seconds)" settings (Order Options). Immediate (the default) creates the Linet doc. on the status change as before. Delayed queues it in the WooCommerce background queue (Action Scheduler) and creates it after the delay (60 seconds by default), so plugins that change the status first and save their order meta after it (payment gateways for example) are done before the doc. is built
+* New: delayed docs are not created twice for the same status, are skipped when a doc. was created in the meantime (the manual order action for example), and use the doc. type of the status that triggered them
+* New: admin warning when delayed docs are stuck in the queue (WP-Cron not running) or failed in the last 7 days
 
 = 2026.10.29 - version 3.6.45 =

linet-erp-woocommerce-integration/trunk/woocommerce-linet.php

@@ -8 +8 @@
  * License: GPL v2 or later
  * License URI: https://www.gnu.org/licenses/gpl-2.0.html
- * Version: 3.6.45
+ * Version: 3.6.46
  * Tested up to: 7.0
  * Requires at least: 6.0
@@ -41 +41 @@
 class WC_Linet
 {
-  const VERSION = '3.6.45';
+  const VERSION = '3.6.46';