Ticket #3883: sfPropelFinder.php

<?php

/*
 * This file is part of the sfPropelFinder package.
 * 
 * (c) 2007 François Zaninotto <francois.zaninotto@symfony-project.com>
 * 
 * For the full copyright and license information, please view the LICENSE
 * file that was distributed with this source code.
 */
 
class sfPropelFinder
{
  protected $peerClass = null;
  protected $databaseMap = null;
  protected $criteria = null;
  protected $relations = null;
  protected $latestQuery = '';
  protected $criterions = array();
  protected $withClasses = array();
  protected $withColumns = array();

  public function __construct($class = '')
  {
    $this->criteria = new Criteria();
    if($class)
    {
      $this->setPeerClass($class.'Peer');
    }
    if($this->peerClass)
    {
      $this->initialize();
    }
  }
  
  public function initialize()
  {
    $mapBuilder = call_user_func(array($this->peerClass, 'getMapBuilder'));
    $mapBuilder->doBuild();
    $this->databaseMap = $mapBuilder->getDatabaseMap();
  }
  
  public function getPeerClass()
  {
    return $this->peerClass;
  }

  public function setPeerClass($peerClass)
  {
    $this->relations[]= $peerClass;
    $this->peerClass = $peerClass;
    
    return $this;
  }
  
  public function getCriteria()
  {
    return $this->buildCriteria();
  }
  
  public function setCriteria($criteria)
  {
    $this->criteria = $criteria;
    $this->criterions = array();
    
    return $this;
  }

  public function reinitCriteria()
  { 
    return $this->setCriteria(new Criteria());
  }
  
  public function getLatestQuery()
  {
    $con = Propel::getConnection();
    if(method_exists($con, 'getLastExecutedQuery'))
    {
      return $this->latestQuery;
    }
    else
    {
      throw new Exception('getLatestQuery() only works when debug mode is enabled');
    }
  }
  
  public function updateLatestQuery()
  {
    $con = Propel::getConnection();
    if(method_exists($con, 'getLastExecutedQuery'))
    {
      $this->latestQuery = $con->getLastExecutedQuery();
    }
  }
  
  public function addWithClass($class)
  {
    $this->withClasses []= $class;
    
    return $this;
  }
  
  public function getWithClasses()
  {
    return $this->withClasses;
  }
  
  public function reinitWithClasses()
  {
    $this->withClasses = array();
    
    return $this;
  }

  public function getWithColumns()
  {
    return $this->withColumns;
  }
  
  public function reinitWithColumns()
  {
    $this->withColumns = array();
    
    return $this;
  }
  
  // Finder Initializers
  
  /**
   * Mixed initializer
   * Accepts either a string (Propel class) or an array of Propel objects
   *
   * @param mixed $from The data to initialize the finder with
   * @return sfPropelFinder a finder object
   * @throws Exception If the data is neither a classname nor an array
   */
  public static function from($from)
  {
    if (is_string($from))
    {
      return self::fromClass($from);
    }
    if (is_array($from))
    {
      return self::fromCollection($from);
    }
    throw new Exception('from() only accepts a Propel object classname or an array of Propel objects');
  }

  /**
   * Class initializer
   *
   * @param string $from Propel classname on which the search will be done
   * @return sfPropelFinder a finder object
   */
  public static function fromClass($class)
  {
    $me = __CLASS__;
    $finder = new $me($class);
    
    return $finder;
  }
  
  /**
   * Collection initializer
   *
   * @param array $from Array of Propel objects of the same class
   * @param string $class Optional classname of the desired objects
   * @param string $class Optional column name of the primary key
   *
   * @return sfPropelFinder a finder object
   * @throws Exception If the array is empty, contains not Propel objects or composite objects
   */
  public static function fromCollection($collection, $class = '', $pkName = '')
  {
    $pks = array();
    foreach($collection as $object)
    {
      if($class != get_class($object))
      {
        if($class)
        {
          throw new Exception('A finder can only be initialized from an array of objects of a single class');
        }
        if($object instanceof BaseObject)
        {
          $class = get_class($object);
        }
        else
        {
          throw new Exception('A finder can only be initialized from an array of Propel objects');
        }
      }
      $pks []= $object->getPrimaryKey();
    }
    if(!$class)
    {
      throw new Exception('A finder cannot be initialized with an empty array');
    }
    
    $tempObject = new $class();
    foreach ($tempObject->getPeer()->getTableMap()->getColumns() as $column)
    {
      if($column->isPrimaryKey())
      {
        if($pkName)
        {
          throw new Exception('A finder cannot be initialized from an array of objects with several foreign keys');
        }
        else
        {
          $pkName = $column->getFullyQualifiedName();
        }
      }
    }
    
    return self::fromArray($pks, $class, $pkName);
  }
  
  /**
   * Array initializer
   *
   * @param array $array Array of Primary keys
   * @param string $class Propel classname on which the search will be done
   *
   * @return sfPropelFinder a finder object
   */
  public static function fromArray($array, $class, $pkName)
  {
    $finder = self::fromClass($class);
    $finder->add($pkName, $array, Criteria::IN);
    
    return $finder;
  }
  
