=A few more phpStorm suggestions, mainly in PHPDocs

Jake Vanderwerf

2026-08-28 5b50afdcafd150186ea5c7b0e1cad98065590b35

 inc/managers/queue/Queue.php

@@ -4,20 +4,32 @@
   exit;
}

use Exception;
use JVBase\Instance;
use JVBase\managers\AdminPages;
use JVBase\managers\Errors;
use JVBase\rest\routes\QueueRoutes;
use Throwable;
use WP_Error;
use WP_REST_Request;
use WP_REST_Response;

class Queue
{
   use Instance;
   private Storage $storage;
   private Processor $processor;
   private TypeRegistry $registry;
   public Executor $executor;
   private Locker $locker;

   public function __construct()
   private QueueRoutes $routes;

   private function __construct()
   {
      //Load routes
      $this->routes = new QueueRoutes();

      $this->storage = new Storage();
      $this->registry = new TypeRegistry();
      $this->locker = new Locker();
@@ -27,6 +39,7 @@

      add_action('jvb_process_queue', [$this, 'checkQueue']);
      add_action('jvb_queue_maintenance', [$this, 'maintenance']);
      add_action('jvb_daily_snapshot', [$this->storage, 'snapshotDaily']);

      if (!wp_next_scheduled('jvb_process_queue')) {
         wp_schedule_event(time(), 'every-minute', 'jvb_process_queue');
@@ -34,6 +47,11 @@
      if (!wp_next_scheduled('jvb_queue_maintenance')) {
         wp_schedule_event(time(), 'hourly', 'jvb_queue_maintenance');
      }
      if (!wp_next_scheduled('jvb_daily_snapshot')) {
         // Schedule for next 3am
         $next3am = strtotime('tomorrow 3am', current_time('timestamp'));
         wp_schedule_event($next3am, 'daily', 'jvb_daily_snapshot');
      }

      jvb_register_do_once('queue_admin_action_registered', [$this, 'registerAdminAction']);
      add_filter(BASE.'admin_action_filter', [$this, 'adminActionFilter'], 10, 3);
@@ -59,13 +77,15 @@
    * @param int $userId User ID
    * @param array $data Request data
    * @param array $options {
    *     @type string $priority     'low', 'normal', 'high'
    *     @type int $delay           Seconds to delay processing
    *     @type string $scheduled    Specific datetime to process
    *     @type array|string $depends_on  Operation IDs this depends on
    *     @type string|array $chunk_key   Key(s) to chunk (overrides registry)
    *     @type int $chunk_size      Chunk size (overrides registry)
    * @type string $priority 'low', 'normal', 'high'
    * @type int $delay Seconds to delay processing
    * @type string $scheduled Specific datetime to process
    * @type array|string $depends_on Operation IDs this depends on
    * @type string|array $chunk_key Key(s) to chunk (overrides registry)
    * @type int $chunk_size Chunk size (overrides registry)
    * }
    * @throws Throwable
    * @throws Throwable
    */
   public function add(string $type, int $userId, array $data, array $options = []): array|WP_Error
   {
@@ -88,8 +108,8 @@
            'updated_existing' => false,
         ];

      } catch (\Exception $e) {
         JVB()->error()->log('queue', $e->getMessage(), $data, 'high');
      } catch (Exception $e) {
         Errors::getInstance()->log('queue', $e->getMessage(), $data, 'high');
         return new WP_Error('queue_failed', $e->getMessage());
      }
   }
@@ -97,7 +117,7 @@
   /**
    * Try to merge incoming operation into an existing pending/scheduled one.
    * Returns result array if merged, null if not.
    * @throws \Throwable
    * @throws Throwable
    */
   private function tryMerge(Operation $incoming): ?array
   {
@@ -106,7 +126,9 @@
         return null;
      }

      $existing = $this->storage->findMergeable($incoming->type, $incoming->userId);
      $criteria = $mergeable->matchCriteria($incoming);

      $existing = $this->storage->findMergeable($incoming->type, $incoming->userId, $criteria);
      if (!$existing || !$mergeable->canMerge($existing, $incoming)) {
         return null;
      }
@@ -164,7 +186,7 @@
   public function maintenance(): void
   {
      $this->locker->withLock(function () {
         $this->storage->resetStuckOperations(30);
         $this->storage->resetStuckOperations();
      });
      $this->runQueueOnShutdown();
   }
@@ -187,7 +209,7 @@
   /**
    * Get a specific value from an operation - backwards compatibility
    */
   public function getOperationValue(string $id, string $column, bool $decodeJson = true): mixed
   public function getOperationValue(string $id, string $column, bool $decodeJson = true): \static|string|int|array|null
   {
      $op = $this->get($id);
      if (!$op) {
@@ -334,7 +356,7 @@
      // Use provided operation_id or generate one
      $op->id = !empty($options['operation_id'])
         ? $options['operation_id']
         : 'u' . $userId . '_' . uniqid('op_');
         : self::generateID($userId);

      $op->type = $type;
      $op->userId = $userId;
@@ -395,7 +417,7 @@

   private function runQueueOnShutdown(): void
   {
      if (!has_action('shutdown', [$this, 'processQueueOnShutdown'])) {
      if (!has_action('shutdown', [$this, 'processQueueOnShutdown']) && $this->processor->hasAdequateResources()) {
         add_action('shutdown', [$this, 'processQueueOnShutdown'], 100);
      }
   }
@@ -413,7 +435,7 @@

   public function registerAdminAction():void
   {
      $admin = JVB()->admin();
      $admin = AdminPages::getInstance();
      $admin->registerAction(
         'Restart Stuck Operations',
         'restart-stuck-operations',
@@ -427,11 +449,12 @@
         'infinity'
      );
   }

   /**
    * @param WP_REST_Response $response
    * @param WP_REST_Request $request
    * @param string $action
    *
    * @return bool|WP_REST_Response
    * @return WP_REST_Response|bool
    */
   public function adminActionFilter(WP_REST_Response $response, WP_REST_Request $request, string $action):WP_REST_Response|bool
   {
@@ -454,4 +477,9 @@
            return $response;
      }
   }

   public static function generateId(int $userID):string
   {
      return 'u' . $userID . '_' . uniqid('op_');
   }
}