API CHANGE DataList::subtract and DataQuery::subtract for subtracting a list from another list

Minor Stripped out ManyManyList tests from DataListTest into it's own test case

docs/en/topics/datamodel.md

@@ -219,6 +219,23 @@ members whose first name is either Sam or Ingo.
 		'FirstName' => array('sam', 'ingo'),
 	));
 
+### Subtract
+
+You can subtract entries from a DataList by passing in another DataList to `subtract()`
+
+	:::php
+	$allSams = DataList::create('Member')->filter('FirstName', 'Sam');
+	$allMembers = DataList::create('Member');
+	$noSams = $allMembers->subtract($allSams);
+
+Though for the above example it would probably be easier to use `filter()` and `exclude()`. A better
+use case could be when you want to find all the members that does not exist in a Group. 
+
+	:::php
+	// ... Finding all members that does not belong to $group.
+	$otherMembers = DataList::create('Member')->subtract($group->Members());
+
+
 ### Relation filters
 
 So far we have only filtered a data list by fields on the object that you're requesting.  For simple cases, this might 

model/DataList.php

@@ -325,6 +325,27 @@ class DataList extends ViewableData implements SS_List {
 		return $this;
 	}
 	
+	/**
+	 * This method returns a list does not contain any DataObjects that exists in $list
+	 * 
+	 * It does not return the resulting list, it only adds the constraints on the database to exclude
+	 * objects from $list.
+	 * The $list passed needs to contain the same dataclass as $this
+	 *
+	 * @param SS_List $list
+	 * @return DataList 
+	 * @throws BadMethodCallException
+	 */
+	public function subtract(SS_List $list) {
+		if($this->dataclass() != $list->dataclass()) {
+			throw new InvalidArgumentException('The list passed must have the same dataclass as this class');
+		}
+		
+		$newlist = clone $this;
+		$newlist->dataQuery->subtract($list->dataQuery());
+		return $newlist;
+	}
+	
 	/**
 	 * Add an inner join clause to this data list's query.
 	 *

model/DataQuery.php

@@ -503,7 +503,20 @@ class DataQuery {
 		}
 		
 		return $modelClass;
-	}	
+	}
+	
+	/**
+	 * Removes the result of query from this query.
+	 * 
+	 * @param DataQuery $subtractQuery
+	 * @param string $field 
+	 */
+	public function subtract(DataQuery $subtractQuery, $field='ID') {
+		$subSelect= $subtractQuery->getFinalisedQuery();
+		$subSelect->select($this->expressionForField($field, $subSelect));
+		$this->ensureSelectContainsOrderbyColumns($subSelect);
+		$this->where($this->expressionForField($field, $this).' NOT IN ('.$subSelect->sql().')');
+	}
 
 	/**
 	 * Select the given fields from the given table

model/ManyManyList.php

@@ -4,11 +4,32 @@
  * Subclass of {@link DataList} representing a many_many relation
  */
 class ManyManyList extends RelationList {
+	
 	protected $joinTable;
+	
 	protected $localKey;
+	
 	protected $foreignKey, $foreignID;
 
 	protected $extraFields;
+	
+	/**
+	 * Synonym of the constructor.  Can be chained with literate methods.
+	 * ManyManyList::create("Group","Member","ID", "GroupID")->sort("Title") is legal, but
+	 * new ManyManyList("Group","Member","ID", "GroupID")->sort("Title") is not.
+	 * 
+	 * @param string $dataClass The class of the DataObjects that this will list.
+	 * @param string $joinTable The name of the table whose entries define the content of this many_many relation.
+	 * @param string $localKey The key in the join table that maps to the dataClass' PK.
+	 * @param string $foreignKey The key in the join table that maps to joined class' PK.
+	 * @param string $extraFields A map of field => fieldtype of extra fields on the join table.
+	 * 
+	 * @see ManyManyList::__construct();
+	 * @example ManyManyList::create('Group','Group_Members', 'GroupID', 'MemberID');
+	 */
+	public static function create($dataClass, $joinTable, $localKey, $foreignKey, $extraFields = array()) {
+		return new ManyManyList($dataClass, $joinTable, $localKey, $foreignKey, $extraFields = array());
+	}
 
 	/**
 	 * Create a new ManyManyList object.
@@ -16,18 +37,17 @@ class ManyManyList extends RelationList {
 	 * A ManyManyList object represents a list of DataObject records that correspond to a many-many
 	 * relationship.  In addition to, 
 	 * 
-	 * 
-	 * 
 	 * Generation of the appropriate record set is left up to the caller, using the normal
 	 * {@link DataList} methods.  Addition arguments are used to support {@@link add()}
 	 * and {@link remove()} methods.
 	 * 
-	 * @param $dataClass The class of the DataObjects that this will list.
+	 * @param string $dataClass The class of the DataObjects that this will list.
-	 * @param $joinTable The name of the table whose entries define the content of this
+	 * @param string $joinTable The name of the table whose entries define the content of this many_many relation.
-	 * many_many relation.
+	 * @param string $localKey The key in the join table that maps to the dataClass' PK.
-	 * @param $localKey The key in the join table that maps to the dataClass' PK.
+	 * @param string $foreignKey The key in the join table that maps to joined class' PK.
-	 * @param $foreignKey The key in the join table that maps to joined class' PK.
+	 * @param string $extraFields A map of field => fieldtype of extra fields on the join table.
-	 * @param $extraFields A map of field => fieldtype of extra fields on the join table.
+	 * 
+	 * @example new ManyManyList('Group','Group_Members', 'GroupID', 'MemberID');
 	 */
 	function __construct($dataClass, $joinTable, $localKey, $foreignKey, $extraFields = array()) {
 		parent::__construct($dataClass);

tests/model/DataListTest.php

@@ -1,6 +1,7 @@
 <?php
 
 class DataListTest extends SapphireTest {
+	
 	// Borrow the model from DataObjectTest
 	static $fixture_file = 'DataObjectTest.yml';
 
@@ -15,6 +16,20 @@ class DataListTest extends SapphireTest {
 		'DataObjectTest_Player',
 		'DataObjectTest_TeamComment'
 	);
+	
+	public function testSubtract(){
+		$subtractList = DataList::create("DataObjectTest_TeamComment")->filter('ID',1);
+		$fullList = DataList::create("DataObjectTest_TeamComment");
+		$newList = $fullList->subtract($subtractList);
+		$this->assertEquals(2, $newList->Count(), 'List should only contain two objects after subtraction');
+	}
+	
+	public function testSubtractBadDataclassThrowsException(){
+		$this->setExpectedException('InvalidArgumentException');
+		$teamsComments = DataList::create("DataObjectTest_TeamComment");
+		$teams = DataList::create("DataObjectTest_Team");
+		$teamsComments->subtract($teams);
+	}
 
 	function testListCreationSortAndLimit() {
 		// By default, a DataList will contain all items of that class

tests/model/DataObjectTest.php

@@ -272,73 +272,6 @@ class DataObjectTest extends SapphireTest {
 		$this->assertEquals($team1->getComponent('Captain')->FirstName, 'Player 1', 'Player 1 is the captain');
 	}
 	
-	/**
-	 * @todo Test removeMany() and addMany() on $many_many relationships
-	 */
-	function testManyManyRelationships() {
-	   $player1 = $this->objFromFixture('DataObjectTest_Player', 'player1');
-	   $player2 = $this->objFromFixture('DataObjectTest_Player', 'player2');
-	   $team1 = $this->objFromFixture('DataObjectTest_Team', 'team1');
-	   $team2 = $this->objFromFixture('DataObjectTest_Team', 'team2');
-	   
-	   // Test adding single DataObject by reference
-	   $player1->Teams()->add($team1);
-	   $player1->flushCache();
-	   
-	   $compareTeams = new ManyManyList('DataObjectTest_Team','DataObjectTest_Team_Players', 'DataObjectTest_TeamID', 'DataObjectTest_PlayerID');
-	   $compareTeams->forForeignID($player1->ID);
-	   $compareTeams->byID($team1->ID);
-	   $this->assertEquals(
-	      $player1->Teams()->column('ID'),
-	      $compareTeams->column('ID'),
-	      "Adding single record as DataObject to many_many"
-	   );
-	   
-	   // test removing single DataObject by reference
-	   $player1->Teams()->remove($team1);
-	   $player1->flushCache();
-	   $compareTeams = new ManyManyList('DataObjectTest_Team','DataObjectTest_Team_Players', 'DataObjectTest_TeamID', 'DataObjectTest_PlayerID');
-	   $compareTeams->forForeignID($player1->ID);
-	   $compareTeams->byID($team1->ID);
-	   $this->assertEquals(
-	      $player1->Teams()->column('ID'),
-	      $compareTeams->column('ID'),
-	      "Removing single record as DataObject from many_many"
-	   );
-	   
-	   // test adding single DataObject by ID
-	   $player1->Teams()->add($team1->ID);
-	   $player1->flushCache();
-	   $compareTeams = new ManyManyList('DataObjectTest_Team','DataObjectTest_Team_Players', 'DataObjectTest_TeamID', 'DataObjectTest_PlayerID');
-	   $compareTeams->forForeignID($player1->ID);
-	   $compareTeams->byID($team1->ID);
-	   $this->assertEquals(
-	      $player1->Teams()->column('ID'),
-	      $compareTeams->column('ID'),
-	      "Adding single record as ID to many_many"
-	   );
-	   
-	   // test removing single DataObject by ID
-	   $player1->Teams()->removeByID($team1->ID);
-	   $player1->flushCache();
-	   $compareTeams = new ManyManyList('DataObjectTest_Team','DataObjectTest_Team_Players', 'DataObjectTest_TeamID', 'DataObjectTest_PlayerID');
-	   $compareTeams->forForeignID($player1->ID);
-	   $compareTeams->byID($team1->ID);
-	   $this->assertEquals(
-	      $player1->Teams()->column('ID'),
-	      $compareTeams->column('ID'),
-	      "Removing single record as ID from many_many"
-	   );
-	
-		// Set a many-many relationship by and idList
-		$player1->Teams()->setByIdList(array($team1->ID, $team2->ID));
-		$this->assertEquals(array($team1->ID, $team2->ID), $player1->Teams()->column());
-		$player1->Teams()->setByIdList(array($team1->ID));
-		$this->assertEquals(array($team1->ID), $player1->Teams()->column());
-		$player1->Teams()->setByIdList(array($team2->ID));
-		$this->assertEquals(array($team2->ID), $player1->Teams()->column());
-	}
-	
 	/**
 	 * @todo Extend type change tests (e.g. '0'==NULL)
 	 */

tests/model/ManyManyListTest.php

@@ -0,0 +1,98 @@
+<?php
+
+class ManyManyListTest extends SapphireTest {
+	
+	// Borrow the model from DataObjectTest
+	public static $fixture_file = 'DataObjectTest.yml';
+
+	protected $extraDataObjects = array(
+		'DataObjectTest_Team',
+		'DataObjectTest_SubTeam',
+		'DataObjectTest_Player',
+	);
+	
+	public function testCreateList() {
+		$list = ManyManyList::create('DataObjectTest_Team','DataObjectTest_Team_Players', 'DataObjectTest_TeamID', 'DataObjectTest_PlayerID');
+		$this->assertEquals(2, $list->count());
+	}
+	
+	public function testAddingSingleDataObjectByReference() {
+		$player1 = $this->objFromFixture('DataObjectTest_Player', 'player1');
+		$team1 = $this->objFromFixture('DataObjectTest_Team', 'team1');
+		$player1->Teams()->add($team1);
+		$player1->flushCache();
+
+		$compareTeams = new ManyManyList('DataObjectTest_Team','DataObjectTest_Team_Players', 'DataObjectTest_TeamID', 'DataObjectTest_PlayerID');
+		$compareTeams->forForeignID($player1->ID);
+		$compareTeams->byID($team1->ID);
+		$this->assertEquals($player1->Teams()->column('ID'),$compareTeams->column('ID'),"Adding single record as DataObject to many_many");
+	}
+	
+	public function testRemovingSingleDataObjectByReference() {
+		$player1 = $this->objFromFixture('DataObjectTest_Player', 'player1');
+		$team1 = $this->objFromFixture('DataObjectTest_Team', 'team1');
+		$player1->Teams()->remove($team1);
+		$player1->flushCache();
+		$compareTeams = new ManyManyList('DataObjectTest_Team','DataObjectTest_Team_Players', 'DataObjectTest_TeamID', 'DataObjectTest_PlayerID');
+		$compareTeams->forForeignID($player1->ID);
+		$compareTeams->byID($team1->ID);
+		$this->assertEquals($player1->Teams()->column('ID'),$compareTeams->column('ID'),"Removing single record as DataObject from many_many");
+	}
+	
+	public function testAddingSingleDataObjectByID() {
+		$player1 = $this->objFromFixture('DataObjectTest_Player', 'player1');
+		$team1 = $this->objFromFixture('DataObjectTest_Team', 'team1');
+		$player1->Teams()->add($team1->ID);
+		$player1->flushCache();
+		$compareTeams = new ManyManyList('DataObjectTest_Team','DataObjectTest_Team_Players', 'DataObjectTest_TeamID', 'DataObjectTest_PlayerID');
+		$compareTeams->forForeignID($player1->ID);
+		$compareTeams->byID($team1->ID);
+		$this->assertEquals($player1->Teams()->column('ID'), $compareTeams->column('ID'), "Adding single record as ID to many_many");
+	}
+	
+	public function testRemoveByID() {
+		$player1 = $this->objFromFixture('DataObjectTest_Player', 'player1');
+		$team1 = $this->objFromFixture('DataObjectTest_Team', 'team1');
+		$player1->Teams()->removeByID($team1->ID);
+		$player1->flushCache();
+		$compareTeams = new ManyManyList('DataObjectTest_Team','DataObjectTest_Team_Players', 'DataObjectTest_TeamID', 'DataObjectTest_PlayerID');
+		$compareTeams->forForeignID($player1->ID);
+		$compareTeams->byID($team1->ID);
+		$this->assertEquals($player1->Teams()->column('ID'), $compareTeams->column('ID'), "Removing single record as ID from many_many");
+	}
+	
+	public function testSetByIdList() {
+		$player1 = $this->objFromFixture('DataObjectTest_Player', 'player1');
+		$team1 = $this->objFromFixture('DataObjectTest_Team', 'team1');
+		$team2 = $this->objFromFixture('DataObjectTest_Team', 'team2');
+		$player1->Teams()->setByIdList(array($team1->ID, $team2->ID));
+		$this->assertEquals(array($team1->ID, $team2->ID), $player1->Teams()->column());
+		$player1->Teams()->setByIdList(array($team1->ID));
+		$this->assertEquals(array($team1->ID), $player1->Teams()->column());
+		$player1->Teams()->setByIdList(array($team2->ID));
+		$this->assertEquals(array($team2->ID), $player1->Teams()->column());
+	}
+	
+	public function testSubtractOnAManyManyList() {
+		$allList = ManyManyList::create('DataObjectTest_Player', 'DataObjectTest_Team_Players','DataObjectTest_PlayerID', 'DataObjectTest_TeamID');
+		$this->assertEquals(3, $allList->count(), 'Precondition; we have all 3 players connected to a team in the list');
+
+		$teamOneID = $this->idFromFixture('DataObjectTest_Team', 'team1');
+		$teamTwoID = $this->idFromFixture('DataObjectTest_Team', 'team2');
+		
+		// Captain 1 belongs to one team; team1
+		$captain1 = $this->objFromFixture('DataObjectTest_Player', 'captain1');
+		$this->assertEquals(array($teamOneID),$captain1->Teams()->column("ID"), 'Precondition; player2 belongs to team1');
+		
+		// Player 2 belongs to both teams: team1, team2
+		$player2 = $this->objFromFixture('DataObjectTest_Player', 'player2');
+		$this->assertEquals(array($teamOneID,$teamTwoID), $player2->Teams()->column("ID"), 'Precondition; player2 belongs to team1 and team2');
+
+		// We want to find the teams for player2 where the captain does not belong to
+		$teamsWithoutTheCaptain = $player2->Teams()->subtract($captain1->Teams());
+		
+		// Assertions
+		$this->assertEquals(1,$teamsWithoutTheCaptain->count(), 'The ManyManyList should onlu contain one team');
+		$this->assertEquals($teamTwoID, $teamsWithoutTheCaptain->first()->ID, 'The ManyManyList contains the wrong team');
+	}
+}