	Source Code Coverage
	Designed for use with PHPUnit2, Xdebug and Phing.

Methods: 29

LOC: 393

Statements: 67

Source file

Statements

Methods

Total coverage

Field.php

94.0%

100.0%

95.8%

<?php
/**
 * Xyster 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://www.opensource.org/licenses/bsd-license.php
 * 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 xyster@devweblog.org so we can send you a copy immediately.
 *
 * @category  Xyster
 * @package   Xyster_Data
 * @copyright Copyright (c) 2007 Irrational Logic (http://devweblog.org)
 * @license   http://www.opensource.org/licenses/bsd-license.php New BSD License
 */

/**
 * @see Xyster_Data_Aggregate
 */
require_once 'Xyster/Data/Aggregate.php';

/**
 * A simple concept for data fields and columns
 *
 * @category  Xyster
 * @package   Xyster_Data
 * @copyright Copyright (c) 2007 Irrational Logic (http://devweblog.org)
 * @license   http://www.opensource.org/licenses/bsd-license.php New BSD License
 */
class Xyster_Data_Field
{
    /**
     * The name of the field
     *
     * @var string
     */
    protected $_name;
    /**
     * An alias for the field, equal to the field name by default
     *
     * @var string
     */
    protected $_alias;

    /**
     * Creates a new Field
     *
     * @param string $name  The field name (be it a property, column, whatever)
     * @param string $alias  The alias for this field
     */
    protected function __construct( $name, $alias=null )
    {
        $this->_name = trim($name);
        if ( !strlen($this->_name) ) {
            require_once 'Xyster/Data/Field/Exception.php';
            throw new Xyster_Data_Field_Exception('A field name cannot be empty');
        }
        $this->_alias = ( !strlen(trim($alias)) ) ? $name : trim($alias);
    }

