From 24a15f96d319e618318512a5aff7259c50edcb31 Mon Sep 17 00:00:00 2001 From: doctrine <> Date: Tue, 15 Oct 2024 22:32:47 +0000 Subject: [PATCH] New version of Doctrine website --- atom.xml | 2 +- contribute/index.html | 2 - contribute/maintainer/index.html | 2 - contribute/website/index.html | 2 - index.html | 2 +- policies.html | 2 - policies/deprecation.html | 2 - policies/releases.html | 2 - policies/security.html | 2 - projects/annotations.html | 6 +- projects/cache.html | 8 +- projects/coding-standard.html | 6 +- projects/collections.html | 6 +- projects/common.html | 6 +- projects/couchdb-client.html | 6 +- projects/data-fixtures.html | 6 +- projects/dbal.html | 10 +- projects/doctrine-bundle.html | 12 +- projects/doctrine-cache-bundle.html | 6 +- projects/doctrine-laminas-hydrator.html | 6 +- projects/doctrine-migrations-bundle.html | 6 +- projects/doctrine-module.html | 6 +- projects/doctrine-mongo-odm-module.html | 6 +- projects/doctrine-mongodb-bundle.html | 6 +- projects/doctrine-orm-module.html | 6 +- .../doctrine-persistence/en/1.0/index.html | 7 + .../en/1.0/reference/index.html | 7 + .../doctrine-persistence/en/1.1/index.html | 7 + .../en/1.1/reference/index.html | 7 + .../1.1/reference/object-change-tracking.html | 7 + .../doctrine-persistence/en/1.2/index.html | 7 + .../en/1.2/reference/index.html | 7 + .../1.2/reference/object-change-tracking.html | 7 + .../doctrine-persistence/en/1.3/index.html | 7 + .../en/1.3/reference/index.html | 7 + .../1.3/reference/object-change-tracking.html | 7 + .../doctrine-persistence/en/1.4/index.html | 7 + .../en/1.4/reference/index.html | 7 + .../1.4/reference/object-change-tracking.html | 7 + .../doctrine-persistence/en/2.0/index.html | 7 + .../en/2.0/reference/index.html | 7 + .../2.0/reference/object-change-tracking.html | 7 + .../doctrine-persistence/en/2.1/index.html | 7 + .../en/2.1/reference/index.html | 7 + .../2.1/reference/object-change-tracking.html | 7 + .../doctrine-persistence/en/2.2/index.html | 7 + .../en/2.2/reference/index.html | 7 + .../2.2/reference/object-change-tracking.html | 7 + .../doctrine-persistence/en/2.3/index.html | 7 + .../en/2.3/reference/index.html | 7 + .../2.3/reference/object-change-tracking.html | 7 + .../doctrine-persistence/en/2.4/index.html | 7 + .../en/2.4/reference/index.html | 7 + .../2.4/reference/object-change-tracking.html | 7 + .../doctrine-persistence/en/2.5/index.html | 7 + .../en/2.5/reference/index.html | 7 + .../2.5/reference/object-change-tracking.html | 7 + .../doctrine-persistence/en/3.0/index.html | 7 + .../en/3.0/reference/index.html | 7 + .../3.0/reference/object-change-tracking.html | 7 + .../doctrine-persistence/en/3.1/index.html | 7 + .../en/3.1/reference/index.html | 7 + .../3.1/reference/object-change-tracking.html | 7 + .../doctrine-persistence/en/3.2/index.html | 7 + .../en/3.2/reference/index.html | 7 + .../3.2/reference/object-change-tracking.html | 7 + .../doctrine-persistence/en/3.3/index.html | 7 + .../en/3.3/reference/index.html | 7 + .../3.3/reference/object-change-tracking.html | 7 + .../doctrine-persistence/en/3.4/index.html | 497 ++++++++ .../en/3.4/reference/index.html | 1054 +++++++++++++++++ .../3.4/reference/object-change-tracking.html | 599 ++++++++++ .../doctrine-persistence/en/latest/index.html | 13 +- .../en/latest/reference/index.html | 13 +- .../reference/object-change-tracking.html | 13 +- projects/doctrine1.html | 2 +- projects/event-manager.html | 12 +- projects/inflector.html | 6 +- projects/instantiator.html | 12 +- projects/lexer.html | 10 +- projects/migrations.html | 6 +- projects/mongodb-odm.html | 6 +- projects/orm.html | 8 +- projects/persistence.html | 19 +- projects/persistence/3.4.html | 326 +++++ projects/persistence/latest.html | 10 +- projects/phpcr-bundle.html | 6 +- projects/phpcr-odm.html | 6 +- projects/reflection.html | 6 +- projects/rst-parser.html | 6 +- rst-examples.html | 2 - sitemap.xml | 754 ++++++------ sponsorship.html | 4 +- 93 files changed, 3311 insertions(+), 513 deletions(-) create mode 100644 projects/doctrine-persistence/en/3.4/index.html create mode 100644 projects/doctrine-persistence/en/3.4/reference/index.html create mode 100644 projects/doctrine-persistence/en/3.4/reference/object-change-tracking.html create mode 100644 projects/persistence/3.4.html diff --git a/atom.xml b/atom.xml index 798da43b5a2..f4a65103940 100644 --- a/atom.xml +++ b/atom.xml @@ -3,7 +3,7 @@
Doctrine has been downloaded a total of 5,615,187,461 times!
+Doctrine has been downloaded a total of 5,618,349,949 times!
+ + | +You are browsing a version that has not yet been released. |
+
The Doctrine Persistence documentation is a reference guide to everything you need +to know about the project.
+ +If this documentation is not helping to answer questions you have about the +Doctrine Persistence project, don't panic. You can get help from different sources:
+ + + +The best way to get started is with the Introduction section +in the documentation. Use the sidebar to browse other documentation for the Doctrine Persistence project.
+ ++ + | +You are browsing a version that has not yet been released. |
+
The Doctrine Persistence project is a set of shared interfaces and functionality that the different Doctrine +object mappers share. You can use these interfaces and abstract classes to build your own mapper if you don't +want to use the full data mappers provided by Doctrine.
+ +The library can easily be installed with composer.
+ +$ composer require doctrine/persistence
The interfaces and functionality in this project evolved from building several different implementations of Doctrine +object mappers. The first implementation was the ORM then came the MongoDB ODM. A set of common interfaces were +extracted from both projects and released in the Doctrine Common project. Over the years, more common functionality +was extracted and eventually moved to this standalone project. +After that, that project was itself split into several projects +including this one.
+ + +A Doctrine object mapper looks like this when implemented.
+ +1 final class User
+{
+ /** @var string */
+ private $username;
+
+ public function __construct(string $username)
+ {
+ $this->username = $username;
+ }
+
+ // ...
+}
+
+$objectManager = new ObjectManager();
+$userRepository = $objectManager->getRepository(User::class);
+
+$newUser = new User('jwage');
+
+$objectManager->persist($newUser);
+$objectManager->flush();
+
+$user = $objectManager->find(User::class, 1);
+
+$objectManager->remove($user);
+$objectManager->flush();
+
+$users = $userRepository->findAll();
+2
+3
+4
+5
+6
+7
+8
+9
+10
+11
+12
+13
+14
+15
+16
+17
+18
+19
+20
+21
+22
+23
+24
+25
+26
+27
+
+ To learn more about the full interfaces and functionality continue reading!
+ +The main public interface that an end user will use is the Doctrine\Persistence\ObjectManager
interface.
1 namespace Doctrine\Persistence;
+
+interface ObjectManager
+{
+ public function find($className, $id);
+ public function persist($object);
+ public function remove($object);
+ public function clear();
+ public function detach($object);
+ public function refresh($object);
+ public function flush();
+ public function getRepository($className);
+ public function getClassMetadata($className);
+ public function getMetadataFactory();
+ public function initializeObject($obj);
+ public function contains($object);
+}
+2
+3
+4
+5
+6
+7
+8
+9
+10
+11
+12
+13
+14
+15
+16
+17
+ The object repository is used to retrieve instances of your mapped objects from the mapper.
+ +1 namespace Doctrine\Persistence;
+
+interface ObjectRepository
+{
+ public function find($id);
+ public function findAll();
+ public function findBy(array $criteria, ?array $orderBy = null, $limit = null, $offset = null);
+ public function findOneBy(array $criteria);
+ public function getClassName();
+}
+2
+3
+4
+5
+6
+7
+8
+9
+10
+ In order for Doctrine to be able to persist your objects to a data store, you have to map the classes and class +properties so they can be properly stored and retrieved while maintaining a consistent state.
+ +1 namespace Doctrine\Persistence\Mapping;
+
+interface ClassMetadata
+{
+ public function getName();
+ public function getIdentifier();
+ public function getReflectionClass();
+ public function isIdentifier($fieldName);
+ public function hasField($fieldName);
+ public function hasAssociation($fieldName);
+ public function isSingleValuedAssociation($fieldName);
+ public function isCollectionValuedAssociation($fieldName);
+ public function getFieldNames();
+ public function getIdentifierFieldNames();
+ public function getAssociationNames();
+ public function getTypeOfField($fieldName);
+ public function getAssociationTargetClass($assocName);
+ public function isAssociationInverseSide($assocName);
+ public function getAssociationMappedByTargetField($assocName);
+ public function getIdentifierValues($object);
+}
+2
+3
+4
+5
+6
+7
+8
+9
+10
+11
+12
+13
+14
+15
+16
+17
+18
+19
+20
+21
+ The Doctrine\Persistence\Mapping\ClassMetadataFactory
class can be used to manage the instances for each of
+your mapped PHP classes.
1 namespace Doctrine\Persistence\Mapping;
+
+interface ClassMetadataFactory
+{
+ public function getAllMetadata();
+ public function getMetadataFor($className);
+ public function hasMetadataFor($className);
+ public function setMetadataFor($className, $class);
+ public function isTransient($className);
+}
+2
+3
+4
+5
+6
+7
+8
+9
+10
+ In order to load ClassMetadata
instances you can use the Doctrine\Persistence\Mapping\Driver\MappingDriver
+interface. This is the interface that does the core loading of mapping information from wherever they are stored.
+That may be in files, attributes, yaml, xml, etc.
1 namespace Doctrine\Persistence\Mapping\Driver;
+
+use Doctrine\Persistence\Mapping\ClassMetadata;
+
+interface MappingDriver
+{
+ public function loadMetadataForClass($className, ClassMetadata $metadata);
+ public function getAllClassNames();
+ public function isTransient($className);
+}
+2
+3
+4
+5
+6
+7
+8
+9
+10
+
+ The Doctrine Persistence project offers a few base implementations that +make it easy to implement your own XML, Attributes or YAML drivers.
+ +The file driver operates in a mode where it loads the mapping files of individual classes on demand. This requires +the user to adhere to the convention of 1 mapping file per class and the file names of the mapping files must +correspond to the full class name, including namespace, with the namespace delimiters '', replaced by dots '.'.
+ + +Extend the Doctrine\Persistence\Mapping\Driver\FileDriver
class to implement your own file driver.
+Here is an example JSON file driver implementation.
1 use Doctrine\Persistence\Mapping\Driver\FileDriver;
+
+final class JSONFileDriver extends FileDriver
+{
+ public function loadMetadataForClass($className, ClassMetadata $metadata)
+ {
+ $mappingFileData = $this->getElement($className);
+
+ // use the array of mapping information from the file to populate the $metadata instance
+ }
+
+ protected function loadMappingFile($file)
+ {
+ return json_decode($file, true);
+ }
+}
+2
+3
+4
+5
+6
+7
+8
+9
+10
+11
+12
+13
+14
+15
+16
+
+ Now you can use it like the following.
+ +
+
+ Now if you have a class named App\Model\User
and you can load the mapping information like this.
+ The PHPDriver includes PHP files which just populate ClassMetadata
instances with plain PHP code.
+
+ Now you can use it like the following:
+ +
+
+ Inside the /path/to/mapping/files/App.Model.User.php
file you can write raw PHP code to populate a ClassMetadata
+instance. You will have access to a variable named $metadata
inside the file that you can use to populate the
+mapping metadata.
+ The StaticPHPDriver calls a static loadMetadata()
method on your model classes where you can manually populate the
+ClassMetadata
instance.
+
+ Your class in App\Model\User
would look like the following.
+ Doctrine uses reflection to set and get the data inside your objects. The
+Doctrine\Persistence\Mapping\ReflectionService
is the primary interface needed for a Doctrine mapper.
1 namespace Doctrine\Persistence\Mapping;
+
+interface ReflectionService
+{
+ public function getParentClasses($class);
+ public function getClassShortName($class);
+ public function getClassNamespace($class);
+ public function getClass($class);
+ public function getAccessibleProperty($class, $property);
+ public function hasPublicMethod($class, $method);
+}
+2
+3
+4
+5
+6
+7
+8
+9
+10
+11
+
+ Doctrine provides an implementation of this interface in the class named
+Doctrine\Persistence\Mapping\RuntimeReflectionService
.
There are several different implementations of the Doctrine Persistence APIs.
+ + + ++ + | +You are browsing a version that has not yet been released. |
+
Change tracking is the process of determining what has changed in +observed objects since the last time they were synchronized with +the persistence backend.
+ + +This approach is based on the observer pattern
+and consists of the following two interfaces:
+ ``Doctrine\Persistence\NotifyPropertyChanged`` that is implemented by the object
+ whose changes can be tracked,
+ Doctrine\Persistence\PropertyChangedListener
that is implemented by subscribers
+which are interested in tracking the changes.
A class that wants to allow other objects to subscribe needs to
+implement the NotifyPropertyChanged
interface. As a guideline,
+such an implementation can look as follows:
1 <?php
+
+use Doctrine\Persistence\NotifyPropertyChanged;
+use Doctrine\Persistence\PropertyChangedListener;
+
+class MyTrackedObject implements NotifyPropertyChanged
+{
+ // ...
+
+ /** @var PropertyChangedListener[] */
+ private $listeners = [];
+
+ public function addPropertyChangedListener(PropertyChangedListener $listener) : void
+ {
+ $this->listeners[] = $listener;
+ }
+}
+2
+3
+4
+5
+6
+7
+8
+9
+10
+11
+12
+13
+14
+15
+16
+17
+
+ Then, in each mutator of this class or any derived classes, you
+need to notify all the PropertyChangedListener
instances. As an
+example we add a convenience method on MyTrackedObject
that shows
+this behavior:
1 <?php
+
+// ...
+
+class MyTrackedObject implements NotifyPropertyChanged
+{
+ // ...
+
+ final protected function notifySubscribers(string $propertyName, $oldValue, $newValue) : void
+ {
+ foreach ($this->listeners as $listener) {
+ $listener->propertyChanged($this, $propertyName, $oldValue, $newValue);
+ }
+ }
+
+ public function setAge(int $age) : void
+ {
+ if ($this->age === $age) {
+ return;
+ }
+
+ $this->notifySubscribers('age', $this->age, $age);
+ $this->age = $age;
+ }
+}
+2
+3
+4
+5
+6
+7
+8
+9
+10
+11
+12
+13
+14
+15
+16
+17
+18
+19
+20
+21
+22
+23
+24
+25
+
+ You have to invoke notifySubscribers()
inside every method that
+changes the persistent state of MyTrackedObject
.
The check whether the new value is different from the old one is +not mandatory but recommended. That way you also have full control +over when you consider a property changed.
+ +