From c613351f39e4607da977619727dae6744604d258 Mon Sep 17 00:00:00 2001 From: Benjamin Eberlei Date: Sun, 29 Jan 2012 22:40:38 +0100 Subject: [PATCH] Added 10 quick steps section --- en/index.rst | 3 +- en/toc.rst | 1 + en/tutorials/in-ten-quick-steps.rst | 300 ++++++++++++++++++++++++++++ 3 files changed, 303 insertions(+), 1 deletion(-) create mode 100644 en/tutorials/in-ten-quick-steps.rst diff --git a/en/index.rst b/en/index.rst index 034432add..8be6565fb 100644 --- a/en/index.rst +++ b/en/index.rst @@ -26,7 +26,8 @@ Getting Started --------------- * **Tutorial**: - :doc:`Getting Started ` + :doc:`Getting Started ` | + :doc:`In 10 quick steps ` * **Reference**: :doc:`Introduction ` | diff --git a/en/toc.rst b/en/toc.rst index 7ab8805b0..8178f8c05 100644 --- a/en/toc.rst +++ b/en/toc.rst @@ -12,6 +12,7 @@ Tutorials tutorials/extra-lazy-associations tutorials/composite-primary-keys tutorials/ordered-associations + tutorials/in-ten-quick-steps Reference Guide --------------- diff --git a/en/tutorials/in-ten-quick-steps.rst b/en/tutorials/in-ten-quick-steps.rst new file mode 100644 index 000000000..754887d66 --- /dev/null +++ b/en/tutorials/in-ten-quick-steps.rst @@ -0,0 +1,300 @@ +Doctrine explained in 10 quick steps +==================================== + +You can follow this tutorial step by step yourself and end up with a simple +Doctrine application. It assumed that you installed Doctrine via PEAR. To work +with another setup just take a look into the :doc:`Installation help +<../reference/introduction>`. + +1. Allows you to map PHP Objects to database tables +--------------------------------------------------- + +.. code-block:: php + + CREATE TABLE Post (id INT AUTO_INCREMENT PRIMARY KEY, title + VARCHAR(255), body TEXT); + + mysql> DESCRIBE Post; + +-------+--------------+------+-----+---------+----------------+ + | Field | Type | Null | Key | Default | Extra | + +-------+--------------+------+-----+---------+----------------+ + | id | int(11) | NO | PRI | NULL | auto_increment | + | title | varchar(255) | YES | | NULL | | + | body | text | YES | | NULL | | + +-------+--------------+------+-----+---------+----------------+ + +.. tip:: + + Objects mapped with Doctrine are called Entities. They don't need to extend + a base class and even allow constructors with required parameters. + + You are responsible for implementing getters, setters and constructors of + your entities yourself. This gives you full freedom to design your business + objects as you wish. + +2. Using Annotations, XML or YAML for Metadata Mapping +------------------------------------------------------ + +.. configuration-block:: + + .. code-block:: php + + + + + + + + + + + + + +3. Object References map to Foreign keys +---------------------------------------- + +.. code-block:: php + + author = $user; + } + } + + /** @Entity **/ + class User + { + /** @Id @GeneratedValue @Column(type="integer") **/ + protected $id; + /** @Column(type="string") **/ + protected $name; + } + + $user = new User(); + $post = new Post($user); + + +:: + + mysql> CREATE TABLE Post (id INT AUTO_INCREMENT PRIMARY KEY, title + VARCHAR(255), body TEXT, author_id INT); + + mysql> CREATE TABLE User (id INT AUTO_INCREMENT PRIMARY KEY, name + VARCHAR(255)); + + mysql> ALTER TABLE Post ADD FOREIGN KEY (author_id) REFERENCES User (id); + + mysql> DESCRIBE Post; + +-----------+--------------+------+-----+---------+----------------+ + | Field | Type | Null | Key | Default | Extra | + +-----------+--------------+------+-----+---------+----------------+ + | id | int(11) | NO | PRI | NULL | auto_increment | + | title | varchar(255) | YES | | NULL | | + | body | text | YES | | NULL | | + | author_id | int(11) | YES | MUL | NULL | | + +-----------+--------------+------+-----+---------+----------------+ + +.. tip:: + + This means you don't have to mess with foreign keys yourself, just use + references to connect objects with each other and let Doctrine handle the + rest. + +4. Collections handle sets of objects references +------------------------------------------------ + +.. code-block:: php + + author = $author; + $this->posts = new ArrayCollection(); + } + + public function addComment($text) + { + $this->comments[] = $new Comment($this, $text); + } + } + + /** @Entity **/ + class Comment + { + /** @Id @GeneratedValue @Column(type="integer") **/ + protected $id; + /** @Column(type="text") **/ + protected $comment; + /** + * @ManyToOne(targetEntity="Post", inversedBy="comments") + **/ + protected $post; + + public function __construct(Post $post, $text) + { + $this->post = $post; + $this->comment = $text; + } + } + + $post->addComment("First.."); + $post->addComment("Second!"); + +5. Easy to setup for the default configuration case +--------------------------------------------------- + +.. code-block:: php + + register(); + + $dbParams = array( + 'driver' => 'pdo_mysql', + 'user' => 'root', + 'password' => '', + 'dbname' => 'tests' + ); + $path = 'path/to/entities'; + $config = Setup::createAnnotationMetadataConfiguration($path, true); + $entityManager = EntityManager::create($dbParams, $config); + + +6. The EntityManager needs to know about your new objects +--------------------------------------------------------- + +.. code-block:: php + + persist($user); + $entityManager->persist($post); + +.. warning:: + + This does not lead to INSERT/UPDATE statements yet. You need to call + EntityManager#flush() + + +7. EntityManager#flush() batches SQL INSERT/UPDATE/DELETE statements +-------------------------------------------------------------------- + +.. code-block:: php + + flush(); + +.. tip:: + + Batching all write-operations against the database allows Doctrine to wrap all + statements into a single transaction and benefit from other performance + optimizations such as prepared statement re-use. + +8. You can fetch objects from the database through the EntityManager +-------------------------------------------------------------------- + +.. code-block:: php + + find("Post", $id); + +9. ..or through a Repository +---------------------------- + +.. code-block:: php + + getRepository("Author"); + $author = $authorRepository->find($authorId); + + $postRepository = $entityManager->getRepository("Post"); + $post = $postRepository->findOneBy(array("title" => "Hello World!")); + + $posts = $repository->findBy( + array("author" => $author), + array("title" => "ASC") + ); + + +10. Or complex finder scenarios with the Doctrine Query Language +---------------------------------------------------------------- + +.. code-block:: php + + createQuery($dql)->getResult();