Unas de las reglas para manejar archivos en wp es que el sistema no permite que desde tu archivo local, puedas usar estos en un proyecto que este dentro del repositorio de wp o para ser consumido por la comunidad de wp. 

El proceso consiste en localizar el archivo dentro del proyecto, copiarlo a la carpeta local temporal y luego generar los metadatos para que wp lo registre en su librería de medios. Aquí los pasos:

 

Localizamos el archivo que deseamos subir

$ruta_local = '/ruta/a/tu/imagen.jpg';

Es necesario verificar que el archivo existe, en que caso de error lanzamos una excepción utilizando el hook disponible para wp.

if (!file_exists($ruta_archivo_local)) {
 return new WP_Error('archivo_no_encontrado', 'El archivo no se encontró en la ruta especificada.');
 }

Vamos a estar utilizando funciones nativas del sistema de wp para localizar las rutas asi como  hooks que generan metadatos por lo tanto debemos llamar los archivos que contienen estos recursos.

 require_once(ABSPATH . 'wp-admin/includes/file.php');
 require_once(ABSPATH . 'wp-admin/includes/image.php');
 require_once(ABSPATH . 'wp-admin/includes/media.php');

Aunque podemos hacer esto directo, para evitar errores, obtenemos informacion necesaria del archivo que deseamos subir, estas informaciones en esta variable guarda la ruta del archivo y el baseName que puede ser 'image/jpg' u otro.

 $info_archivo = pathinfo($ruta_archivo_local);
 $nombre_archivo = $info_archivo['basename'];

Ahora que tenemos los datos del archivo, asignamos la ruta en donde se estaría copiando el archivo a la carpeta temporal, tambien asignamos el nombre que puede ser colocado directamente o tomando el nombre genuino del archivo.

 $upload_dir = wp_upload_dir();
 $ruta_destino = $upload_dir['path'] . '/' . $nombre_archivo;

El siguiente paso es vital ya que que se encarga de ejecutar la acción que copia nuestro archivo local a wp y lanzamos una excepción en caso error para ir controlando el flujo del proceso y poder localizar el error en caso de un fallo en el proceso.

 if (!copy($ruta_archivo_local, $ruta_destino)) {
     return new WP_Error('fallo_copia', 'No se pudo copiar el archivo a la carpeta de subidas.');
 }

Si todo va bien tenemos el archivo dentro de wp copiado, entonces debemos preparar la metadata para que sea registrado en medios de wp. 

 $mime_type = mime_content_type($ruta_destino); // Detecta el tipo MIME
 $archivo = [
   'guid' => $upload_dir['url'] . '/' . $nombre_archivo,
   'post_mime_type' => $mime_type,
   'post_title' => $titulo_imagen,
   'post_content' => '',
   'post_status' => 'inherit',
 ];

Para que nos sirve esta metadata si ya tenemos nuestro archivo en wp. 

Cuando subimos un archivo a al medios de wp es como crear un post, en este se guardan informaciones como generar un id identificador, asignar un nombre, generar los diferentes tamaños así como evitar que contenga datos maliciosos que podría tener un archivo binario.

Podríamos pensar que el archivo puede ser visible ya que esta dentro del sistema de wp, pero solo se ha copiado a un espacio temporal por lo tanto el siguiente comando es quien se encarga de esto logrando que el mismo pase a la carpeta de medios de wp y para continuar rastreando posibles errores pasamos una excepción en caso de error. 

 $attachment_id = wp_insert_attachment($archivo, $ruta_destino);
 if (is_wp_error($attachment_id)) {
 return $attachment_id; // Retorna el error si ocurre
 }

Hasta el momento si todo va bien ya el archivo se encuentra oficialmente en wp y podríamos invocar por su id pero queda el ultimo paso para generar la metadata que wp nos enseña al ciclar sobre este archivo y finalmente retornamos el id en caso de que queramos asignarlo a alguna variable ect. 

 $metadata = wp_generate_attachment_metadata($attachment_id, $ruta_destino);
 wp_update_attachment_metadata($attachment_id, $metadata);

 return $attachment_id;

A continuación el coligo completo.

 

$ruta_local = '/ruta/a/tu/imagen.jpg';

 if (!file_exists($ruta_archivo_local)) {
 return new WP_Error('archivo_no_encontrado', 'El archivo no se encontró en la ruta especificada.');
 }
 
 require_once(ABSPATH . 'wp-admin/includes/file.php');
 require_once(ABSPATH . 'wp-admin/includes/image.php');
 require_once(ABSPATH . 'wp-admin/includes/media.php');
 
 $info_archivo = pathinfo($ruta_archivo_local);
 $nombre_archivo = $info_archivo['basename'];
 
 $upload_dir = wp_upload_dir();
 $ruta_destino = $upload_dir['path'] . '/' . $nombre_archivo;

 if (!copy($ruta_archivo_local, $ruta_destino)) {
 return new WP_Error('fallo_copia', 'No se pudo copiar el archivo a la carpeta de subidas.');
 }

 $mime_type = mime_content_type($ruta_destino); // Detecta el tipo MIME
 $archivo = [
 'guid' => $upload_dir['url'] . '/' . $nombre_archivo,
 'post_mime_type' => $mime_type,
 'post_title' => $titulo_imagen,
 'post_content' => '',
 'post_status' => 'inherit',
 ]; 

 $attachment_id = wp_insert_attachment($archivo, $ruta_destino);

 if (is_wp_error($attachment_id)) {
 return $attachment_id; // Retorna el error si ocurre
 } 

 $metadata = wp_generate_attachment_metadata($attachment_id, $ruta_destino);
 wp_update_attachment_metadata($attachment_id, $metadata);

 return $attachment_id;