Upload image in custom module form

We are going to define an upload field for a single image, using the Drupal API to do some basic validation.

my_module.module

/**
 * Form builder; Builds the image form.
 */
function my_module_image_form($form, &$form_state) {
  $image_path = my_module_get_image_path();
  // Thumbnail preview (optional).
  $form['thumbnail_preview'] = array(
    '#type' => 'item',
    '#markup' => theme('thumbnail', array(
      'path' => $image_path,
      'width' => 100,
      'height' => 100,
      'alt' => t('Example image'),
    )),
  );

  // Upload field.
  $form['image'] = array(
    '#type' => 'file',
    '#title' => t('Upload picture'),
    '#description' => t('Select a picture of at least @dimensionspx and maximum @filesize.', array(
      '@dimensions' => '100x100',
      '@filesize' => format_size(file_upload_max_size()),
    )),
  );

  // Submit button.
  $form['submit'] = array(
    '#type' => 'submit',
    '#value' => t('Save'),
  );
}

The first form element displays a preview of the currently uploaded image. You'll have to replace my_module_get_image_path() with a real function or variable that gets the image path. The second form element is the upload field. Because we will check on dimensions (in the submit handler) and file size (what Drupal does by default), we are displaying this information as a field description.

Next, also in my_module.module we add the submit handler of the form:

/**
 * Form submit handler; Redirect to the picture edit form.
 */
function my_module_image_form_submit($form, &$form_state) {
  // Upload file to upload_directory in the public files dir.
  $file = file_save_upload('image', array(
    'file_validate_is_image' => array(),
    'file_validate_image_resolution' => array('500x500', '100x100'),
  ), 'public://uploaded_images/', FILE_EXISTS_RENAME);
  
  // Check if image upload was success.
  if ($file) {
    drupal_set_message(t('Image successfully uploaded.'), 'status');
  }
  else {
    form_set_error('image', t('Image was not uploaded.'));
  }
}

Make sure that the first parameter of file_save_upload() is the name of your image field. In our case 'image'.
We are uploading the file to the directory 'uploaded_images'.
file_validate_is_image: Validation to check if the uploaded file is an image.
file_validate_image_resolution: The image will not be uploaded when smaller than 100x100 pixels and will be automatically resized when bigger than 500x500 pixels.
Other validations provided by core are file_validate_size or file_validate_extensions.
The last parameter of the upload function is the replace behaviour. In our case we will rewrite the file name when already existing. Other options are:

• FILE_EXISTS_REPLACE: Replace the existing file.
• FILE_EXISTS_RENAME: Append _{incrementing number} until the filename is unique.
• FILE_EXISTS_ERROR: Do nothing and return FALSE.

That's it, our upload form is functional.