Hierarchy-based random header images for the Graphene theme

/**********************************************************************************************
    SCRIPT INFO:

    Description: Hierarchy-based random header images for the Graphene theme
    Author:      Francisco de Azevedo (a.k.a., Marventus)
                 (based on code by Syahir Hakim)
    License:     Share at will (with attribution)

    PLEASE DO NOT DELETE THIS INFO
***********************************************************************************************/


/***********************************************************************************************
    INSTRUCTIONS:

    A.  What It Does:
    This script allows you to display custom header images for specific category archive
    pages, single posts, and pages in the Graphene Theme based on your category and/or
    page hierarchy. It supports up to 3 levels of depth.

    B.  How to Use It:
        In order for the script to work, you need to:
        1.  Create a folder called "custom-headers" inside the folder "graphene/images/";
        2.  Using the category and page slugs as folder names, create a directory tree inside
            that folder that mirrors the category and/or page hierarchy of the categories and
            pages for which you wish to display custom images;
        3.  Upload images (.JPG only) to those folders; and
        4.  Insert all LEVEL 1 (i.e. main) category and page IDs you wish to target as a comma-
            separated list inside the $custom_image_ids array below. There is no need to
            include any LEVEL 2 or LEVEL 3 categories or pages (i.e., sub-categories or subpages)
            in the array: the script will retrieve custom images for all sub-categories and
            sub-pages under the targeted LEVEL 1 categories and pages.

    C.  How It Works:
        The script checks if the current category archive, post category, or page is targeted
        in the array, and if it is, it checks if a custom image folder exists for said cats or
        pages and if they contain any images. If they do, it wil fetch them and display a random
        one. If they do not, it will fetch the images from the LEVEL 1 category or page and
        display a random one.

    D.  An Example:
        Let's suppose you have the following category structure. The cat ID of each
        category is shown in parenthesis. A star symbol (*) next to a main category means
        I am targeting that category (i.e., I have included it in the array).
        An at symbol (@) next to any category means I would like to display custom images
        for that category:

        People (2) @ *
            - Family (12) @
                -- Close Family (41) @
                -- Extended Family (39)
            - Friends (15)
                -- School (30) @
                -- Work (32)
        Objects (5) @ *
            - Tools (10) @
                -- Utensils (25) @
                -- Computers (27)
        Places (7) *
        Hobbies (8)

        Based on that, my $custom_image_ids array would be defined as such:
        $custom_image_ids = array(2,5,7);

        I would have to create the following directories inside
        "grapehne/images" and upload images to each one:
            /custom-headers/
            /custom-headers/people/
            /custom-headers/people/family/
            /custom-headers/people/family/close-family/
            /custom-headers/people/friends/
            /custom-headers/people/friends/school/
            /custom-headers/objects/
            /custom-headers/objects/tools/
            /custom-headers/objects/tools/utensils/

        Now, while navigating through the site, here's what I'll see inside
        each category:
          - Inside People | Images from /people/;
          - Inside People -> Family | Images from /people/family/;
          - Inside People -> Family -> Close Family | Images from
             /people/family/close-family/;
          - Inside People -> Family -> Extended Family | Images from /people/;
          - Inside People -> Friends | Images from /people/;
          - Inside People -> Friends -> School | Images from
             /people/friends/school/;
          - Inside People -> Friends -> Work | Images from /people/;
          - Inside Places (or its sub-cats) | Default images, because, even though
            the category is included in the $custom_image_ids array, there is no
            folder /custom-headers/places/;
          - Inside Hobbies (or its sub-cats) | Default images.

        The same logic would apply if we wanted to use pages for this, and the
        directory tree would be composed of folders named after the page slugs.


YOI CAN DELETE THESE INSTRUCTIONS OR SAVE THEM TO A TEXT FILE IF DESIRED
***********************************************************************************************/


/***********************************************************************************************
    SCRIPT START
***********************************************************************************************/