    /**
     * Gets the name of this field
     *
     * @return string The field name
     */
    public function getName()
    {
        return $this->_name;
    }
    /**
     * Gets the alias assigned to this field
     *
     * @return string The field alias
     */
    public function getAlias()
    {
        return $this->_alias;
    }
    /**
     * Sets the alias assigned to this column
     *
     * @param string $alias  The alias to assign
     * @throws Xyster_Data_Field_Exception if the alias is invalid
     */
    public function setAlias( $alias )
    {
        if ( !strlen(trim($alias)) ) {
            require_once 'Xyster/Data/Field/Exception.php';
            throw new Xyster_Data_Field_Exception('An alias cannot be empty');
        }
        $this->_alias = trim($alias);
    }
    /**
     * Evaluates the reference for the given object
     *
     * @param mixed $object
     * @return mixed
     */
    public function evaluate( $object )
    {
        $value = null;
        if ( is_array($object) || $object instanceof ArrayAccess ) {
            if ( !isset($object[$this->_name]) && !array_key_exists($this->_name, $object) ) {
                require_once 'Xyster/Data/Field/Exception.php';
                throw new Xyster_Data_Field_Exception("Field name '{$this->_name}' is invalid");
            }
            $value = $object[$this->_name];
        } else if ( is_object($object) && preg_match('/^[a-z_]\w*$/i', $this->_name) ) {
            // name of a real property or one caught by __get()
            $value = $object->{$this->_name};
        } else if ( is_object($object) ) {
            // this is eval'ed becuse $this->_name might be a method call
            // maybe sometime in the future we can do this better...
            eval("\$value = \$object->{$this->_name};");
        } else {
            require_once 'Xyster/Data/Field/Exception.php';
            throw new Xyster_Data_Field_Exception("Only objects or arrays can be evaluated");
        }
        return $value;
    }
    /**
     * String representation of this object
     *
     * @magic
     * @return string
     */
    public function __toString()
    {
        return $this->getName();
    }
    /**
     * Factories an ascending {@link Xyster_Data_Sort} for this field name
     *
     * @return Xyster_Data_Sort
     */
    public function asc()
    {
        require_once 'Xyster/Data/Sort.php';
        return Xyster_Data_Sort::asc($this);
    }
    /**
     * Factories a descending {@link Xyster_Data_Sort} for this field name
     *
     * @return Xyster_Data_Sort
     */
    public function desc()
    {
        require_once 'Xyster/Data/Sort.php';
        return Xyster_Data_Sort::desc($this);
    }
    /**
     * Factories an Equal To Xyster_Data_Expression ( column = 'value' )
     *
     * @param mixed $value
     * @return Xyster_Data_Expression
     */
    public function eq( $value )
    {
        return $this->_expression(__FUNCTION__, array($this, $value));
    }
    /**
     * Factories a Not Equal To Xyster_Data_Expression ( column <> 'value' )
     *
     * @param mixed $value
     * @return Xyster_Data_Expression
     */
    public function neq( $value )
    {
        return $this->_expression(__FUNCTION__, array($this, $value));
    }
    /**
     * Factories a Less Than Xyster_Data_Expression ( column < 3 )
     *
     * @param mixed $value
     * @return Xyster_Data_Expression
     */
    public function lt( $value )
    {
        return $this->_expression(__FUNCTION__, array($this, $value));
    }
    /**
     * Factories a Less Than or Equal To Xyster_Data_Expression ( column <= 3 )
     *
     * @param mixed $value
     * @return Xyster_Data_Expression
     */
    public function lte( $value )
    {
        return $this->_expression(__FUNCTION__, array($this, $value));
    }
    /**
     * Factories a Greater Than Xyster_Data_Expression ( column > 2 )
     *
     * @param mixed $value
     * @return Xyster_Data_Expression
     */
    public function gt( $value )
    {
        return $this->_expression(__FUNCTION__, array($this, $value));
    }
    /**
     * Factories a Greater Than or Equal To Xyster_Data_Expression ( column >= 2 )
     *
     * @param mixed $value
     * @return Xyster_Data_Expression
     */
    public function gte( $value )
    {
        return $this->_expression(__FUNCTION__, array($this, $value));
    }
    /**
     * Factories a LIKE Xyster_Data_Expression ( column LIKE '%value' )
     *
     * @param mixed $value
     * @return Xyster_Data_Expression
     */
    public function like( $value )
    {
        return $this->_expression(__FUNCTION__, array($this, $value));
    }
    /**
     * Factories a NOT LIKE Xyster_Data_Expression ( column NOT LIKE '%value' )
     *
     * @param mixed $value
     * @return Xyster_Data_Expression
     */
    public function notLike( $value )
    {
        return $this->_expression(__FUNCTION__, array($this, $value));
    }
    /**
     * Factories a BETWEEN Xyster_Data_Expression ( column BETWEEN 'value' AND 'value' )
     *
     * @param mixed $start
     * @param mixed $end
     * @return Xyster_Data_Expression
     */
    public function between( $start, $end )
    {
        return $this->_expression(__FUNCTION__, array($this, $start, $end));
    }
    /**
     * Factories a NOT BETWEEN Xyster_Data_Expression ( column NOT BETWEEN 'value' AND 'value' )
     *
     * @param mixed $start
     * @param mixed $end
     * @return Xyster_Data_Expression
     */
    public function notBetween( $start, $end )
    {
        return $this->_expression(__FUNCTION__, array($this, $start, $end));
    }
    /**
     * Factories an In expression ( column IN ( 1,1,2,3,5,8,13,21,'fibonacci','sequence' ) )
     *
     * @param array $choices
     * @return Xyster_Data_Expression
     */
    public function in( array $choices )
    {
        return $this->_expression(__FUNCTION__, array($this, $choices));
    }
    /**
     * Factories a Not in expression ( column NOT IN ( 1,1,2,3,5,8,13,21,'fibonacci','sequence' ) )
     *
     * @param array $choices
     * @return Xyster_Data_Expression
     */
    public function notIn( array $choices )
    {
        return $this->_expression(__FUNCTION__, array($this, $choices));
    }

    /**
     * Factories an expression
     *
     * @param string $function
     * @param array $params
     * @return Xyster_Data_Expression
     */
    protected function _expression( $function, array $params = array() )
    {
        require_once 'Xyster/Data/Expression.php';
        return call_user_func_array(
                array('Xyster_Data_Expression',$function),
                $params
            );
    }

