<?php
/**
 * WordPress image and attachment helpers.
 * 
 * @author Dan Suleski
 * @package ski
 * @since ski 1.0
 */

namespace ski;



/**
 * The main WP database class where database interactions can be grouped together for consistency.
 */
class media
{
    /* PUBLIC */

    /**
     * Returns an array of all attachment IDs present in the media library that
     * match a given slug pattern.
     * 
     * @param string $slug_like Search for attachments that match this name; can use SQL 'like' wildcards
     * @param boolean $mime_type Can be something like 'image' to find 'image/png', 'image/jpg', etc; or null for everything
     * @param integer $num_ids_desired The first X rows will be returned; otherwise use 0 for everything
     * @return array If found, an array of attachment IDs; otherwise, null
     */
    public static function find_ids_like_slug( $slug_like = null, $mime_type = 'image', $num_ids_desired = 0 )
    {
        global $wpdb;
        
        //  Do not bother if the slug is non-existent..
        if ( ( $slug_like == null ) || ( empty ( $slug_like ) ) ) return null;
        
        //  Put together a query - talk directly to the database since the
        //  slug info is not supported by any of the WordPress query functions..
        $query = 'select ID from wp_posts where post_type = \'attachment\' ';
        if ( !empty( $slug_like ) ) $query .= ' and post_name like \''.$wpdb->esc_like( $slug_like ).'\' ';
        if ( !empty( $mime_type ) ) $query .= 'and post_mime_type like \'%'.$wpdb->esc_like( $mime_type ).'%\' ';
        if ( $num_ids_desired > 0 ) $query .= ' limit '.esc_sql( $num_ids_desired );

        //  Run the query - just need one piece of info, so use the column option..
        return $wpdb->get_col( $query );
    }

    /**
     * Returns the first-found attachment ID present in the media library that
     * matches a given slug pattern.
     * 
     * @param string $slug_like Search for attachments that match this name; can use SQL 'like' wildcards
     * @param boolean $mime_type Can be something like 'image' to find 'image/png', 'image/jpg', etc; or null for everything
     * @return array If found, a single attachment ID; otherwise, null
     */
    public static function find_first_id_like_slug( $slug_like = null, $mime_type = 'image' )
    {
        $result = self::find_ids_like_slug( $slug_like, $mime_type, 1 );
        if ( $result != null ) return $result[0];
        return null;
    }

    /**
     * Returns an array of all image IDs present in the media library that
     * match the given slug pattern.
     * 
     * @param string $slug_like Search for images that match this name; can use SQL 'like' wildcards
     * @param integer $num_ids_desired The first X rows will be returned; otherwise use 0 for everything
     * @return array If found, an array of image IDs; otherwise, null
     */
    public static function find_image_ids_like_slug( $slug_like = null, $num_ids_desired = 0 )
    {
        return self::find_ids_like_slug( $slug_like, 'image', $num_ids_desired );
    }

    /**
     * Returns the first-found image ID present in the media library that
     * matches a given slug pattern.
     * 
     * @param string $slug_like Search for an image that matches this name; can use SQL 'like' wildcards
     * @return array If found, a single image ID; otherwise, null
     */
    public static function find_first_image_id_like_slug( $slug_like = null )
    {
        $result = self::find_ids_like_slug( $slug_like, 'image', 1 );
        if ( $result != null ) return $result[0];
        return null;
    }

    /**
     * Retrieves information on an attachment.  Oddly, no native function 
     * exists in WordPress to give this kind of info all-in-one.
     * 
     * @param integer $attachment_id The ID of the attachment whose info is desired
     * @param boolean $include_sizes Set to 'true' and the returned array will contain an embedded array with the 'src' for each image size
     * @return array This array contains 'alt', 'caption', 'description', 'href', 'src', and 'title' (and optionally, 'sizes')
     */
    public static function get_meta_info( $attachment_id, $include_sizes = false )
    {
        $end = null;
        if ( ( $attachment_id != null ) && ( $attachment_id >= 0 ) )
        {
            //  Setup the first layer of data from this attachment.
            $attachment = get_post( $attachment_id );
            if ( !empty( $attachment ) )
            {
                $end = array (
                    'alt'           =>	get_post_meta( $attachment->ID, '_wp_attachment_image_alt', true ),
                    'caption'       =>	$attachment->post_excerpt,
                    'description'   =>	$attachment->post_content,
                    'href'          =>	get_permalink( $attachment->ID ),
                    'src'           =>	$attachment->guid,
                    'title'         =>	$attachment->post_title
                );
            }
            
            //  Optionally, setup the deeper layer that includes the
            //  sources for all sizes (in the case of an image).
            if ( $include_sizes )
            {
                $sizes = self::get_image_sizes();
                if ( !is_wp_error( $sizes ) && ( !empty( $sizes ) ) )
                {
                    $end['sizes'] = array();
                    foreach( $sizes as $size )
                    {
                        $struct = wp_get_attachment_image_src( $attachment_id, $size );
                        if ( !empty( $struct ) )
                        {
                            $end['sizes'][$size] = $struct[0];
                        }
                    }
                }
            }
        }
        return $end;
    }

