From 3ca5163004ca8490b7410464d5030acfb2c5fa2f Mon Sep 17 00:00:00 2001 From: Maciej Malarz Date: Tue, 19 Feb 2019 21:00:07 +0100 Subject: [PATCH] Mark methods and classes as internal --- UPGRADE-2.0.md | 10 ++ .../ODM/MongoDB/Hydrator/HydratorFactory.php | 2 + .../ODM/MongoDB/Mapping/ClassMetadata.php | 9 +- .../MongoDB/Mapping/ClassMetadataFactory.php | 2 + .../PersistentCollectionInterface.php | 15 +- .../Persisters/CollectionPersister.php | 2 + .../MongoDB/Persisters/DocumentPersister.php | 2 + .../MongoDB/Persisters/PersistenceBuilder.php | 2 + .../ODM/MongoDB/Proxy/FileLocator.php | 3 + .../MongoDB/Query/QueryExpressionVisitor.php | 2 + .../ODM/MongoDB/Query/ReferencePrimer.php | 2 + lib/Doctrine/ODM/MongoDB/UnitOfWork.php | 131 +++++++++++++----- 12 files changed, 129 insertions(+), 53 deletions(-) diff --git a/UPGRADE-2.0.md b/UPGRADE-2.0.md index b6f4877010..6899075d17 100644 --- a/UPGRADE-2.0.md +++ b/UPGRADE-2.0.md @@ -297,3 +297,13 @@ ocramius. If you are checking for proxies, the following changed: * The `isScheduledForDirtyCheck` and `scheduleForDirtyCheck` methods have been renamed to `isScheduledForSynchronization` and `scheduleForSynchronization`, respectively. + +## Internal classes and methods + +Number of public methods and classes saw an `@internal` annotation added. This +marks places which are considered private to ODM but can not become ones due to +language limitations. Those methods can still be used (at your own risk) however +the backward compatibility promise for them is relaxed: we reserve the right to +change internal method's signatures and/or remove them altogether in *minor* +releases. Should such change be made, a note shall be included in the `UPGRADE.md` +file describing changes contained in the release. diff --git a/lib/Doctrine/ODM/MongoDB/Hydrator/HydratorFactory.php b/lib/Doctrine/ODM/MongoDB/Hydrator/HydratorFactory.php index 5e2a40b54a..9017386f19 100644 --- a/lib/Doctrine/ODM/MongoDB/Hydrator/HydratorFactory.php +++ b/lib/Doctrine/ODM/MongoDB/Hydrator/HydratorFactory.php @@ -107,6 +107,8 @@ public function __construct(DocumentManager $dm, EventManager $evm, ?string $hyd /** * Sets the UnitOfWork instance. + * + * @internal */ public function setUnitOfWork(UnitOfWork $uow) : void { diff --git a/lib/Doctrine/ODM/MongoDB/Mapping/ClassMetadata.php b/lib/Doctrine/ODM/MongoDB/Mapping/ClassMetadata.php index b811f452da..325c8d9837 100644 --- a/lib/Doctrine/ODM/MongoDB/Mapping/ClassMetadata.php +++ b/lib/Doctrine/ODM/MongoDB/Mapping/ClassMetadata.php @@ -573,8 +573,9 @@ public function isIdentifier($fieldName) : bool } /** - * INTERNAL: * Sets the mapped identifier field of this class. + * + * @internal */ public function setIdentifier(?string $identifier) : void { @@ -1249,9 +1250,10 @@ public function mapManyReference(array $mapping) : void } /** - * INTERNAL: * Adds a field mapping without completing/validating it. * This is mainly used to add inherited field mappings to derived classes. + * + * @internal */ public function addInheritedFieldMapping(array $fieldMapping) : void { @@ -1265,10 +1267,11 @@ public function addInheritedFieldMapping(array $fieldMapping) : void } /** - * INTERNAL: * Adds an association mapping without completing/validating it. * This is mainly used to add inherited association mappings to derived classes. * + * @internal + * * @throws MappingException */ public function addInheritedAssociationMapping(array $mapping) : void diff --git a/lib/Doctrine/ODM/MongoDB/Mapping/ClassMetadataFactory.php b/lib/Doctrine/ODM/MongoDB/Mapping/ClassMetadataFactory.php index 01ed9601a4..a7fb898c33 100644 --- a/lib/Doctrine/ODM/MongoDB/Mapping/ClassMetadataFactory.php +++ b/lib/Doctrine/ODM/MongoDB/Mapping/ClassMetadataFactory.php @@ -30,6 +30,8 @@ * The ClassMetadataFactory is used to create ClassMetadata objects that contain all the * metadata mapping informations of a class which describes how a class should be mapped * to a document database. + * + * @internal */ class ClassMetadataFactory extends AbstractClassMetadataFactory { diff --git a/lib/Doctrine/ODM/MongoDB/PersistentCollection/PersistentCollectionInterface.php b/lib/Doctrine/ODM/MongoDB/PersistentCollection/PersistentCollectionInterface.php index a6c7f227f3..d029517229 100644 --- a/lib/Doctrine/ODM/MongoDB/PersistentCollection/PersistentCollectionInterface.php +++ b/lib/Doctrine/ODM/MongoDB/PersistentCollection/PersistentCollectionInterface.php @@ -71,14 +71,12 @@ public function isDirty(); public function setDirty($dirty); /** - * INTERNAL: * Sets the collection's owning entity together with the AssociationMapping that * describes the association between the owner and the elements of the collection. */ public function setOwner(object $document, array $mapping); /** - * INTERNAL: * Tells this collection to take a snapshot of its current state reindexing * itself numerically if using save strategy that is enforcing BSON array. * Reindexing is safe as snapshot is taken only after synchronizing collection @@ -87,14 +85,12 @@ public function setOwner(object $document, array $mapping); public function takeSnapshot(); /** - * INTERNAL: * Clears the internal snapshot information and sets isDirty to true if the collection * has elements. */ public function clearSnapshot(); /** - * INTERNAL: * Returns the last snapshot of the elements in the collection. * * @return array The last snapshot of the elements. @@ -102,37 +98,30 @@ public function clearSnapshot(); public function getSnapshot(); /** - * INTERNAL: - * getDeleteDiff - * * @return array */ public function getDeleteDiff(); /** - * INTERNAL: get objects that were removed, unlike getDeleteDiff this doesn't care about indices. + * Get objects that were removed, unlike getDeleteDiff this doesn't care about indices. * * @return array */ public function getDeletedDocuments(); /** - * INTERNAL: - * getInsertDiff - * * @return array */ public function getInsertDiff(); /** - * INTERNAL: get objects that were added, unlike getInsertDiff this doesn't care about indices. + * Get objects that were added, unlike getInsertDiff this doesn't care about indices. * * @return array */ public function getInsertedDocuments(); /** - * INTERNAL: * Gets the collection owner. */ public function getOwner() : ?object; diff --git a/lib/Doctrine/ODM/MongoDB/Persisters/CollectionPersister.php b/lib/Doctrine/ODM/MongoDB/Persisters/CollectionPersister.php index d4bb3ce1b4..d24d0d87a0 100644 --- a/lib/Doctrine/ODM/MongoDB/Persisters/CollectionPersister.php +++ b/lib/Doctrine/ODM/MongoDB/Persisters/CollectionPersister.php @@ -38,6 +38,8 @@ * removed, CollectionPersister::update() will be called, which may set the * entire collection or delete/insert individual elements, depending on the * mapping strategy. + * + * @internal */ class CollectionPersister { diff --git a/lib/Doctrine/ODM/MongoDB/Persisters/DocumentPersister.php b/lib/Doctrine/ODM/MongoDB/Persisters/DocumentPersister.php index cc0be9af8f..1600b86394 100644 --- a/lib/Doctrine/ODM/MongoDB/Persisters/DocumentPersister.php +++ b/lib/Doctrine/ODM/MongoDB/Persisters/DocumentPersister.php @@ -62,6 +62,8 @@ /** * The DocumentPersister is responsible for persisting documents. + * + * @internal */ class DocumentPersister { diff --git a/lib/Doctrine/ODM/MongoDB/Persisters/PersistenceBuilder.php b/lib/Doctrine/ODM/MongoDB/Persisters/PersistenceBuilder.php index f50e0db345..45b05e67f6 100644 --- a/lib/Doctrine/ODM/MongoDB/Persisters/PersistenceBuilder.php +++ b/lib/Doctrine/ODM/MongoDB/Persisters/PersistenceBuilder.php @@ -21,6 +21,8 @@ * PersistenceBuilder builds the queries used by the persisters to update and insert * documents when a DocumentManager is flushed. It uses the changeset information in the * UnitOfWork to build queries using atomic operators like $set, $unset, etc. + * + * @internal */ class PersistenceBuilder { diff --git a/lib/Doctrine/ODM/MongoDB/Proxy/FileLocator.php b/lib/Doctrine/ODM/MongoDB/Proxy/FileLocator.php index 9b454019b0..2fb8220ac9 100644 --- a/lib/Doctrine/ODM/MongoDB/Proxy/FileLocator.php +++ b/lib/Doctrine/ODM/MongoDB/Proxy/FileLocator.php @@ -8,6 +8,9 @@ use function mkdir; use function realpath; +/** + * @internal + */ final class FileLocator extends BaseFileLocator { public function __construct(string $proxiesDirectory) diff --git a/lib/Doctrine/ODM/MongoDB/Query/QueryExpressionVisitor.php b/lib/Doctrine/ODM/MongoDB/Query/QueryExpressionVisitor.php index ff11da62f2..2487399aad 100644 --- a/lib/Doctrine/ODM/MongoDB/Query/QueryExpressionVisitor.php +++ b/lib/Doctrine/ODM/MongoDB/Query/QueryExpressionVisitor.php @@ -13,6 +13,8 @@ /** * Converts Collection expressions to query expressions. + * + * @internal */ class QueryExpressionVisitor extends ExpressionVisitor { diff --git a/lib/Doctrine/ODM/MongoDB/Query/ReferencePrimer.php b/lib/Doctrine/ODM/MongoDB/Query/ReferencePrimer.php index 00cca2a61c..e35352fe9a 100644 --- a/lib/Doctrine/ODM/MongoDB/Query/ReferencePrimer.php +++ b/lib/Doctrine/ODM/MongoDB/Query/ReferencePrimer.php @@ -37,6 +37,8 @@ * * Priming can only be used for the owning side side of a relationship, since * the referenced identifiers are not immediately available on an inverse side. + * + * @internal */ class ReferencePrimer { diff --git a/lib/Doctrine/ODM/MongoDB/UnitOfWork.php b/lib/Doctrine/ODM/MongoDB/UnitOfWork.php index fde8a033f8..b743099ec8 100644 --- a/lib/Doctrine/ODM/MongoDB/UnitOfWork.php +++ b/lib/Doctrine/ODM/MongoDB/UnitOfWork.php @@ -275,6 +275,8 @@ public function __construct(DocumentManager $dm, EventManager $evm, HydratorFact /** * Factory for returning new PersistenceBuilder instances used for preparing data into * queries for insert persistence. + * + * @internal */ public function getPersistenceBuilder() : PersistenceBuilder { @@ -286,6 +288,8 @@ public function getPersistenceBuilder() : PersistenceBuilder /** * Sets the parent association for a given embedded document. + * + * @internal */ public function setParentAssociation(object $document, array $mapping, ?object $parent, string $propertyPath) : void { @@ -335,6 +339,8 @@ public function getCollectionPersister() : CollectionPersister /** * Set the document persister instance to use for the given document name + * + * @internal */ public function setDocumentPersister(string $documentName, Persisters\DocumentPersister $persister) : void { @@ -513,8 +519,9 @@ public function getDocumentChangeSet(object $document) : array } /** - * INTERNAL: * Sets the changeset for a document. + * + * @internal */ public function setDocumentChangeSet(object $document, array $changeset) : void { @@ -524,6 +531,8 @@ public function setDocumentChangeSet(object $document, array $changeset) : void /** * Get a documents actual data, flattening all the objects to arrays. * + * @internal + * * @return array */ public function getDocumentActualData(object $document) : array @@ -957,7 +966,6 @@ private function computeAssociationChanges(object $parentDocument, array $assoc, } /** - * INTERNAL: * Computes the changeset of an individual document, independently of the * computeChangeSets() routine that is used at the beginning of a UnitOfWork#commit(). * @@ -966,8 +974,6 @@ private function computeAssociationChanges(object $parentDocument, array $assoc, * whereby changes detected in this method prevail. * * @throws InvalidArgumentException If the passed document is not MANAGED. - * - * @ignore */ public function recomputeSingleDocumentChangeSet(ClassMetadata $class, object $document) : void { @@ -1144,6 +1150,8 @@ private function executeDeletions(ClassMetadata $class, array $documents, array * If the document already has an identifier, it will be added to the * identity map. * + * @internal + * * @throws InvalidArgumentException */ public function scheduleForInsert(ClassMetadata $class, object $document) : void @@ -1173,6 +1181,8 @@ public function scheduleForInsert(ClassMetadata $class, object $document) : void * Schedules a document for upsert into the database and adds it to the * identity map * + * @internal + * * @throws InvalidArgumentException */ public function scheduleForUpsert(ClassMetadata $class, object $document) : void @@ -1216,6 +1226,8 @@ public function isScheduledForUpsert(object $document) : bool /** * Schedules a document for being updated. * + * @internal + * * @throws InvalidArgumentException */ public function scheduleForUpdate(object $document) : void @@ -1258,8 +1270,9 @@ public function isScheduledForSynchronization(object $document) : bool } /** - * INTERNAL: * Schedules a document for deletion. + * + * @internal */ public function scheduleForDelete(object $document) : void { @@ -1301,6 +1314,8 @@ public function isScheduledForDelete(object $document) : bool /** * Checks whether a document is scheduled for insertion, update or deletion. + * + * @internal */ public function isDocumentScheduled(object $document) : bool { @@ -1312,14 +1327,13 @@ public function isDocumentScheduled(object $document) : bool } /** - * INTERNAL: * Registers a document in the identity map. * * Note that documents in a hierarchy are registered with the class name of * the root document. Identifiers are serialized before being used as array * keys to allow differentiation of equal, but not identical, values. * - * @ignore + * @internal */ public function addToIdentityMap(object $document) : bool { @@ -1400,13 +1414,12 @@ public function getDocumentState(object $document, ?int $assume = null) : int } /** - * INTERNAL: * Removes a document from the identity map. This effectively detaches the * document from the persistence management of Doctrine. * - * @throws InvalidArgumentException + * @internal * - * @ignore + * @throws InvalidArgumentException */ public function removeFromIdentityMap(object $document) : bool { @@ -1430,14 +1443,13 @@ public function removeFromIdentityMap(object $document) : bool } /** - * INTERNAL: * Gets a document in the identity map by its identifier hash. * + * @internal + * * @param mixed $id Document identifier * * @throws InvalidArgumentException If the class does not have an identifier. - * - * @ignore */ public function getById($id, ClassMetadata $class) : object { @@ -1451,17 +1463,16 @@ public function getById($id, ClassMetadata $class) : object } /** - * INTERNAL: * Tries to get a document by its identifier hash. If no document is found * for the given hash, FALSE is returned. * + * @internal + * * @param mixed $id Document identifier * * @return mixed The found document or FALSE. * * @throws InvalidArgumentException If the class does not have an identifier. - * - * @ignore */ public function tryGetById($id, ClassMetadata $class) { @@ -1476,6 +1487,8 @@ public function tryGetById($id, ClassMetadata $class) /** * Schedules a document for dirty-checking at commit-time. + * + * @internal */ public function scheduleForSynchronization(object $document) : void { @@ -1485,6 +1498,8 @@ public function scheduleForSynchronization(object $document) : void /** * Checks whether a document is registered in the identity map. + * + * @internal */ public function isInIdentityMap(object $document) : bool { @@ -1515,10 +1530,9 @@ private function getIdForIdentityMap(object $document) : string } /** - * INTERNAL: * Checks whether an identifier exists in the identity map. * - * @ignore + * @internal */ public function containsId($id, string $rootClassName) : bool { @@ -1528,6 +1542,8 @@ public function containsId($id, string $rootClassName) : bool /** * Persists a document as part of the current unit of work. * + * @internal + * * @throws MongoDBException If trying to persist MappedSuperclass. * @throws InvalidArgumentException If there is something wrong with document's identifier. */ @@ -1600,6 +1616,8 @@ private function doPersist(object $document, array &$visited) : void /** * Deletes a document as part of the current unit of work. + * + * @internal */ public function remove(object $document) { @@ -1650,6 +1668,8 @@ private function doRemove(object $document, array &$visited) : void /** * Merges the state of the given detached document into this UnitOfWork. + * + * @internal */ public function merge(object $document) : object { @@ -1846,6 +1866,8 @@ private function doMerge(object $document, array &$visited, ?object $prevManaged /** * Detaches a document from the persistence management. It's persistence will * no longer be managed by Doctrine. + * + * @internal */ public function detach(object $document) : void { @@ -1895,6 +1917,8 @@ private function doDetach(object $document, array &$visited) : void * Refreshes the state of the given document from the database, overwriting * any local, unpersisted changes. * + * @internal + * * @throws InvalidArgumentException If the document is not MANAGED. */ public function refresh(object $document) : void @@ -2098,6 +2122,8 @@ private function cascadeRemove(object $document, array &$visited) : void /** * Acquire a lock on the given document. * + * @internal + * * @throws LockException * @throws InvalidArgumentException */ @@ -2129,6 +2155,8 @@ public function lock(object $document, int $lockMode, ?int $lockVersion = null) /** * Releases a lock on the given document. * + * @internal + * * @throws InvalidArgumentException */ public function unlock(object $document) : void @@ -2142,6 +2170,8 @@ public function unlock(object $document) : void /** * Clears the UnitOfWork. + * + * @internal */ public function clear(?string $documentName = null) : void { @@ -2183,12 +2213,11 @@ public function clear(?string $documentName = null) : void } /** - * INTERNAL: * Schedules an embedded document for removal. The remove() operation will be * invoked on that document at the beginning of the next commit of this * UnitOfWork. * - * @ignore + * @internal */ public function scheduleOrphanRemoval(object $document) : void { @@ -2196,10 +2225,9 @@ public function scheduleOrphanRemoval(object $document) : void } /** - * INTERNAL: * Unschedules an embedded or referenced object for removal. * - * @ignore + * @internal */ public function unscheduleOrphanRemoval(object $document) : void { @@ -2236,8 +2264,9 @@ private function fixPersistentCollectionOwnership(PersistentCollectionInterface } /** - * INTERNAL: * Schedules a complete collection for removal when this UnitOfWork commits. + * + * @internal */ public function scheduleCollectionDeletion(PersistentCollectionInterface $coll) : void { @@ -2253,6 +2282,8 @@ public function scheduleCollectionDeletion(PersistentCollectionInterface $coll) /** * Checks whether a PersistentCollection is scheduled for deletion. + * + * @internal */ public function isCollectionScheduledForDeletion(PersistentCollectionInterface $coll) : bool { @@ -2260,8 +2291,9 @@ public function isCollectionScheduledForDeletion(PersistentCollectionInterface $ } /** - * INTERNAL: * Unschedules a collection from being deleted when this UnitOfWork commits. + * + * @internal */ public function unscheduleCollectionDeletion(PersistentCollectionInterface $coll) : void { @@ -2280,8 +2312,9 @@ public function unscheduleCollectionDeletion(PersistentCollectionInterface $coll } /** - * INTERNAL: * Schedules a collection for update when this UnitOfWork commits. + * + * @internal */ public function scheduleCollectionUpdate(PersistentCollectionInterface $coll) : void { @@ -2302,8 +2335,9 @@ public function scheduleCollectionUpdate(PersistentCollectionInterface $coll) : } /** - * INTERNAL: * Unschedules a collection from being updated when this UnitOfWork commits. + * + * @internal */ public function unscheduleCollectionUpdate(PersistentCollectionInterface $coll) : void { @@ -2323,6 +2357,8 @@ public function unscheduleCollectionUpdate(PersistentCollectionInterface $coll) /** * Checks whether a PersistentCollection is scheduled for update. + * + * @internal */ public function isCollectionScheduledForUpdate(PersistentCollectionInterface $coll) : bool { @@ -2330,10 +2366,11 @@ public function isCollectionScheduledForUpdate(PersistentCollectionInterface $co } /** - * INTERNAL: * Gets PersistentCollections that have been visited during computing change * set of $document * + * @internal + * * @return PersistentCollectionInterface[] */ public function getVisitedCollections(object $document) : array @@ -2344,9 +2381,10 @@ public function getVisitedCollections(object $document) : array } /** - * INTERNAL: * Gets PersistentCollections that are scheduled to update and related to $document * + * @internal + * * @return PersistentCollectionInterface[] */ public function getScheduledCollections(object $document) : array @@ -2359,6 +2397,8 @@ public function getScheduledCollections(object $document) : array /** * Checks whether the document is related to a PersistentCollection * scheduled for update or deletion. + * + * @internal */ public function hasScheduledCollections(object $document) : bool { @@ -2437,6 +2477,8 @@ public function getOwningDocument(object $document) : object * Gets the class name for an association (embed or reference) with respect * to any discriminator value. * + * @internal + * * @param array|null $data */ public function getClassNameForAssociation(array $mapping, $data) : string @@ -2471,12 +2513,9 @@ public function getClassNameForAssociation(array $mapping, $data) : string } /** - * INTERNAL: * Creates a document. Used for reconstitution of documents during hydration. * - * @internal Highly performance-sensitive method. - * - * @ignore + * @internal */ public function getOrCreateDocument(string $className, array $data, array &$hints = [], ?object $document = null) : object { @@ -2554,6 +2593,8 @@ public function getOrCreateDocument(string $className, array $data, array &$hint /** * Initializes (loads) an uninitialized persistent collection of a document. + * + * @internal */ public function loadCollection(PersistentCollectionInterface $collection) : void { @@ -2567,6 +2608,8 @@ public function loadCollection(PersistentCollectionInterface $collection) : void /** * Gets the identity map of the UnitOfWork. + * + * @internal */ public function getIdentityMap() : array { @@ -2586,6 +2629,9 @@ public function getOriginalDocumentData(object $document) : array return $this->originalDocumentData[$oid] ?? []; } + /** + * @internal + */ public function setOriginalDocumentData(object $document, array $data) : void { $oid = spl_object_hash($document); @@ -2594,12 +2640,11 @@ public function setOriginalDocumentData(object $document, array $data) : void } /** - * INTERNAL: * Sets a property value of the original data array of a document. * - * @param mixed $value + * @internal * - * @ignore + * @param mixed $value */ public function setOriginalDocumentProperty(string $oid, string $property, $value) : void { @@ -2619,6 +2664,8 @@ public function getDocumentIdentifier(object $document) /** * Checks whether the UnitOfWork has any pending insertions. * + * @internal + * * @return bool TRUE if this UnitOfWork has pending insertions, FALSE otherwise. */ public function hasPendingInsertions() : bool @@ -2629,6 +2676,8 @@ public function hasPendingInsertions() : bool /** * Calculates the size of the UnitOfWork. The size of the UnitOfWork is the * number of documents in the identity map. + * + * @internal */ public function size() : int { @@ -2640,7 +2689,6 @@ public function size() : int } /** - * INTERNAL: * Registers a document as managed. * * TODO: This method assumes that $id is a valid PHP identifier for the @@ -2650,6 +2698,8 @@ public function size() : int * In the future, we may want to round-trip $id through a PHP and database * conversion and throw an exception if it's inconsistent. * + * @internal + * * @param mixed $id The identifier values. */ public function registerManaged(object $document, $id, array $data) : void @@ -2669,8 +2719,9 @@ public function registerManaged(object $document, $id, array $data) : void } /** - * INTERNAL: * Clears the property changeset of the document with the given OID. + * + * @internal */ public function clearDocumentChangeSet(string $oid) { @@ -2739,6 +2790,8 @@ public function getScheduledDocumentDeletions() : array /** * Get the currently scheduled complete collection deletions + * + * @internal */ public function getScheduledCollectionDeletions() : array { @@ -2747,6 +2800,8 @@ public function getScheduledCollectionDeletions() : array /** * Gets the currently scheduled collection inserts, updates and deletes. + * + * @internal */ public function getScheduledCollectionUpdates() : array { @@ -2755,6 +2810,8 @@ public function getScheduledCollectionUpdates() : array /** * Helper method to initialize a lazy loading proxy or persistent collection. + * + * @internal */ public function initializeObject(object $obj) : void {