    /**
     * Creates a Xyster_Data_Field by name with an alias
     *
     * @param string $name The name of the field
     * @param string $alias The alias to assign
     * @return Xyster_Data_Field
     */
    static public function named( $name, $alias = null )
    {
        require_once 'Xyster/Data/Field/Aggregate.php';
        if ( $match = Xyster_Data_Field_Aggregate::match($name) ) {
            require_once 'Xyster/Enum.php';
            $function = Xyster_Enum::valueOf('Xyster_Data_Aggregate', $match['function']);
            return self::aggregate($function, $match['field'], $alias);
        } else {
            return new Xyster_Data_Field($name, $alias);
        }
    }

    /**
     * Creates a Xyster_Data_Field that defines a group in a result
     *
     * @param string $name
     * @param string $alias
     * @return Xyster_Data_Field_Group
     */
    static public function group( $name, $alias = null )
    {
        require_once 'Xyster/Data/Field/Group.php';
        return new Xyster_Data_Field_Group($name, $alias);
    }
    /**
     * Creates an {@link Xyster_Data_Aggregate} field
     *
     * @param Xyster_Data_Aggregate $function The aggregate used
     * @param string $name The name of the field to aggregate
     * @param string $alias Optional; the alias of the aggregate field
     * @return Xyster_Data_Field_Aggregate
     */
    static public function aggregate( Xyster_Data_Aggregate $function, $name, $alias = null )
    {
        require_once 'Xyster/Data/Field/Aggregate.php';
        return new Xyster_Data_Field_Aggregate($function, $name, $alias);
    }
    /**
     * Creates an {@link Xyster_Data_Aggregate} field to count items in a tuple
     *
     * @param string $name The name of the field
     * @param string $alias The alias to assign
     * @return Xyster_Data_Field_Aggregate
     */
    static public function count( $name, $alias = null )
    {
        return self::aggregate(Xyster_Data_Aggregate::Count(), $name, $alias);
    }
    /**
     * Creates an {@link Xyster_Data_Aggregate} field to sum the values in a field
     *
     * @param string $name The name of the field
     * @param string $alias The alias to assign
     * @return Xyster_Data_Field_Aggregate
     */
    static public function sum( $name, $alias = null )
    {
        return self::aggregate(Xyster_Data_Aggregate::Sum(), $name, $alias);
    }
    /**
     * Creates an {@link Xyster_Data_Aggregate} field to average the values in a field
     *
     * @param string $name The name of the field
     * @param string $alias The alias to assign
     * @return Xyster_Data_Field_Aggregate
     */
    static public function avg( $name, $alias = null )
    {
        return self::aggregate(Xyster_Data_Aggregate::Average(), $name, $alias);
    }
    /**
     * Creates an {@link Xyster_Data_Aggregate} field to find the maximum value in a field
     *
     * @param string $name The name of the field
     * @param string $alias The alias to assign
     * @return Xyster_Data_Field_Aggregate
     */
    static public function max( $name, $alias = null )
    {
        return self::aggregate(Xyster_Data_Aggregate::Maximum(), $name, $alias);
    }
    /**
     * Creates an {@link Xyster_Data_Aggregate} field to find the minimum value in a field
     *
     * @param string $name The name of the field
     * @param string $alias The alias to assign
     * @return Xyster_Data_Field_Aggregate
     */
    static public function min( $name, $alias = null )
    {
        return self::aggregate(Xyster_Data_Aggregate::Minimum(), $name, $alias);
    }
}

Report generated at 2007-10-08T19:32:24-05:00

