Practical WordPress Development

Upload Files to the WordPress Media Library

Programmatically uploading files to WordPress is really just the same as uploading files from any source location to a destination.

That is to say, there are a number of PHP functions all of which make it pretty easy to deal with file-level operations, grabbing files from one location, and moving them to the next.

And yes, there are some nuances that can come with PHP’s configuration such that you may not be able to write to certain directories, perform certain options via HTTP, and so on. All of these can be managed by either changing up the configuration or by changing the way in which files are handled by the code.

The WordPress Media Library

One thing that WordPress offers that manual uploads don’t manage is adding files – specifically media types – to the Media Library after uploading a file. This is relatively easy to do given media_sideload_image.

But let’s say the situation is a little more complex.

Adding Files to the WordPress Media Library

Say that the setup is something like this:

  • You have files located on the root of the server
  • You need to move the files to the `uploads` directory
  • You need to add the files to the Media Library

There are a number of reasons that files may exist on the server. Perhaps you don’t want to grant the user access to the CMS, or perhaps it’s just easier for the person to drop the files into a directory via FTP and have a cron job pick it up and handle the rest.

Whatever the case, here’s a function that will locate the files in a subdirectory called my-files in the root of a WordPress installation, upload the file, and then write to the error log if the upload fails.

Note that in the code above we’re working both with the upload directory (using the path index of the $uploads array) and with the upload URL (using the url index of the $uploads array). This is because, in most cases, copy requires that the operation be done using the file system rather than remote calls using HTTP.

Furthermore, not much is happening after the image has been uploaded. That is, the code really only writes to a file if there’s a problem; otherwise, it’s assumed to have worked.

This is usually better handled by giving some type of feedback. Since implementations vary, that’s one of those things that’s easier to implement on a one-on-one basis rather than trying to give some type of prescriptive advice in a single blog post.

Regardless, this will make it possible to upload files to the WordPress Media Library when the files already exist on the server.


  1. Edward

    Oh sweet. This will come in handy.

  2. Julien

    Hi Tom,
    very useful post once again!
    But, what is this error_log call? Is it a WP native function?

    • Tom

      error_log is a built-in PHP function :).

  3. simona

    Hi, I would really need this function now for a website I am working on.
    However, as not much into coding and php, could you please explain (or point me to some resources) what I should do with this bit of code – should I just copy it to the functions.php file? And how do I make it “happen”?


    • Tom

      Hey Simona,

      In order to make this happen, this depends on how you server is setup – as you can see in the code above, I’m operating out of a directory called my-files.

      In functions.php, you can define this code, but you’ll need to pass it the $post_id and the $filename and it will need to be invoked by another function at some point during the page lifecycle depending on when you need to actually make this happen.

  4. simona

    Thanks, Tom, for coming back to me – I see it is probably far beyond my “non-programming” skills so I will need to find another way round it.

    Thanks again!

  5. Ilmari


    I think that this function could solve my problems I have been trying to solve for many weeks now! But I’m not much familiar with WP functions, how should I install this piece of code and how I run the function? Does it open images in the Media Library if there will be subfolders inside of my-files folder?

    Best Wishes

    • Tom

      Hey Ilmari,

      This particular question is one that deserves an answer that’s more advanced than can really be shared in a comment. I wish I could be more help, but if the content of the blog post isn’t enough to round out the bases, I don’t have enough time to share the content in this particular area right now.

  6. Ilmari

    Oh, and I want to invoke this function when I upload my LightRoom photos in my blog (into a NextGen Gallery) with this LightRoom plugin:

    All the best

  7. Asad Ali


    I am working on a plugin and its been great help for me. :)


  8. David Cowgill

    Great snippet, Tom!

    FYI: I needed to add these includes within the function otherwise I got a “media_sideload_image() function not found” error.

    // WordPress API for image uploads.

    include_once( ABSPATH . 'wp-admin/includes/image.php' );

    include_once( ABSPATH . 'wp-admin/includes/file.php' );

    include_once( ABSPATH . 'wp-admin/includes/media.php' );

Leave a Reply

© 2020 Tom McFarlin

Theme by Anders NorenUp ↑