Added 10 quick steps section
This commit is contained in:
Benjamin Eberlei
parent
9bd51f2062
commit
c613351f39
@ -26,7 +26,8 @@ Getting Started
|
||||
---------------
|
||||
|
||||
* **Tutorial**:
|
||||
:doc:`Getting Started <tutorials/getting-started>`
|
||||
:doc:`Getting Started <tutorials/getting-started>` |
|
||||
:doc:`In 10 quick steps <tutorials/in-ten-quick-steps>`
|
||||
|
||||
* **Reference**:
|
||||
:doc:`Introduction <reference/introduction>` |
|
||||
|
||||
@ -12,6 +12,7 @@ Tutorials
|
||||
tutorials/extra-lazy-associations
|
||||
tutorials/composite-primary-keys
|
||||
tutorials/ordered-associations
|
||||
tutorials/in-ten-quick-steps
|
||||
|
||||
Reference Guide
|
||||
---------------
|
||||
|
||||
300
en/tutorials/in-ten-quick-steps.rst
Normal file
300
en/tutorials/in-ten-quick-steps.rst
Normal file
@ -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
|
||||
|
||||
<?php
|
||||
class Post
|
||||
{
|
||||
protected $id;
|
||||
protected $title;
|
||||
protected $body;
|
||||
}
|
||||
|
||||
::
|
||||
|
||||
mysql> 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
|
||||
|
||||
<?php
|
||||
/** @Entity **/
|
||||
class Post
|
||||
{
|
||||
/** @Id @GeneratedValue @Column(type="integer") **/
|
||||
protected $id;
|
||||
/** @Column(type="string") **/
|
||||
protected $title;
|
||||
/** @Column(type="text") **/
|
||||
protected $body;
|
||||
}
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
Post:
|
||||
type: entity
|
||||
id:
|
||||
id:
|
||||
type: integer
|
||||
generator:
|
||||
strategy: AUTO
|
||||
fields:
|
||||
title:
|
||||
type: string
|
||||
body:
|
||||
type: text
|
||||
|
||||
.. code-block:: xml
|
||||
|
||||
<?xml version="1.0" ?>
|
||||
<doctrine-mapping>
|
||||
<entity name="Post">
|
||||
<id name="id type="integer">
|
||||
<generator strategy="AUTO" />
|
||||
</id>
|
||||
<field name="title" type="string" />
|
||||
<field name="body" type="text" />
|
||||
</entity>
|
||||
</doctrine-mapping>
|
||||
|
||||
|
||||
3. Object References map to Foreign keys
|
||||
----------------------------------------
|
||||
|
||||
.. code-block:: php
|
||||
|
||||
<?php
|
||||
/** @Entity **/
|
||||
class Post
|
||||
{
|
||||
// .. previous code
|
||||
|
||||
/**
|
||||
* @ManyToOne(targetEntity="User")
|
||||
**/
|
||||
protected $author;
|
||||
|
||||
public function __construct(User $user)
|
||||
{
|
||||
$this->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
|
||||
|
||||
<?php
|
||||
use Doctrine\Common\Collections\ArrayCollection;
|
||||
|
||||
class Post
|
||||
{
|
||||
// .. previous code
|
||||
|
||||
/**
|
||||
* @OneToMany(targetEntity="Comment", mappedBy="post",
|
||||
* cascade={"persist"})
|
||||
**/
|
||||
protected $comments;
|
||||
|
||||
public function __construct(User $author)
|
||||
{
|
||||
$this->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
|
||||
|
||||
<?php
|
||||
|
||||
use Doctrine\ORM\Tools\Setup;
|
||||
use Doctrine\ORM\EntityManager;
|
||||
|
||||
require_once 'Doctrine/Common/ClassLoader.php';
|
||||
|
||||
$loader = new \Doctrine\Common\ClassLoader("Doctrine");
|
||||
$loader->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
|
||||
|
||||
<?php
|
||||
|
||||
$entityManager->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
|
||||
|
||||
<?php
|
||||
|
||||
$entityManager->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
|
||||
|
||||
<?php
|
||||
|
||||
$post = $entityManager->find("Post", $id);
|
||||
|
||||
9. ..or through a Repository
|
||||
----------------------------
|
||||
|
||||
.. code-block:: php
|
||||
|
||||
<?php
|
||||
|
||||
$authorRepository = $entityManager->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
|
||||
|
||||
<?php
|
||||
// all posts and their comment count
|
||||
$dql = "SELECT p, count(c.id) AS comments " .
|
||||
"FROM Post p JOIN p.comments GROUP BY p";
|
||||
$results = $entityManager->createQuery($dql)->getResult();
|
||||
Loading…
Reference in New Issue
Block a user