diff --git a/docs/en/topics/datamodel.md b/docs/en/topics/datamodel.md index 6f025111b..42237206a 100755 --- a/docs/en/topics/datamodel.md +++ b/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 diff --git a/model/DataList.php b/model/DataList.php index effb3abaf..5e83a5d7a 100644 --- a/model/DataList.php +++ b/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. * diff --git a/model/DataQuery.php b/model/DataQuery.php index 95f11bb01..cea43dd26 100644 --- a/model/DataQuery.php +++ b/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 diff --git a/model/ManyManyList.php b/model/ManyManyList.php index 9e1e7325a..76e4db2b8 100644 --- a/model/ManyManyList.php +++ b/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 $joinTable The name of the table whose entries define the content of this - * many_many relation. - * @param $localKey The key in the join table that maps to the dataClass' PK. - * @param $foreignKey The key in the join table that maps to joined class' PK. - * @param $extraFields A map of field => fieldtype of extra fields on the join table. + * @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. + * + * @example new ManyManyList('Group','Group_Members', 'GroupID', 'MemberID'); */ function __construct($dataClass, $joinTable, $localKey, $foreignKey, $extraFields = array()) { parent::__construct($dataClass); diff --git a/tests/model/DataListTest.php b/tests/model/DataListTest.php index c6d7f8910..1d99c88da 100755 --- a/tests/model/DataListTest.php +++ b/tests/model/DataListTest.php @@ -1,6 +1,7 @@ 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 diff --git a/tests/model/DataObjectTest.php b/tests/model/DataObjectTest.php index 6e91812ec..ca49fe580 100644 --- a/tests/model/DataObjectTest.php +++ b/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) */ diff --git a/tests/model/ManyManyListTest.php b/tests/model/ManyManyListTest.php new file mode 100644 index 000000000..f9240eb02 --- /dev/null +++ b/tests/model/ManyManyListTest.php @@ -0,0 +1,98 @@ +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'); + } +} \ No newline at end of file