Programmatically Importing Product with Images in Magento

Although written in 2009, this article is still consistently one of the best read articles on the site. Use it at your own risk. If someone knows for sure that it still works (or doesn't!), please let me know.
It took me quite a while to figure out how to import products into Magento including images. The long version is below, the final results are here for those that need a quick fix, with thanks to articles from Darryl Adie (to show me 95% of the solution) and tza79 (who showed me how to set the visibility, a.k.a. mediaAttribute). Start with the code from Darryl, and then add the following...

//This call is needed since the media gallery is null for a newly created product.

$product->setMediaGallery (array('images'=>array (), 'values'=>array ()));

$product->addImageToMediaGallery ($fullImagePath, array ('image'), false, false); 

$product->addImageToMediaGallery ($fullSmallImagePath, array ('small_image'), false, false); 

$product->addImageToMediaGallery ($fullThumbnailPath, array ('thumbnail'), false, false);

----------------------------
Long, boring version:

I understood quickly with debugging (and with the help of Branko Ajzele's article) that the media gallery used in magento/app/code/core/Mage/Catalog/Model/Product.php was the object that I wanted to use, but for a newly created product, product->getMediaGalleryImages() returns NULL.

Product attribute "media_gallery_images" is only set in getMediaGalleryImages, when $product->getMediaGallery is already set, but $product->getMediaGallery is null for a newly created product - this is the cause of getMediaGalleryImages returning null.

product->setMediaGallery doesn't exist - but then again, neither does getMediaGallery (even though it's called in $product->getMediaGalleryImages)! What's going on here?!? This led me to several articles, which led to people talking about PHP5's Overloading. OK, maybe I should have known this already, but it was a cool discovery. However, it didn't help me solve my problem.

Here's where I lost a lot of time... I decided my best bet was to debug the admin area, to see how they create the media gallery. I was able to get Zend Studio for Eclipse to debug the admin area... a task which I will document shortly.

With the debugger, I could see that it was the ProductController that was creating the media gallery while loading the admin part, but EXACTLY where it was creating it, I was not able to find before it was time to go to dinner yesterday. In any case, if you want to debug this yourself, I can give you a hint: start in the "newAction" routine in /magento/app/code/core/Mage/Adminhtml/controllers/Catalog/ProductController.php

Rather than going back to debugging the admin area today, I decided to take a good look at what an empty media gallery looks like, by creating a product in the Magento admin area, and then loading it with...

$product->load(6);
$mediaGallery = $product->getMediaGallery();
print_r ($mediaGallery);

Hmmm, it's nothing more than an array of arrays. Why not make it myself using setMediaGallery? Bingo!