1. <?php
  2. /**
  3.  * File containing the ezcQuerySubSelect class.
  4.  *
  5.  * @package Database
  6.  * @version 1.4
  7.  * @copyright Copyright (C) 2005-2008 eZ systems as. All rights reserved.
  8.  * @license http://ez.no/licenses/new_bsd New BSD License
  9.  */
 10.  
 11. /**
 12.  * Class to create subselects within queries.
 13.  *
 14.  * The ezcSubQuery used for creating correct subqueries inside ezcQuery object.
 15.  * Class holds a refenence to inclusive ezcQuery and transfer
 16.  * PDO related calls to it.
 17.  *
 18.  *
 19.  * Example:
 20.  * <code>
 21.  * $q = ezcDbInstance::get()->createSelectQuery();
 22.  * $q2 = $q->subSelect();
 23.  *
 24.  * $q2->select( 'lastname' )->from( 'users' );
 25.  *
 26.  * // This will produce SQL:
 27.  * // SELECT * FROM Greetings WHERE age > 10 AND user IN ( ( SELECT lastname FROM users ) )
 28.  * $q->select( '*' )->from( 'Greetings' );
 29.  *     ->where( $q->expr->gt( 'age', 10 ),
 30.  *              $q->expr->in( 'user', $q2 ) );
 31.  *
 32.  * $stmt = $q->prepare(); // $stmt is a normal PDOStatement
 33.  * $stmt->execute();
 34.  * </code>
 35.  *
 36.  * @package Database
 37.  * @version 1.4
 38.  */
 39. class ezcQuerySubSelect extends ezcQuerySelect
 40. {
 41.     /**
 42.      * Holds the outer query.
 43.      *
 44.      * @var ezcQuery 
 45.      */
 46.     protected $outerQuery = null;
 47.  
 48.     /**
 49.      * Constructs a new ezcQuery object.
 50.      *
 51.      * @param ezcQuery $outer reference to inclusive ezcQuery object.
 52.      */
 53.     public function __construct( ezcQuery $outer )
 54.     {
 55.         $this->outerQuery = $outer;
 56.  
 57.         if ( $this->expr === null )
 58.         {
 59.             $this->expr = $outer->db->createExpression();
 60.         }
 61.     }
 62.  
 63.     /**
 64.      * Binds the parameter $param to the specified variable name $placeHolder..
 65.      *
 66.      * This method use ezcQuery::bindParam() from the ezcQuery in which subselect included.
 67.      * Info about bounded parameters stored in ezcQuery.
 68.      *
 69.      * The parameter $param specifies the variable that you want to bind. If
 70.      * $placeholder is not provided bind() will automatically create a
 71.      * placeholder for you. An automatic placeholder will be of the name
 72.      * 'ezcValue1', 'ezcValue2' etc.
 73.      *
 74.      * Example:
 75.      * <code>
 76.      * $value = 2;
 77.      * $subSelect = $q->subSelect();
 78.      * $subSelect->select('*')
 79.      *              ->from( 'table2' )
 80.      *                ->where( $subSelect->expr->in('id', $subSelect->bindParam( $value )) );
 81.      *
 82.      * $q->select('*')
 83.      *     ->from( 'table' )
 84.      *       ->where ( $q->expr->eq( 'id', $subSelect ) );
 85.      *
 86.      * $stmt = $q->prepare(); // the parameter $value is bound to the query.
 87.      * $value = 4;
 88.      * $stmt->execute(); // subselect executed with 'id = 4'
 89.      * </code>
 90.      *
 91.      * @see ezcQuery::bindParam()
 92.      *
 93.      * @param &mixed $param 
 94.      * @param string $placeHolder the name to bind with. The string must start with a colon ':'.
 95.      * @return string the placeholder name used.
 96.      */
 97.     public function bindParam( &$param, $placeHolder = null, $type = PDO::PARAM_STR )
 98.     {
 99.         return $this->outerQuery->bindParam( $param, $placeHolder, $type );
100.     }
101.  
102.     /**
103.      * Binds the value $value to the specified variable name $placeHolder.
104.      *
105.      * This method use ezcQuery::bindValue() from the ezcQuery in which subselect included.
106.      * Info about bounded parameters stored in ezcQuery.
107.      *
108.      * The parameter $value specifies the value that you want to bind. If
109.      * $placeholder is not provided bindValue() will automatically create a
110.      * placeholder for you. An automatic placeholder will be of the name
111.      * 'ezcValue1', 'ezcValue2' etc.
112.      *
113.      * Example:
114.      * <code>
115.      *
116.      * $value = 2;
117.      * $subSelect = $q->subSelect();
118.      * $subSelect->select( name )
119.      *              ->from( 'table2' )
120.      *                ->where(  $subSelect->expr->in('id', $subSelect->bindValue( $value )) );
121.      *
122.      * $q->select('*')
123.      *     ->from( 'table1' )
124.      *       ->where ( $q->expr->eq( 'name', $subSelect ) );
125.      *
126.      * $stmt = $q->prepare(); // the $value is bound to the query.
127.      * $value = 4;
128.      * $stmt->execute(); // subselect executed with 'id = 2'
129.      * </code>
130.      *
131.      * @see ezcQuery::bindValue()
132.      *
133.      * @param mixed $value 
134.      * @param string $placeHolder the name to bind with. The string must start with a colon ':'.
135.      * @return string the placeholder name used.
136.      */
137.     public function bindValue( $value, $placeHolder = null, $type = PDO::PARAM_STR )
138.     {
139.         return $this->outerQuery->bindValue( $value, $placeHolder, $type );
140.     }
141.  
142.  
143.     /**
144.      * Return SQL string for subselect.
145.      *
146.      * Typecasting to (string) should be used to make __toString() to be called
147.      * with PHP 5.1.  This will not be needed in PHP 5.2 and higher when this
148.      * object is used in a string context.
149.      *
150.      * Example:
151.      * <code>
152.      * $subSelect = $q->subSelect();
153.      * $subSelect->select( name )->from( 'table2' );
154.      * $q->select('*')
155.      *     ->from( 'table1' )
156.      *       ->where ( $q->expr->eq( 'name', (string)$subSelect ) );
157.      * $stmt = $q->prepare();
158.      * $stmt->execute();
159.      * </code>
160.      *
161.      * @return string SQL string for subselect.
162.      */
163.     public function __toString()
164.     {
165.         return $this->getQuery();
166.     }
167.  
168.     /**
169.      * Return string with SQL query for subselect.
170.      *
171.      * Example:
172.      * <code>
173.      * $subSelect = $q->subSelect();
174.      * $subSelect->select( name )->from( 'table2' );
175.      * $q->select('*')
176.      *     ->from( 'table1' )
177.      *       ->where ( $q->expr->eq( 'name', $subSelect ) );
178.      * $stmt = $q->prepare();
179.      * $stmt->execute();
180.      * </code>
181.      *
182.      * @return string SQL string for subselect.
183.      */
184.     public function getQuery()
185.     {
186.         return '( '.parent::getQuery().' )';
187.     }
188.  
189.     /**
190.     * Returns ezcQuerySubSelect of deeper level.
191.     *
192.     * Used for making subselects inside subselects.
193.     *
194.     * Example:
195.     * <code>
196.     *
197.     * $value = 2;
198.     * $subSelect = $q->subSelect();
199.     * $subSelect->select( name )
200.     *              ->from( 'table2' )
201.     *                ->where( $subSelect->expr->in('id', $subSelect->bindValue( $value )) );
202.     *
203.     * $q->select(*)
204.     *     ->from( 'table1' )
205.     *       ->where ( $q->expr->eq( 'name', $subSelect ) );
206.     *
207.     * $stmt = $q->prepare(); // the $value is bound to the query.
208.     * $value = 4;
209.     * $stmt->execute(); // subselect executed with 'id = 2'
210.     * </code>
211.     *
212.     * @return ezcQuerySubSelect 
213.     */
214.     public function subSelect()
215.     {
216.         return new ezcQuerySubSelect( $this->outerQuery );
217.     }
218.  
219. }
220.  
221. ?>