<?php error_reporting(E_ALL);
/**
 * This file is part of the Dynamic Networks RSS Framework for PHP
 * 
 * @author Gordon Oheim (hide@address.com)
 * @copyright Copyright 2005, Dynamic Networks
 * @link http://www.dynamicnetworks.de
 * @license http://creativecommons.org/licenses/GPL/2.0/ GNU General Public License
 * @filesource
 * @version 1.0.0
 */

/**
 * A class  representing a media:people object
 * 
 * This class represents a people object of the Yahoo Media RSS module.
 * Mediapeople lists the notable individuals/businesses and their contribution
 * to the creation of the media object. It is an optional subelement of the item
 * object or the mediacontent object. If first case, the text applies to all
 * enclosed media elements.
 *
 * @package rssFramework
 * @author Gordon Oheim (hide@address.com)
 * @link http://tools.search.yahoo.com/mrss/
 * @see mediacategory
 * @see mediacontent
 * @see mediarss
 * @see mediathumbnail
 */ 
class mediapeople extends xmlbaseclass {
	
 	/**
 	 * Specifies the role individuals played.
 	 * 
 	 * Examples include: producer, artist, news anchor, cast member, etc. It is
 	 * an optional attribute.
 	 * 
 	 * @var string
 	 * @access private
 	 */
 	 var $role;
 	 
 	 /**
 	 * A string listing the people who are attributed by this element.
 	 *
 	 * According to the draft specification, this is a string, where names are
 	 * divided by a pipe symbol. This makes accessing the people difficult, so
 	 * this framework uses an array instead. When transforming into RSS, the
 	 * content of this framework is transformed into the string notation.
 	 * 
 	 * @var string[]
 	 * @access private
 	 */
 	 var $people;
 	 
 	 /**
 	  * creates a new media:people object
 	  * 
 	  * The constructor creates a new mediapeople object. Set role and names via
 	  * the specified set methods.
 	  * 
 	  * @access public
 	  */
 	  function mediapeople() {
		$this->people = array();
 	  }

  	/**
  	 * Sets the role attribute of the mediapeople object
  	 * 
  	 * This function will set the param $role to the attribute $role of the
  	 * mediapeople object.
  	 * 
  	 * @param string $role
  	 * @access public
  	 * @see $role
  	 * @see get_role()
  	 */
  	function set_role($role) {
 	  	if (is_string($role)) {
 	  		$this->role = $role;
 	  	} else {
 	  		die("FATAL ERROR: added param is not a string");
 	  	}
  	}

  	/**
  	 * Returns the role attribute of the mediapeople object
  	 * 
  	 * This function will return the value of the $role attribute
  	 * 
  	 * @access public
  	 * @see $role
  	 * @see set_role()
  	 */
  	function get_role() {
		return $this->role;
  	}
  	
 	/**
 	 * Adds a person name to the $people array.
 	 * 
 	 * This function adds a string to the $people array.
 	 *
 	 * @param string $person
	 * @see $people[]
 	 * @see get_people()
 	 * @see set_people()
 	 * @see remove_person()
 	 * @access public
 	 */
 	function set_person($person) {
 	  	if (is_string($person)) {
			$this->people[] = $person;
  		} else {
  			die("FATAL ERROR: added param is not a string");
  		}
 	}
 	
 	 /**
 	 * Adds an array of strings denoting people to the channel.
 	 * 
 	 * This function adds all strings in $array to the $people array.
 	 *
 	 * @param string[] $array
	 * @see $people
 	 * @see get_people()
 	 * @see set_person()
 	 * @see remove_person()
 	 * @access public
 	 */
 	function set_people($array) {
 		foreach ($array as $person) {
 			$this->set_person($person);
 		}
 	}
  	
	/**
	 * Removes a person from the $people array.
	 * 
	 * This function removes the item object located at the specified index by
	 * the param and reindexes the array. The function will return true on
	 * success. This class is a wrapper for the function remove_from_array().
	 * Note: As of this writing there are no shorts in PHP. Use integer instead.
	 * 
	 * @access public
	 * @param short $index
	 * @return bool
	 * @see get_people()
	 * @see set_people()
	 * @see set_person()
	 * @see remove_from_array();
	 * @see $people
	 */	
	function remove_person($index) {
		return $this->remove_from_array($this->people, $index);	
	}

	/**
	 * Unsets an array element.
	 * 
	 * This function removes the element located at the $index of the specified
	 * array and returns true on success. This method is private and should not
	 * be called by your program. Use the appropriate methods for the elements
	 * you want to remove instead.
	 * 
	 * @access private
	 * @param array $array
	 * @param short $index
	 * @return bool
	 * @see remove_person()
	 */
	function remove_from_array(&$array, $index) {
		if (is_integer($index)) {
			if (isset($array[$index])) {
				unset($array[$index]);
				$array = array_values($array);
				return true;
			} else {
				return false;
			}
		} else {
			return false;
		}
	}  	
}
?>