Obelix WP Code Documentation.

 
     /**
      * Retrieves the valid ID and type (post, term, user, comment) based on a given ID or the current query.
      *
      * This function checks for a valid ID from various contexts (post, term, user, comment)
      * and returns an array containing the valid ID and its type, or false if no valid type is found.
      *
      * @since 1.0.0
      *
      * @param int|false $id The optional ID to validate. If not provided, the current queried object is used.
      * 
      * @return array|false An array with 'id' and 'type' (post, term, user, comment), or false if no valid type is found.
      */
     function get_valid_type($id = false)
     {
         // Set a transient key for caching results
         $transient_key = 'valid_type_' . ($id ? $id : 'current_query');
     
         // Check if the data is cached
         $cached_value = get_transient($transient_key);
         if ($cached_value !== false) {
             return $cached_value;
         }
     
         $the_id = false;
         $type = false;
     
         // If an ID is provided, check for various object types
         if ($id) {
             if (get_post($id)) {
                 $the_id = (int) $id;
                 $type = 'post';
             } elseif (get_term($id)) {
                 $the_id = (int) $id;
                 $type = 'term';
             } elseif (get_user_by('id', $id)) {
                 $the_id = (int) $id;
                 $type = 'user';
             } elseif (get_comment($id)) {
                 $the_id = (int) $id;
                 $type = 'comment';
             }
         } else {
             // If no ID is provided, get the current queried object
             $queried_object = get_queried_object();
             if (is_object($queried_object)) {
                 if (isset($queried_object->post_type, $queried_object->ID)) {
                     $the_id = (int) $queried_object->ID;
                     $type = 'post';
                 } elseif (isset($queried_object->roles, $queried_object->ID)) {
                     $the_id = (int) $queried_object->ID;
                     $type = 'user';
                 } elseif (isset($queried_object->taxonomy, $queried_object->term_id)) {
                     $the_id = (int) $queried_object->term_id;
                     $type = 'term';
                 } elseif (isset($queried_object->comment_ID)) {
                     $the_id = (int) $queried_object->comment_ID;
                     $type = 'comment';
                 }
             }
         }
     
         // If no valid ID or type is found, cache the result as false
         if ($the_id === false || $type === false) {
             set_transient($transient_key, false, 2 * HOUR_IN_SECONDS);
             return false;
         }
     
         // Cache the valid ID and type for 2 hours
         $result = [
             'id' => $the_id,
             'type' => $type
         ];
     
         set_transient($transient_key, $result, 2 * HOUR_IN_SECONDS);
     
         return $result;
     }
     
     /**
      * Retrieves metadata for a specific entity (post, term, user, comment).
      *
      * This function fetches metadata for the given object type (post, term, user, or comment)
      * based on the selector (meta key) and the entity ID.
      *
      * @since 1.0.0
      *
      * @param string $selector The meta key to retrieve the value for.
      * @param int|false $id    The ID of the entity (post, term, user, or comment). If false, the current entity is used.
      * 
      * @return mixed The metadata value, or false if not found.
      */
     function get_meta_field($selector, $id = false)
     {
         // Validate the ID and get the object type
         $valid_type = get_valid_type($id);
         if (!$valid_type) {
             return false;
         }
     
         $the_id = (int) $valid_type['id'];
         $type = $valid_type['type'];
         $value = false;
     
         // Retrieve metadata based on the object type
         switch ($type) {
             case 'post':
                 $value = get_post_meta($the_id, $selector, true);
                 break;
             case 'term':
                 $value = get_term_meta($the_id, $selector, true);
                 break;
             case 'user':
                 $value = get_user_meta($the_id, $selector, true);
                 break;
             case 'comment':
                 $value = get_comment_meta($the_id, $selector, true);
                 break;
         }
     
         // Return the unserialized value if found, otherwise return false
         return $value ? maybe_unserialize($value) : false;
     }
     
     
     /**
      * Retrieves a specific field object from the field guide for a given entity (post, term, user, or comment).
      *
      * This function fetches a meta field object using a selector (meta key) from a field guide.
      * If $load_value is set to true, it also retrieves and includes the stored meta value for the field.
      * The function handles group fields by assigning child field values from the stored data.
      *
      * @since 1.0.0
      *
      * @param string    $selector   The field key (meta_key) used to retrieve the field object.
      * @param int|false $id         The ID of the entity (post, term, user, comment) to retrieve the field object from. 
      *                              If false, the function attempts to get a valid entity ID via `get_valid_type()`.
      * @param bool      $load_value Whether to load the stored value for the field from meta data. Defaults to false.
      *
      * @return array|false The field object with optional value, or false if the field object is not found.
      */
     function get_meta_field_object($selector, $id = false, $load_value = false)
     {
         // Get the valid ID and type (post, term, user, comment) if not explicitly provided.
         $valid_type = $id ?: get_valid_type($id);
         if (!$valid_type) return false;
     
         $the_id = (int) $valid_type['id'];
         $type = $valid_type['type'];
     
         // Retrieve the field guide from the meta (from '_obelix_field_guide').
         $field_guide = get_meta_field('_obelix_field_guide', $the_id);
         if (!$field_guide || !isset($field_guide[$selector])) {
             // If no field guide exists or the selector is not present, return false.
             return false;
         }
     
         // Fetch the field object for the specified selector.
         $fields_Obj = $field_guide[$selector];
     
         // If the value is not requested, return the field object as is.
         if (!$load_value) return $fields_Obj;
     
         // Retrieve the stored meta value for the field.
         $field_value = get_meta_field($selector, $the_id);
         if (!$field_value) return $fields_Obj;
     
         // Unserialize the meta value (if applicable).
         $field_value = maybe_unserialize($field_value);
     
         // Handle the "group" field type by populating child field values.
         if ($fields_Obj['type'] === 'group' && isset($fields_Obj['fields']) && is_array($fields_Obj['fields'])) {
             foreach ($fields_Obj['fields'] as $key => $field) {
                 foreach ($field_value as $child) {
                     // Assign child values based on matching field keys.
                     foreach ($child as $k => $data) {
                         if (isset($field['key']) && $field['key'] === $k) {
                             $fields_Obj['fields'][$key]['value'][] = $data;
                         }
                     }
                 }
             }
         } else {
             // Assign the field value directly for non-group fields.
             $fields_Obj['value'] = $field_value;
         }
     
         // Return the field object, or false if the object is empty.
         return !empty($fields_Obj) ? $fields_Obj : false;
     }
     
     
     
     /**
      * Retrieves an array of custom field objects for a specific post, term, user, or comment.
      *
      * This function fetches the meta field objects associated with a given post ID, term ID, user ID, or comment ID.
      * It loads the field guide from the entity's metadata (via the `_obelix_field_guide` meta key).
      * If $load_value is true, it populates the field values from the corresponding meta fields.
      * The function also handles nested "group" fields, associating child fields with their respective parent groups.
      *
      * @since 1.0.0
      *
      * @param int|false $id         The ID of the entity (post, term, user, comment) for which field objects are retrieved. 
      *                              If not provided, the function attempts to fetch a valid ID via `get_valid_type()`. 
      *                              Returns false if no valid ID is found.
      * @param bool      $load_value Whether to load field values from meta data. Defaults to false.
      *
      * @return array|false An associative array of field objects where the key is the meta key and the value is the field object.
      *                     Returns false if no valid entity ID is found or no field guide exists.
      */
     function get_meta_field_objects($id = false, $load_value = false)
     {
         // Retrieve the valid entity ID and type (post, term, user, comment).
         $valid_type = $id ?: get_valid_type($id);
         if (!$valid_type) return false;
         $the_id = (int) $valid_type['id'];
         $type = $valid_type['type'];
         
         // Fetch the field guide from the meta of the entity using the '_obelix_field_guide' key.
         $field_guide = get_meta_field('_obelix_field_guide', $the_id);
         if (!$field_guide || !is_array($field_guide)) {
             // If no field guide exists or it is not an array, return false.
             return false;
         }
     
         // Initialize an empty array to store field objects.
         $meta = [];
     
         // Loop through each field in the field guide.
         foreach ($field_guide as $key => $field) {
             // Fetch the field object for the current field.
             // Optionally load the stored value if $load_value is true.
             $field_obj = get_meta_field_object($key, $id, $load_value);
             
             // Add the field object to the result array, with the field key as the array key.
             $meta[$key] = $field_obj;
         }
     
         // Return the populated array of field objects, or false if empty.
         return !empty($meta) ? $meta : false;
     }