Add clear method to EntityDocument (#776)

* Add Clearable interface for entities

* Fix whitespace

* Rename to ClearableEntity

* Make clear part of EntityDocument.

* Improve ItemTest::testClear

Author: jakobw

src/Entity/EntityDocument.php

@@ -88,4 +88,11 @@ public function equals( $target );
 	 */
 	public function copy();
 
+	/**
+	 * Clears all fields of the entity that can be emptied. The entity's id stays the same.
+	 *
+	 * @since 7.4
+	 */
+	public function clear();
+
 }

src/Entity/Item.php

@@ -342,4 +342,13 @@ public function __clone() {
 		$this->statements = clone $this->statements;
 	}
 
+	/**
+	 * @since 7.4
+	 */
+	public function clear() {
+		$this->fingerprint = new Fingerprint();
+		$this->siteLinks = new SiteLinkList();
+		$this->statements = new StatementList();
+	}
+
 }

src/Entity/Property.php

@@ -297,4 +297,12 @@ public function __clone() {
 		$this->statements = clone $this->statements;
 	}
 
+	/**
+	 * @since 7.4
+	 */
+	public function clear() {
+		$this->fingerprint = new Fingerprint();
+		$this->statements = new StatementList();
+	}
+
 }

tests/unit/Entity/ItemTest.php

@@ -7,6 +7,7 @@
 use Wikibase\DataModel\Entity\Item;
 use Wikibase\DataModel\Entity\ItemId;
 use Wikibase\DataModel\SiteLink;
+use Wikibase\DataModel\SiteLinkList;
 use Wikibase\DataModel\Snak\PropertyNoValueSnak;
 use Wikibase\DataModel\Snak\PropertySomeValueSnak;
 use Wikibase\DataModel\Statement\Statement;
@@ -742,4 +743,43 @@ public function testGetAliasGroups_sameListAsFingerprint() {
 		);
 	}
 
+	/**
+	 * @dataProvider clearableProvider
+	 */
+	public function testClear( Item $item ) {
+		$clone = $item->copy();
+
+		$item->clear();
+
+		$this->assertEquals( $clone->getId(), $item->getId(), 'cleared Item should keep its id' );
+		$this->assertTrue( $item->isEmpty(), 'cleared Item should be empty' );
+	}
+
+	public function clearableProvider() {
+		return [
+			'empty' => [ new Item( new ItemId( 'Q23' ) ), ],
+			'with fingerprint' => [
+				new Item(
+					new ItemId( 'Q42' ),
+					new Fingerprint( new TermList( [ new Term( 'en', 'foo' ) ] ) )
+				),
+			],
+			'with sitelink' => [
+				new Item(
+					new ItemId( 'Q123' ),
+					null,
+					new SiteLinkList( [ new SiteLink( 'enwiki', 'Wikidata' ) ] )
+				)
+			],
+			'with statement' => [
+				new Item(
+					new ItemId( 'Q321' ),
+					null,
+					null,
+					new StatementList( [ $this->newStatement() ] )
+				)
+			]
+		];
+	}
+
 }

tests/unit/Entity/PropertyTest.php

@@ -619,4 +619,48 @@ public function testGetAliasGroups_sameListAsFingerprint() {
 		);
 	}
 
+	/**
+	 * @dataProvider clearableProvider
+	 */
+	public function testClear( Property $property ) {
+		$clone = $property->copy();
+
+		$property->clear();
+
+		$this->assertEquals(
+			$clone->getId(),
+			$property->getId(),
+			'cleared Property should keep its id'
+		);
+		$this->assertEquals(
+			$clone->getDataTypeId(),
+			$property->getDataTypeId(),
+			'cleared Property should keep its data type'
+		);
+		$this->assertTrue( $property->isEmpty(), 'cleared Property should be empty' );
+	}
+
+	public function clearableProvider() {
+		return [
+			'empty' => [
+				new Property( new PropertyId( 'P123' ), null, 'string' ),
+			],
+			'with fingerprint' => [
+				new Property(
+					new PropertyId( 'P321' ),
+					new Fingerprint( new TermList( [ new Term( 'en', 'foo' ) ] ) ),
+					'time'
+				),
+			],
+			'with statement' => [
+				new Property(
+					new PropertyId( 'P234' ),
+					null,
+					'wikibase-entityid',
+					$this->newNonEmptyStatementList()
+				)
+			],
+		];
+	}
+
 }