  // Finder Executers
  
  public function count($con = null, $reinitCriteria = true)
  {
    $ret = call_user_func(array($this->getPeerClass(), 'doCount'), $this->getCriteria(), $con);
    $this->updateLatestQuery();
    if($reinitCriteria)
    {
      $this->reinitCriteria();
    }
    
    return $ret;
  }
  
  public function find($limit = null, $con = null, $reinitCriteria = false)
  {
    if($limit)
    {
      $this->criteria->setLimit($limit);
    }
    $ret = $this->doFind($this->getCriteria(), $con);
    $this->updateLatestQuery();
    if($reinitCriteria)
    {
      $this->reinitCriteria();
    }
    
    return $ret;
  }
  
  public function findOne($con = null, $reinitCriteria = true)
  {
    $this->criteria->setLimit(1);
    $ret = $this->doFind($this->getCriteria(), $con);
    $this->updateLatestQuery();
    if($reinitCriteria)
    {
      $this->reinitCriteria();
    }
    if ($ret)
    {
      return $ret[0];
    }
    return null;
  }
  
  public function findLast($column = null, $con = null, $reinitCriteria = true)
  {
    if($column)
    {
      $this->orderBy($column, 'desc');
    }
    else
    {
      $this->guessOrder('desc');
    }
    
    return $this->findOne($con, $reinitCriteria);
  }
  
  public function findFirst($column = null, $con = null, $reinitCriteria = true)
  {
    if($column)
    {
      $this->orderBy($column, 'asc');
    }
    else
    {
      $this->guessOrder('asc');
    }
    
    return $this->findOne($con, $reinitCriteria);
  }

  protected function guessOrder($direction = 'desc')
  {
    $columnNames = array();
    foreach ($this->getColumnsForPeerClass($this->getPeerClass()) as $c)
    {
      $columnNames []= $c->getPhpName();
    }
    foreach(sfConfig::get('app_sfPropelFinder_sort_column_guesses', array('UpdatedAt', 'UpdatedOn', 'CreatedAt', 'CreatedOn', 'Id')) as $testColumnName)
    {
      if(in_array($testColumnName, $columnNames))
      {
        $this->orderBy($testColumnName, $direction);
        return;
      }
    }
    
    throw new Exception('Unable to figure out the column to use to order rows');
  }
  
  public function findBy($columnName, $value, $limit = null, $con = null, $reinitCriteria = false)
  {
    $column = $this->getColName($columnName);
    $this->addCondition('and', $column, $value, Criteria::EQUAL);
    
    return $this->find($limit, $con, $reinitCriteria);
  }

  public function findOneBy($columnName, $value, $con = null, $reinitCriteria = false)
  {
    $column = $this->getColName($columnName);
    $this->addCondition('and', $column, $value, Criteria::EQUAL);
    
    return $this->findOne($con, $reinitCriteria);
  }
  
  public function findPk($pk, $con = null)
  {
    if(is_array($pk))
    {
      $ret = call_user_func(array($this->getPeerClass(), 'retrieveByPks'), $pk, $con);
    }
    else
    {
      $ret = call_user_func(array($this->getPeerClass(), 'retrieveByPk'), $pk, $con);
    }
    $this->updateLatestQuery();
    
    return $ret;
  }
  
  public function doFind($criteria, $con = null)
  {
    if($this->getWithClasses() || $this->getWithColumns())
    {
      $c = $this->prepareCompositeCriteria($criteria);
      $resultSet = call_user_func(array($this->getPeerClass(), 'doSelectRS'), $c, $con);
      
      // Hydrate the objects based on the resultset
      $omClass = call_user_func(array($this->getPeerClass(), 'getOMClass'));
      $cls = Propel::import($omClass);
      $objects = array();
      $withObjs = array();
      while ($resultSet->next())
      {
        // First come the columns of the main class
        $obj = new $cls();
        $startCol = $obj->hydrate($resultSet, 1);
        // Then the related classes added by way of 'with'
        $objectsInJoin = array($obj);
        foreach ($this->getWithClasses() as $className)
        {
          $withObj = new $className();
          $startCol = $withObj->hydrate($resultSet, $startCol);
          
          // initialize our object directory
          if (!isset($withObjs[$className]))
          {
            $withObjs[$className] = array();
          }
          
          // check if object is not already referenced in allObjects directory
          $isNewObject = true;
          foreach ($withObjs[$className] as $otherObject)
          {
            if ($otherObject->getPrimaryKey() === $withObj->getPrimaryKey())
            {
              $isNewObject = false;
              $withObj = $otherObject;
              break;
            }
          }
          $this->relateObjects($withObj, $objectsInJoin, $isNewObject);
          $objectsInJoin []= $withObj;
          if ($isNewObject)
          {
            $withObjs[$className][] = $withObj;
          }
        }
        // Then the columns added one by one by way of 'withColumn'
        foreach($this->getWithColumns() as $name => $column)
        {
          // Additional columns are stored in the object, in a special 'namespace'
          // see getColumn() for how to retrieve the value afterwards
          $asName = 'WithColumn'.$name;
          // Using the third parameter of withColumn() as a type. defaults to $rs->get() (= $rs->getString())
          $typedGetter = 'get'.ucfirst($column['type']);
          $obj->$asName = $resultSet->$typedGetter($startCol);
          $startCol++;
        }
        
        $objects []= $obj;
      }
      
      // activate custom column getter if asColumns were added
      if($this->getWithColumns() && !sfMixer::getCallable('Base'.$cls.':getColumn'))
      {
        sfMixer::register('Base'.$cls, array($this, 'getColumn'));
      }
      
      return $objects;
    }
    else
    {
      // No 'with', so we use the native Propel doSelect()
      return call_user_func(array($this->getPeerClass(), 'doSelect'), $criteria, $con);
    }
  }
  
