Register a Server-Uploaded File in WordPress Media Library

Sometimes you may upload a file directly to your server (e.g., via FTP) and want WordPress to recognize it in the Media Library. WordPress does not automatically detect such files, so we need to insert them programmatically.

Step 1: Upload the File to the Server

1. Use FTP, cPanel File Manager, or any server tool to upload your file.

2. Place it in the WordPress uploads folder, maintaining a standard folder structure:

wp-content/uploads/YYYY/MM/

For example:

Step 2: Add the Code to Functions.php or a Custom Plugin

You can place this code in your theme’s functions.php or in a custom plugin.

<?php function smartupworld_register_server_video_once() {
$file_path = wp_normalize_path( ABSPATH . ‘wp-content/uploads/2025/09/re-min.mp4’ );

if ( ! file_exists( $file_path ) ) {
return;
}

// Check if attachment already exists
$existing = get_posts( array(
‘post_type’ => ‘attachment’,
‘meta_key’ => ‘_wp_attached_file’,
‘meta_value’ => ‘2025/09/re-min.mp4’,
‘numberposts’ => 1,
) );

if ( $existing ) {
// Already exists, remove hook so it doesn’t run again
remove_action( ‘admin_init’, ‘smartupworld_register_server_video_once’ );
return;
}

$filetype = wp_check_filetype( basename( $file_path ), null );

$attachment = array(
‘guid’ => content_url( ‘uploads/2025/09/re-min.mp4’ ),
‘post_mime_type’ => $filetype[‘type’],
‘post_title’ => sanitize_file_name( basename( $file_path ) ),
‘post_content’ => ”,
‘post_status’ => ‘inherit’,
);

require_once( ABSPATH . ‘wp-admin/includes/image.php’ );

$attach_id = wp_insert_attachment( $attachment, $file_path );
$attach_data = wp_generate_attachment_metadata( $attach_id, $file_path );
wp_update_attachment_metadata( $attach_id, $attach_data );

// Remove hook so it runs only once
remove_action( ‘admin_init’, ‘smartupworld_register_server_video_once’ );
}
add_action( ‘admin_init’, ‘smartupworld_register_server_video_once’ );

?>

Step 3: How This Works

1. File Check – Ensures the file exists on your server.

2. Media Library Check – Checks if the file is already registered.

3. Insert Attachment – Uses wp_insert_attachment() to register the file in WordPress.

4. Generate Metadata – Creates attachment metadata for WordPress (required for videos, images).

5. One-Time Execution – The action removes itself after running to prevent duplicate registration.

Step 4: Trigger the Code

• Visit any admin page (like Dashboard → Media → Library).

• The code will execute automatically.

• The file will appear in Media Library.

Step 5: Optional – Get Attachment ID or URL

If you want to use this uploaded file in a shortcode or plugin:

<?php 

$attachment_url = wp_get_attachment_url( $attach_id );
$attachment_id = $attach_id;

You can then use $attachment_url to output the file in your shortcodes, player, or links.

Tips

• Ensure the file path in $file_path and the relative path in ‘meta_value’ match exactly.

• Works for videos, PDFs, images, or any file type.

• Best practice: place this code in a custom plugin so it’s theme-independent.

This is the standard way to programmatically register server-uploaded media without duplication.