From 142c20aad1413e64082a5a9a2e5ee49617e3a1a0 Mon Sep 17 00:00:00 2001 From: Benjamin Eberlei Date: Tue, 9 Apr 2013 00:00:16 +0200 Subject: [PATCH] Work on the Tutorial --- docs/en/tutorials/getting-started.rst | 175 ++++++++++++++++++-------- 1 file changed, 124 insertions(+), 51 deletions(-) diff --git a/docs/en/tutorials/getting-started.rst b/docs/en/tutorials/getting-started.rst index f34590de2..2faea8218 100644 --- a/docs/en/tutorials/getting-started.rst +++ b/docs/en/tutorials/getting-started.rst @@ -258,8 +258,8 @@ entity definition in there: } Note how the properties have getter and setter methods defined except -`$id`. To access data from entities Doctrine 2 uses the Reflection API, so it -is possible for Doctrine to access the value of `$id`. You don't have to +``$id``. To access data from entities Doctrine 2 uses the Reflection API, so it +is possible for Doctrine to access the value of ``$id``. You don't have to take Doctrine into account when designing access to the state of your objects. The next step for persistence with Doctrine is to describe the @@ -268,9 +268,8 @@ language. The metadata language describes how entities, their properties and references should be persisted and what constraints should be applied to them. -Metadata for entities are configured using a -XML, YAML or Docblock Annotations. This -Getting Started Guide will show the mappings for all Mapping Drivers. +Metadata for entities are configured using a XML, YAML or Docblock Annotations. +This Getting Started Guide will show the mappings for all Mapping Drivers. References in the text will be made to the XML mapping. .. configuration-block:: @@ -337,9 +336,12 @@ You have to update the database now, because we have a first Entity now: :: - $ php vendor/bin/doctrine orm:schema-tool:update + $ php vendor/bin/doctrine orm:schema-tool:update --force --dump-sql -Now create a simple script to create a new product: +Specifying both flags ``--force`` and ``-dump-sql`` prints and executes the DDL +statements. + +Now create a new script that will insert products into the database: .. code-block:: php @@ -357,41 +359,37 @@ Now create a simple script to create a new product: echo "Created Product with ID " . $product->getId() . "\n"; -Call this script to see how new products are created: +Call this script from the command line to see how new products are created: :: $ php create_product.php ORM $ php create_product.php DBAL -What is happening here? In the code using the Product is pretty standard OOP. -The interesting bits are the communication with the ``EntityManager``. To +What is happening here? Using the ``Product`` is pretty standard OOP. +The interesting bits are the use of the ``EntityManager`` service. To notify the EntityManager that a new entity should be inserted into the database -you have to call ``persist()``. However the EntityManager does not act on this -command, its merely notified. You have to explicitly call ``flush()`` to have -the EntityManager write those two entities to the database. +you have to call ``persist()``. To intiate a transaction to actually perform +the insertion, You have to explicitly call ``flush()`` on the ``EntityManager``. -You might wonder why does this distinction between persist notification and -flush exist: Doctrine 2 uses the UnitOfWork pattern to aggregate all writes +This distinction between persist and flush is allows to aggregate all writes (INSERT, UPDATE, DELETE) into one single transaction, which is executed when -flush is called. Using this approach the write-performance is significantly +flush is called. Using this approach the write-performance is significantly better than in a scenario where updates are done for each entity in isolation. -In more complex scenarios than the previous two, you are free to request -updates on many different entities and all flush them at once. -Doctrine's UnitOfWork detects entities that have changed after retrieval from -the database automatically when the flush operation is called, so that you only -have to keep track of those entities that are new or to be removed and pass -them to ``EntityManager#persist()`` and ``EntityManager#remove()`` -respectively. +Doctrine follows the UnitOfWork pattern which additionally detects all entities +that were fetched and have changed during the request. You don't have to keep track of +entities yourself, when Doctrine already knowns about them. -We want to see a list of all the products now, so lets create a new script for -this: +As a next step we want to fetch a list of all the products. Let's create a +new script for this: .. code-block:: php getRepository('Product'); $products = $productRepository->findAll(); @@ -399,65 +397,144 @@ this: echo sprintf("-%s\n", $product->getName()); } -The ``EntityRepository`` fetched through the ``EntityManager#getRepository()`` -method exists for every entity and is provided by Doctrine. It contains -some finder methods such as ``findAll()`` we used here. +The ``EntityManager#getRepository()`` method can create a finder object (called +repository) for every entity. It is provided by Doctrine and contains some +finder methods such as ``findAll()``. -Lets display the name of a product based on its ID: +Let's continue with displaying the name of a product based on its ID: .. code-block:: php + require_once "bootstrap.php"; + $id = $argv[1]; $product = $entityManager->find('Product', $id); + if ($product === null) { + echo "No product found.\n"; + exit(1); + } + echo sprintf("-%s\n", $product->getName()); +Updating a product name demonstrates the functionality UnitOfWork of pattern +discussed before. We only need to find a product entity and all changes to its +properties are written to the database: + +.. code-block:: php + + + require_once "bootstrap.php"; + + $id = $argv[1]; + $newName = $argv[2]; + + $product = $entityManager->find('Product', $id); + + if ($product === null) { + echo "Product $id does not exist.\n"; + exit(1); + } + + $product->setName($newName); + + $entityManager->flush(); + +After calling this script on one of the existing products, you can verify the +product name changed by calling the ``show_product.php`` script. + Adding Bug and User Entities ---------------------------- -We continue with the bug tracker domain, by creating the missing -classes ``Bug`` and ``User`` and putting them into -`src/Bug.php` and `src/User.php` -respectively. +We continue with the bug tracker domain, by creating the missing classes +``Bug`` and ``User`` and putting them into ``src/Bug.php`` and +``src/User.php`` respectively. .. code-block:: php id; + } + + public function getDescription() + { + return $this->description; + } + + public function setDescription($description) + { + $this->description = $description; + } + + public function setCreated(DateTime $created) + { + $this->created = $created; + } + + public function getCreated() + { + return $this->created; + } + + public function setStatus($status) + { + $this->status = $status; + } + + public function getStatus() + { + return $this->status; + } + } .. code-block:: php