  /**
   * Prepare the select columns and add the missing joins
   */
  protected function prepareCompositeCriteria($criteria)
  {
    $c = clone $criteria;
    $c->clearSelectColumns();
    // First come the columns of the main class
    call_user_func(array($this->getPeerClass(), 'addSelectColumns'), $c);
    // Then the related classes added by way of 'with'
    foreach ($this->getWithClasses() as $className)
    {
      $tempClass = new $className();
      call_user_func(array($tempClass->getPeer(), 'addSelectColumns'), $c);
      // if join() wasn't called previously on this class, do a simple join
      if(!in_array($className.'Peer', $this->relations))
      {
        list($column1, $column2) = $this->getRelation($className);
        $c->addJoin($column1, $column2);
        $this->relations[]= $className.'Peer';
      }
    }
    // Then the columns added one by one by way of 'withColumn'
    foreach($this->getWithColumns() as $name => $column)
    {
      // if the column is on a related object property 
      // and if join() wasn't called previously on this object, do a simple join
      $peerClass = $column['peerClass'];
      if($peerClass && !in_array($peerClass, $this->relations))
      {
        list($column1, $column2) = $this->getRelation(str_replace('Peer', '', $peerClass));
        $c->addJoin($column1, $column2);
        $this->relations[]= $peerClass;
      }
      $c->addAsColumn($name, $column['column']);
    }
    
    return $c;
  }
  
  protected function relateObjects($new, $existingObjects, $isNew)
  {
    // brute force (to be optimized later)
    foreach ($existingObjects as $existingObject)
    {
      $methodName = 'add'.get_class($existingObject);
      if(method_exists($new, $methodName))
      {
        if($isNew)
        {
          call_user_func(array($new, 'init'.get_class($existingObject).'s'));
        }
        call_user_func(array($new, $methodName), $existingObject);
        break;
      }
    }
  }
  
  public function delete($con = null, $reinitCriteria = true)
  {
    $deleteCriteria = $this->getCriteria();
    if($deleteCriteria->equals(new Criteria()))
    {
      // delete will delete nothing when passed an empty criteria
      // while it should, in fact, delete all
      $fieldNames = call_user_func(array($this->getPeerClass(), 'getFieldNames'), BasePeer::TYPE_COLNAME);
      $firstFieldName = $fieldNames[0];
      $deleteCriteria->add($firstFieldName, true, Criteria::BINARY_OR);
    }
    $ret = call_user_func(array($this->getPeerClass(), 'doDelete'), $deleteCriteria, $con);
    $this->updateLatestQuery();
    if($reinitCriteria)
    {
      $this->reinitCriteria();
    }
    
    return $ret;
  }
  
  // Hydrating
  
  public function with($classes)
  {
    if(!is_array($classes))
    {
      $classes = func_get_args();
    }
    foreach($classes as $class)
    {
      $this->addWithClass($class);
    }
    
    return $this;
  }

  public function withColumn($column, $alias = null, $type = null)
  {
    $isCalculationColumn = strpos($column, '(') !== false;
    if(!$alias)
    {
      if($isCalculationColumn)
      {
        throw new Exception('Calculated colums added with withColumn() need an alias as second parameter');
      }
      else
      {
        $alias = $column;
      }
    }
    if($isCalculationColumn)
    {
      $peerClass = null;
    }
    else
    {
      list($peerClass, $columnName) = $this->getColName($column, null, true);
    }
    $this->withColumns [$alias]= array(
      'column'    => $isCalculationColumn ? $column : $columnName,
      'type'      => $type,
      'peerClass' => $peerClass
    );
    
    return $this;
  }
  
  // Finder Filters
  
  /**
   * Finder Fluid Interface for Criteria::setDistinct()
   */
  public function distinct()
  {
    $this->criteria->setDistinct();
    
    return $this;
  }
  
  /**
   * Finder Fluid Interface for Criteria::add()
   * Infers $column, $value, $comparison from $columnName and some optional arguments
   * Examples:
   *   $articleFinder->where('IsPublished')
 &nbs