    /**
     * Return the sized-specific HTML for a full path image.  Specifically, if you send it something
     * like 'http://www.mysite.com/stuff.png' and you ask for the 'medium' registered WP side, you
     * might get something back like 'http://www.mysite.com/stuff-300x300.png'.
     * 
     * @param string $path The full path of the image desired
     * @param string $size A thumbnail slug; can be 'medium', 'thumbnail', etc; defaults to 'full'
     * @param string $title An optional attribute to be used in the generated HTML
     * @param string $class An optional class to apply to the generated HTML
     * @return strubg The generated resized image markup
     */
    public static function generate_resized_image_html_by_original_path( $path, $size = 'full', $title = '', $class = '' )
    {
        return media::generate_image_html_by_slug( path::change_extension( basename( $path ), '' ), $size, $title, $class );
    }

    /**
     * Return the HTML for an image ID.  WordPress already offers this kind of
     * functionality, but it is being added here to pair up with the sibling
     * function - generate_image_html_by_slug.
     * 
     * @param integer $id The ID of the image desired
     * @param string $size A thumbnail slug; can be 'medium', 'thumbnail', etc; defaults to 'full'
     * @param string  $title An optional attribute to be used in the generated HTML
     * @param string $class An optional class to apply to the generated HTML
     * @return strubg The generated image markup
     */
    public static function generate_image_html_by_id( $id, $size = 'full', $title = '', $class = '' )
    {
	//  Construct the HTML..
        $image_html =   wp_get_attachment_image
                        (
                            $id,
                            $size,
                            0,
                            array
                            (
                                'alt'   =>	$slug,
                                'class' =>	$class,
                                'title' =>	$title
                            )
                        );
	
	//  Simply return the markup..
	return $image_html;
    }

    /**
     * Return the HTML for an image slug.  Oddly, WordPress only offers this 
     * kind of functionality against an ID, not a slug.
     * 
     * @param string $slug The name of the image desired; can use SQL 'like' wildcards
     * @param string $size A thumbnail slug; can be 'medium', 'thumbnail', etc; defaults to 'full'
     * @param string  $title An optional attribute to be used in the generated HTML
     * @param string $class An optional class to apply to the generated HTML
     * @return strubg The generated image markup
     */
    public static function generate_image_html_by_slug( $slug, $size = 'full', $title = '', $class = '' )
    {
        //  Try to find the image by the slug..
        $image_id = self::find_first_image_id_like_slug( $slug );

        //  If an image_ID was found, then construct the HTML..
        $image_html = '';
        if ( ( $image_id != null ) && ( $image_id > 0 ) )
        {
                $image_html =   wp_get_attachment_image
                                (
                                    $image_id,
                                    $size,
                                    0,
                                    array
                                    (
                                        'alt'   =>	$slug,
                                        'class' =>	$class,
                                        'title' =>	$title
                                    )
                                );
        }
	
        //  Simply return the markup..
        return $image_html;
    }

    /**
     * Returns a list of image sizes registered in the active WP database.
     * 
     * @link http://codex.wordpress.org/Function_Reference/get_intermediate_image_sizes
     * @param boolean $include_dimensions If set to 'true', an element in the list might look like this: 'medium 300x300'
     * @return array A list of sizes as string (e.g. 'thumbnail', 'medium', 'full', etc)
     */
    public static function get_image_sizes( $include_dimensions = false )
    {
        //  Get the list of image sizes.
        $image_sizes = array();
        
        //  Special sauce fpr piecing names with dimensions.
        if ( $include_dimensions )
        {
            global $_wp_additional_image_sizes;
            $sizes = array();
            foreach( get_intermediate_image_sizes() as $s )
            {
                $sizes[$s] = array( 0, 0 );
                if( in_array( $s, array( 'thumbnail', 'medium', 'large' ) ) )
                {
                    $sizes[$s][0] = get_option( $s.'_size_w' );
                    $sizes[$s][1] = get_option( $s.'_size_h' );
                }
                else
                {
                    if( isset( $_wp_additional_image_sizes ) && isset( $_wp_additional_image_sizes[$s] ) )
                    {
                        $sizes[$s] = array( $_wp_additional_image_sizes[$s]['width'], $_wp_additional_image_sizes[$s]['height'], );
                    }
                }
            }
            foreach( $sizes as $size => $atts )
            {
                $image_sizes[] = ( $size.' '.implode( 'x', $atts ) );
            }
        }
        
        //  Otherwise, the user just wanted the names.
        else
        {
            $image_sizes = get_intermediate_image_sizes();
        }

        //  Note: 'full' is not an officially registered image size, but is recognized in the codex - append it.
        $image_sizes[] = __( 'full', 'ski' );

        //  And return.
        return $image_sizes;
    }

    /**
     * Attachments can have 'alternative text' specified by the user.  Unfortunately, this
     * value does not live in the attachment/post object - instead, it is stored as a
     * custom field and the key is not so obvious.  Thus, this accessor.
     * 
     * @link http://wordpress.org/support/topic/get-alternate-text-from-attachments
     * @param integer $attachment_id The ID of the attachment whose alt text is sought
     * @return string The alt text, if found; otherwise, an empty string
     */
    public static function get_attachment_alt_text( $attachment_id )
    {
        return get_post_meta( $attachment_id, '_wp_attachment_image_alt', true );
    }

    /* PRIVATE */

    /**
     * Only use this class as a utility..
     */
    private function __construct()
    {
        //  Intentionally blank..
    }
}

?>