function custom_header_image($random_image) {

/* CATEGORY AND PAGE IDS FOR CUSTOM IMAGES */
       $custom_image_ids = array(4,6,8,9); // modify at will

/* GET CURRENT CAT OR PAGE INFO */
    // Test if we are inside a cat archive, a post, or a page
    if ( is_category() || is_single() || is_page() ){
        // If we are, test if we are inside a cat archive or a post
        if ( is_category() || is_single() ) {
        // If we are, test if we are inside a cat archive
            if (is_category() ) {
                // If we are, get cat and cat info
                $current_id = get_query_var( 'cat' );
                $current_array = get_category($current_id);
                $current_slug = $current_array->slug;
                $parent_id = $current_array->parent;
            // If we are not, we are inside a single post
            } else {
                // Get cat and cat info
                global $post;
                $current_array = get_the_category( $post->ID );
                $current_id = $current_array[0]->cat_ID;
                $current_slug = $current_array[0]->slug;
                $parent_id = $current_array[0]->parent;
            }
            // Get the rest of the cat info
            $parent_array = get_category($parent_id);
            $parent_slug = $parent_array->slug;
            $ancestor_id = $parent_array->parent;
            $ancestor_array = get_category($ancestor_id);
            $ancestor_slug = $ancestor_array->slug;
        // If it's neither a cat archive or a post, it's a page
        } else {
            // Get page and page info
            global $post;
            $current_array = get_page( $post->ID );
            $current_id = $post->ID;
            $current_slug = $post->post_name;
            $current_ancestors = get_ancestors ($current_id, 'page');
            $parent_id = $current_ancestors[0];
            // Test if current page has a parent
            if ( $parent_id ) {
            $parent_array = get_page( $parent_id );
            $parent_slug = $parent_array->post_name;
            }
            $ancestor_id = $current_ancestors[1];
            // Test if current page has an ancestor
            if ( $ancestor_id ) {
            $ancestor_array = get_page( $ancestor_id );
            $ancestor_slug = $ancestor_array->post_name;
            }
        }


/* GET CUSTOM IMAGES FOR CATS */
        // Check if we are dealing with one of the selected categories
        if ( in_array( $current_id, $custom_image_ids ) || in_array( $parent_id, $custom_image_ids )|| in_array( $ancestor_id, $custom_image_ids ) ) {
        // If we are, put together the absolute path
            $current_slug_slash = $current_slug . '/';
            $parent_slug_slash = $parent_slug . '/';
            $ancestor_slug_slash = $ancestor_slug . '/';
            $image_start_path = get_stylesheet_directory() . '/images/custom-headers/';
            $image_start_dir = get_stylesheet_directory_uri() . '/images/custom-headers/';
            $custom_images = '';
            // Check which directory to retrieve the custom images from and save them in a variable
            if ( $ancestor_slug ) {
                $image_abs_path = $image_start_path . $ancestor_slug_slash . $parent_slug_slash . $current_slug_slash;
                if ( is_dir( $image_abs_path ) && $custom_images = glob( $image_abs_path . "/*.jpg" ) ) {
                    $image_dir = $image_start_dir . $ancestor_slug_slash . $parent_slug_slash . $current_slug_slash;
                } else {
                    $image_abs_path = $image_start_path . $ancestor_slug_slash;
                    $image_dir = $image_start_dir . $ancestor_slug_slash;
                    $custom_images = glob( $image_abs_path . "/*.jpg" );
                }
            }
            elseif ( !$ancestor_slug && $parent_slug ) {
                $image_abs_path = $image_start_path . $parent_slug_slash . $current_slug_slash;
                if ( is_dir( $image_abs_path ) && $custom_images = glob( $image_abs_path . "/*.jpg" ) ) {
                    $image_dir = $image_start_dir . $parent_slug_slash . $current_slug_slash;
                } else {
                    $image_abs_path = $image_start_path . $parent_slug_slash;
                    $image_dir = $image_start_dir . $parent_slug_slash;
                    $custom_images = glob( $image_abs_path . "/*.jpg" );
                }
            }
            elseif ( $current_slug && !$parent_slug ) {
                $image_abs_path = $image_start_path . $current_slug_slash;
                if ( is_dir( $image_abs_path ) && $custom_images = glob( $image_abs_path . "/*.jpg" ) ) {
                    $image_dir = $image_start_dir . $current_slug_slash;
                }
            }
            // Retrieve random images from custom image  obtained
            if ( $custom_images ) {
                $key = array_rand( $custom_images );
                $random_image = $image_dir . basename( $custom_images[$key] );
            }
        }
    }
    // Return the random image obtained
    return $random_image;
}
add_filter( 'graphene_header_image', 'custom_header_image' );

/***********************************************************************************************
    SCRIPT END
***********************************************************************************************/