1		<?php
2		/**
3		* Xyster Framework
4		*
5		* LICENSE
6		*
7		* This source file is subject to the new BSD license that is bundled
8		* with this package in the file LICENSE.txt.
9		* It is also available through the world-wide-web at this URL:
10		* http://www.opensource.org/licenses/bsd-license.php
11		* If you did not receive a copy of the license and are unable to
12		* obtain it through the world-wide-web, please send an email
13		* to xyster@devweblog.org so we can send you a copy immediately.
14		*
15		* @category Xyster
16		* @package Xyster_Data
17		* @copyright Copyright (c) 2007 Irrational Logic (http://devweblog.org)
18		* @license http://www.opensource.org/licenses/bsd-license.php New BSD License
19		*/
20
21		/**
22		* @see Xyster_Data_Aggregate
23		*/
24	1	require_once 'Xyster/Data/Aggregate.php';
25
26		/**
27		* A simple concept for data fields and columns
28		*
29		* @category Xyster
30		* @package Xyster_Data
31		* @copyright Copyright (c) 2007 Irrational Logic (http://devweblog.org)
32		* @license http://www.opensource.org/licenses/bsd-license.php New BSD License
33		*/
34		class Xyster_Data_Field
35		{
36		/**
37		* The name of the field
38		*
39		* @var string
40		*/
41		protected $_name;
42		/**
43		* An alias for the field, equal to the field name by default
44		*
45		* @var string
46		*/
47		protected $_alias;
48
49		/**
50		* Creates a new Field
51		*
52		* @param string $name The field name (be it a property, column, whatever)
53		* @param string $alias The alias for this field
54		*/
55		protected function __construct( $name, $alias=null )
56		{
57	237	$this->_name = trim($name);
58	237	if ( !strlen($this->_name) ) {
59	1	require_once 'Xyster/Data/Field/Exception.php';
60	1	throw new Xyster_Data_Field_Exception('A field name cannot be empty');
61	0	}
62	237	$this->_alias = ( !strlen(trim($alias)) ) ? $name : trim($alias);
63		}
64
65		/**
66		* Gets the name of this field
67		*
68		* @return string The field name
69		*/
70		public function getName()
71		{
72	68	return $this->_name;
73		}
74		/**
75		* Gets the alias assigned to this field
76		*
77		* @return string The field alias
78		*/
79		public function getAlias()
80		{
81	10	return $this->_alias;
82		}
83		/**
84		* Sets the alias assigned to this column
85		*
86		* @param string $alias The alias to assign
87		* @throws Xyster_Data_Field_Exception if the alias is invalid
88		*/
89		public function setAlias( $alias )
90		{
91	4	if ( !strlen(trim($alias)) ) {
92	1	require_once 'Xyster/Data/Field/Exception.php';
93	1	throw new Xyster_Data_Field_Exception('An alias cannot be empty');
94	0	}
95	4	$this->_alias = trim($alias);
96		}
97		/**
98		* Evaluates the reference for the given object
99		*
100		* @param mixed $object
101		* @return mixed
102		*/
103		public function evaluate( $object )
104		{
105	76	$value = null;
106	76	if ( is_array($object) \|\| $object instanceof ArrayAccess ) {
107	32	if ( !isset($object[$this->_name]) && !array_key_exists($this->_name, $object) ) {
108	1	require_once 'Xyster/Data/Field/Exception.php';
109	1	throw new Xyster_Data_Field_Exception("Field name '{$this->_name}' is invalid");
110	0	}
111	31	$value = $object[$this->_name];
112	75	} else if ( is_object($object) && preg_match('/^[a-z_]\w*$/i', $this->_name) ) {
113		// name of a real property or one caught by __get()
114	45	$value = $object->{$this->_name};
115	46	} else if ( is_object($object) ) {
116		// this is eval'ed becuse $this->_name might be a method call
117		// maybe sometime in the future we can do this better...
118	6	eval("\$value = \$object->{$this->_name};");
119	6	} else {
120	1	require_once 'Xyster/Data/Field/Exception.php';
121	1	throw new Xyster_Data_Field_Exception("Only objects or arrays can be evaluated");
122		}
123	74	return $value;
124		}
125		/**
126		* String representation of this object
127		*
128		* @magic
129		* @return string
130		*/
131		public function __toString()
132		{
133	28	return $this->getName();
134		}
135		/**
136		* Factories an ascending {@link Xyster_Data_Sort} for this field name
137		*
138		* @return Xyster_Data_Sort
139		*/
140		public function asc()
141		{
142	3	require_once 'Xyster/Data/Sort.php';
143	3	return Xyster_Data_Sort::asc($this);
144		}
145		/**
146		* Factories a descending {@link Xyster_Data_Sort} for this field name
147		*
148		* @return Xyster_Data_Sort
149		*/
150		public function desc()
151		{
152	3	require_once 'Xyster/Data/Sort.php';
153	3	return Xyster_Data_Sort::desc($this);
154		}
155		/**
156		* Factories an Equal To Xyster_Data_Expression ( column = 'value' )
157		*
158		* @param mixed $value
159		* @return Xyster_Data_Expression
160		*/
161		public function eq( $value )
162		{
163	1	return $this->_expression(__FUNCTION__, array($this, $value));
164		}
165		/**
166		* Factories a Not Equal To Xyster_Data_Expression ( column <> 'value' )
167		*
168		* @param mixed $value
169		* @return Xyster_Data_Expression
170		*/
171		public function neq( $value )
172		{
173	2	return $this->_expression(__FUNCTION__, array($this, $value));
174		}
175		/**
176		* Factories a Less Than Xyster_Data_Expression ( column < 3 )
177		*
178		* @param mixed $value
179		* @return Xyster_Data_Expression
180		*/
181		public function lt( $value )
182		{
183	1	return $this->_expression(__FUNCTION__, array($this, $value));
184		}
185		/**
186		* Factories a Less Than or Equal To Xyster_Data_Expression ( column <= 3 )
187		*
188		* @param mixed $value
189		* @return Xyster_Data_Expression
190		*/
191		public function lte( $value )
192		{
193	1	return $this->_expression(__FUNCTION__, array($this, $value));
194		}
195		/**
196		* Factories a Greater Than Xyster_Data_Expression ( column > 2 )
197		*
198		* @param mixed $value
199		* @return Xyster_Data_Expression
200		*/
201		public function gt( $value )
202		{
203	1	return $this->_expression(__FUNCTION__, array($this, $value));
204		}
205		/**
206		* Factories a Greater Than or Equal To Xyster_Data_Expression ( column >= 2 )
207		*
208		* @param mixed $value
209		* @return Xyster_Data_Expression
210		*/
211		public function gte( $value )
212		{
213	1	return $this->_expression(__FUNCTION__, array($this, $value));
214		}
215		/**
216		* Factories a LIKE Xyster_Data_Expression ( column LIKE '%value' )
217		*
218		* @param mixed $value
219		* @return Xyster_Data_Expression
220		*/
221		public function like( $value )
222		{
223	1	return $this->_expression(__FUNCTION__, array($this, $value));
224		}
225		/**
226		* Factories a NOT LIKE Xyster_Data_Expression ( column NOT LIKE '%value' )
227		*
228		* @param mixed $value
229		* @return Xyster_Data_Expression
230		*/
231		public function notLike( $value )
232		{
233	2	return $this->_expression(__FUNCTION__, array($this, $value));
234		}
235		/**
236		* Factories a BETWEEN Xyster_Data_Expression ( column BETWEEN 'value' AND 'value' )
237		*
238		* @param mixed $start
239		* @param mixed $end
240		* @return Xyster_Data_Expression
241		*/
242		public function between( $start, $end )
243		{
244	2	return $this->_expression(__FUNCTION__, array($this, $start, $end));
245		}
246		/**
247		* Factories a NOT BETWEEN Xyster_Data_Expression ( column NOT BETWEEN 'value' AND 'value' )
248		*
249		* @param mixed $start
250		* @param mixed $end
251		* @return Xyster_Data_Expression
252		*/
253		public function notBetween( $start, $end )
254		{
255	1	return $this->_expression(__FUNCTION__, array($this, $start, $end));
256		}
257		/**
258		* Factories an In expression ( column IN ( 1,1,2,3,5,8,13,21,'fibonacci','sequence' ) )
259		*
260		* @param array $choices
261		* @return Xyster_Data_Expression
262		*/
263		public function in( array $choices )
264		{
265	2	return $this->_expression(__FUNCTION__, array($this, $choices));
266		}
267		/**
268		* Factories a Not in expression ( column NOT IN ( 1,1,2,3,5,8,13,21,'fibonacci','sequence' ) )
269		*
270		* @param array $choices
271		* @return Xyster_Data_Expression
272		*/
273		public function notIn( array $choices )
274		{
275	1	return $this->_expression(__FUNCTION__, array($this, $choices));
276		}
277
278		/**
279		* Factories an expression
280		*
281		* @param string $function
282		* @param array $params
283		* @return Xyster_Data_Expression
284		*/
285		protected function _expression( $function, array $params = array() )
286		{
287	15	require_once 'Xyster/Data/Expression.php';
288	15	return call_user_func_array(
289	15	array('Xyster_Data_Expression',$function),
290		$params
291	15	);
292		}
293
294		/**
295		* Creates a Xyster_Data_Field by name with an alias
296		*
297		* @param string $name The name of the field
298		* @param string $alias The alias to assign
299		* @return Xyster_Data_Field
300		*/
301		static public function named( $name, $alias = null )
302		{
303	230	require_once 'Xyster/Data/Field/Aggregate.php';
304	230	if ( $match = Xyster_Data_Field_Aggregate::match($name) ) {
305	11	require_once 'Xyster/Enum.php';
306	11	$function = Xyster_Enum::valueOf('Xyster_Data_Aggregate', $match['function']);
307	11	return self::aggregate($function, $match['field'], $alias);
308	0	} else {
309	226	return new Xyster_Data_Field($name, $alias);
310		}
311		}
312
313		/**
314		* Creates a Xyster_Data_Field that defines a group in a result
315		*
316		* @param string $name
317		* @param string $alias
318		* @return Xyster_Data_Field_Group
319		*/
320		static public function group( $name, $alias = null )
321		{
322	11	require_once 'Xyster/Data/Field/Group.php';
323	11	return new Xyster_Data_Field_Group($name, $alias);
324		}
325		/**
326		* Creates an {@link Xyster_Data_Aggregate} field
327		*
328		* @param Xyster_Data_Aggregate $function The aggregate used
329		* @param string $name The name of the field to aggregate
330		* @param string $alias Optional; the alias of the aggregate field
331		* @return Xyster_Data_Field_Aggregate
332		*/
333		static public function aggregate( Xyster_Data_Aggregate $function, $name, $alias = null )
334		{
335	35	require_once 'Xyster/Data/Field/Aggregate.php';
336	35	return new Xyster_Data_Field_Aggregate($function, $name, $alias);
337		}
338		/**
339		* Creates an {@link Xyster_Data_Aggregate} field to count items in a tuple
340		*
341		* @param string $name The name of the field
342		* @param string $alias The alias to assign
343		* @return Xyster_Data_Field_Aggregate
344		*/
345		static public function count( $name, $alias = null )
346		{
347	10	return self::aggregate(Xyster_Data_Aggregate::Count(), $name, $alias);
348		}
349		/**
350		* Creates an {@link Xyster_Data_Aggregate} field to sum the values in a field
351		*
352		* @param string $name The name of the field
353		* @param string $alias The alias to assign
354		* @return Xyster_Data_Field_Aggregate
355		*/
356		static public function sum( $name, $alias = null )
357		{
358	3	return self::aggregate(Xyster_Data_Aggregate::Sum(), $name, $alias);
359		}
360		/**
361		* Creates an {@link Xyster_Data_Aggregate} field to average the values in a field
362		*
363		* @param string $name The name of the field
364		* @param string $alias The alias to assign
365		* @return Xyster_Data_Field_Aggregate
366		*/
367		static public function avg( $name, $alias = null )
368		{
369	3	return self::aggregate(Xyster_Data_Aggregate::Average(), $name, $alias);
370		}
371		/**
372		* Creates an {@link Xyster_Data_Aggregate} field to find the maximum value in a field
373		*
374		* @param string $name The name of the field
375		* @param string $alias The alias to assign
376		* @return Xyster_Data_Field_Aggregate
377		*/
378		static public function max( $name, $alias = null )
379		{
380	6	return self::aggregate(Xyster_Data_Aggregate::Maximum(), $name, $alias);
381		}
382		/**
383		* Creates an {@link Xyster_Data_Aggregate} field to find the minimum value in a field
384		*
385		* @param string $name The name of the field
386		* @param string $alias The alias to assign
387		* @return Xyster_Data_Field_Aggregate
388		*/
389		static public function min( $name, $alias = null )
390		{
391	3	return self::aggregate(Xyster_Data_Aggregate::Minimum(), $name, $alias);
392		}
393		}

Source Code Coverage