<?php

/**
 * Zend Framework
 *
 * LICENSE
 *
 * This source file is subject to the new BSD license that is bundled
 * with this package in the file LICENSE.txt.
 * It is also available through the world-wide-web at this URL:
 * http://framework.zend.com/license/new-bsd
 * If you did not receive a copy of the license and are unable to
 * obtain it through the world-wide-web, please send an email
 * to license@zend.com so we can send you a copy immediately.
 *
 * @category   Zend
 * @package    Zend_View
 * @subpackage Helper
 * @copyright  Copyright (c) 2005-2007 Zend Technologies USA Inc. (http://www.zend.com)
 * @license    http://framework.zend.com/license/new-bsd     New BSD License
 */

/**
 * @uses Zend_View_Helper_HtmlElement
 */
require_once 'Zend/View/Helper/HtmlElement.php';

/**
 * View helper for generating Gravatar (http://www.gravatar.com) avatar URLs
 *
 * @category   Zend
 * @package    Zend_View
 * @subpackage Helper
 * @copyright  Copyright (c) 2005-2007 Zend Technologies USA Inc. (http://www.zend.com)
 * @license    http://framework.zend.com/license/new-bsd     New BSD License
 */

class Zend_View_Helper_Gravatar extends Zend_View_Helper_HtmlElement
{
    /**
     * Default gravatar value constants
     */
    const DEFAULT_404       = '404';
    const DEFAULT_MM        = 'mm';
    const DEFAULT_IDENTICON = 'identicon';
    const DEFAULT_MONSTERID = 'monsterid';
    const DEFAULT_WAVATAR   = 'wavatar';

    /**
     * Rating constants
     */
    const RATING_G  = 'g';
    const RATING_PG = 'pg';
    const RATING_R  = 'r';
    const RATING_X  = 'x';
    
    /**
     * Gravatar Service URL
     * 
     * @var string
     */
    protected $_serviceUrl = 'http://www.gravatar.com/avatar/';
    
    /**
     * Size in pixels
     * 
     * @var integer
     */
    protected $_size = 80;
    
    /**
     * Default gravatar to use. Can be a URL or one of the DEFAULT_* constants
     * 
     * @var string
     */
    protected $_default = self::DEFAULT_MM;
    
    /**
     * Maximal rating for the gravatar. Can be one of the RATING_* constants
     *
     * @var string
     */
    protected $_rating = self::RATING_G;

    /**
     * Email address
     * 
     * @var string
     */
    protected $_email = null;
    
    /**
     * Get access to the gravat object, optionally setting Gravatar properties
     * 
     * @param  string  $email
     * @param  integer $size
     * @param  string  $default
     * @param  string  $rating
     * @return Zend_View_Helper_Gravatar
     */
    public function gravatar($email = null, $size = null, $default = null, $rating = null)
    {
        if ($email)   $this->setEmail($email);
        if ($size)    $this->setSize($size);
        if ($default) $this->setDefault($default);
        if ($rating)  $this->setRating($rating);
        
        return $this;
    }

    /**
     * Set the email address to be used for the gravatar
     * 
     * We assume the email address is valid and comes from a safe place. It is
     * not the role of this component to validate the email address. Passing
     * an invalid email address will most likely result in getting the default
     * Gravatar instead of a real one.
     * 
     * @param  string $email
     * @return Zend_View_Helper_Gravatar
     */
    public function setEmail($email)
    {
        $this->_email = trim($email);
        return $this;
    }
    
    /**
     * Set the gravatar size
     * 
     * @param integer $size Size in pixels between 1 and 512
     * @return Zend_View_Helper_Gravatar
     */
    public function setSize($size)
    {
        $size = (int) $size;
        if ($size < 1 || $size > 512) {
            require_once 'Zend/View/Exception.php';
            throw new Zend_View_Exception("Gravatar size must be a number between 1 and 512");
        }
        
        $this->_size = $size;
        
        return $this;
    }
    
    /**
     * Set the default gravatar URL or type
     *  
     * Can be either an absolute URL to an image, or one of the DEFAULT_* constants
     * 
     * @param  string $default
     * @return Zend_View_Helper_Gravatar
     */
    public function setDefault($default)
    {
        $this->_default = $default;
        return $this;
    }
    
    /**
     * Set the maximal rating (inclusive) of the Gravatar. 
     * 
     * Must be one of the RATING_* constants
     * 
     * @param string $rating Rating - can be g, pg, r or 'x'.
     * @return Zend_View_Helper_Gravatar
     */
    public function setRating($rating)
    {
        $rating = strtolower($rating);
        switch($rating) { 
            case self::RATING_G:
            case self::RATING_PG:
            case self::RATING_R:
            case self::RATING_X:
                $this->_rating = $rating;
                break;
                
            default:
                require_once 'Zend/View/Exception.php';
                throw new Zend_View_Exception("Gravatar rating must be one of g, pg, r or x");
        }
        
        return $this;
    }
    
    /**
     * Get a full <img> tag with the Gravatar URL, as opposed to just a URL
     * 
     * You should pass additional img tag attributes (namely 'alt') as an
     * associative array
     * 
     * @param  array $attribs
     * @return Zend_View_Helper_Gravatar
     */
    public function getImageTag(array $attribs = array())
    {
        return '<img src="' . $this->_getGravatarUrl() . '"' . 
            $this->_htmlAttribs($attribs) . $this->getClosingBracket();
    }
    
    /**
     * Stringify the Gravatar object - this returns a gravat URL
     * 
     * @return string
     */
    public function __toString()
    {
        return $this->_getGravatarUrl();
    }
    
    /**
     * Generate the full gravatar URL
     * 
     * @return string
     */
    protected function _getGravatarUrl()
    {
        if (! $this->_email) { 
            require_once 'Zend/View/Exception.php';
            throw new Zend_View_Exception("No Gravatar email address was set");
        }
        
        $email = md5(strtolower($this->_email));
        $url = $this->_serviceUrl . $email . 
               "?s={$this->_size}" . 
               "&d=" . urlencode($this->_default) .
               "&r={$this->_rating}";

        return $url;
    }
}