epwzf20

Building Persistent Classes

In my opinion Doctrine's most compelling feature is its ability to make PHP classes persistent simply by adding DocBlock annotations to the class, meaning that merely adding those annotations will empower Doctrine to associate CRUD features with the class. An added bonus of these annotations is the ability to generate and maintain table schemas based on the annotation declarations.

These annotations are added to your model in a very unobtrusive way, placed within PHP comments spread throughout the class file. The below listing presents a simplified version of the Account entity found in application/models/Entities/Account.php, complete with the annotations. An explanation of key lines follows the listing.

09{

10/**

11* @Id @Column(type="integer")

12* @GeneratedValue(strategy="AUTO")

13*/

14private $id;

15

16/** @Column(type="string", length=255) */

17private $name;

18

19/** @Column(type="string", length=255) */

20private $publisher;

21

22/** @Column(type="decimal",scale=2, precision=5) */

23private $price;

24

25public function getId()

26{

27return $this->id;

28}

29

30public function getName()

31{

32return $this->name;

33}

34

35public function setName($name)

36{

37$this->name = $name;

38}

39

40 ...

41

42public function setPassword($password)

43{

44$this->password = md5($password);

45}

46

47 ...

48

49public function getPrice()

50{

51return $this->price;

52}

53

54public function setPrice($price)

55{

56$this->price = $price;

57}

58

59 }

Let's review the code:

•Line 03 declares this class to be part of the namespace Entities. Doctrine refers to persistable classes as entities, which are defined as objects with identity. Therefore for organizational purposes I've placed these persistable classes in a the directory application/models/Entities, and use PHP 5.3's namespacing feature within the controllers to reference the class, which is much more convenient than using the underscore-based approach embraced by the Zend Framework (which is unavoidable since namespaces are a PHP 5.3-specific feature). Therefore while it's not a requirement in terms of making a class persistable, I nonetheless suggest doing it for organizational purposes.

•Line 06 declares the class to be an entity (done using the @Entity annotation). Doctrine will by default map the class to a database table of the same name as the class, however if you prefer to use a different name then you can override the default using the @Table annotation.

•Lines 11-14 define an automatically incrementing integer-based primary key named id.

•Line 16 defines a column named name using type varchar of length 255. Doctrine will by default define this column as NOT NULL.

Querying and Manipulating Your Data

One of Doctrine's most compelling features is its ability to map table schemas to an object-oriented interface. Not only can you use the interface to conveniently carry out the usual CRUD (create, retrieve, update, delete) tasks, but Doctrine will also make your life even easier by providing a number of so-called "magic finders" which allow you to explicitly identify the argument you're searching for as part of the method name. In this section I'll show you how to use Doctrine to retrieve and manipulate data.

Inserting, Updating, and Deleting Records

Whether its creating user accounts, updating blog entries, or deleting comment spam, you're guaranteed to spend a great deal of time developing features which insert, modify, and delete database records. In this section I'll show you how to use Doctrine's native capabilities to perform all three tasks.

Inserting Records

Unless you've already gone ahead and manually inserted records into the tables created in the previous section, the z2d2 database is currently empty, so let's begin by adding a new record:

01 $em = $this->_helper->EntityManager(); 02

03 $account = new \Entities\Account;

04

05 $account->setUsername('wjgilmore');

06 $account->setEmail('example@wjgilmore.com');

07 $account->setPassword('jason');

08 $account->setZip('43201');

09$em->persist($account);

10$em->flush();

Let's review this example:

•Line 01 retrieves an instance of the Doctrine entity manager. The Doctrine documentation defines the entity manager "as the central access point to ORM functionality", and it will play a central role in all of your Doctrine-related operations.

•Line 03 creates a new instance of the Account entity, using the namespacing syntax made available with PHP 5.3.

•Lines 05-08 set the object's fields. The beauty of this approach is that we have encapsulated domain-specific behaviors within the class, such as hashing the password using PHP's md5() function. See the Account entity file to understand how this is accomplished.

•Line 09 uses the entity manager's persist() method that you intend to make this data persistent. Note that this does not write the changes to the database! This is the job of the flush() method found on line 10. The flush() method will write all changes which have been identified by the persist() method back to the database.

Note

It's possible to fully decouple the entity manager from the application controllers by creating a service layer, however I've concluded that for the purposes of this exercise it would perhaps be overkill as it would likely only serve to confuse those readers who are being introduced to this topic for the first time. In the coming weeks I'll release a second version of z2d2 which implements a service layer, should you want to know more about how such a feature might be accomplished.

Modifying Records

Modifying a record couldn't be easier; just retrieve it from the database, use the entity setters to change the attributes, and then save the record using the persist() / flush() methods demonstrated in the previous example. I'm getting ahead of myself due to necessarily needing to retrieve a record in order to modify it, however the method name used to retrieve the record is quite self-explanatory:

$accounts = $em->getRepository('Entities\Account') ->findOneByUsername('wjgilmore');

$account->setZip('20171'); $em->persist($account); $em->flush();

Deleting Records

To delete a record, you'll pass the entity object to the entity manager's remove() method:

$accounts = $em->getRepository('Entities\Account') ->findOneByUsername('wjgilmore');

$em->remove($account); $em->flush();

foreach ($accounts AS $account)

{

echo "{$account->getUsername()}<br />";

}

It's even possible to execute native queries and map those results to objects using a new Doctrine 2 feature known as Native Queries. See the Doctrine manual for more information.

Logically you're not going to want to embed DQL into your controllers, however the domain model isn't an ideal location either. The proper location is within methods defined within custom entity repositories. I'll show you how this is done in the later section "Defining Repositories".

Managing Entity Associations

All of the examples provided thus far are useful for becoming familiar with Doctrine syntax, however even a relatively simple real-world application is going to require significantly more involved queries. In many cases the queries will be more involved because the application will involve multiple domain models which are interrelated.

Unless you're a particularly experienced SQL wrangler, you're probably well aware of just how difficult it can be to both build and mine these associations. For instance just the three tables (accounts, games, accounts_games) which you generated earlier in this chapter pose some significant challenges in the sense that you'll need to create queries which can determine which games are associated with a particular account, and also which accounts are associated with a particular game. You'll also need to create features for associating and disassociating games with accounts. If you're new to managing these sorts of associations, it can be very easy to devise incredibly awkward solutions to manage these sort of relations.

Doctrine makes managing even complex associations laughably easy, allowing you to for instance retrieve the games associated with a particular account using intuitive object-oriented syntax:

$account = $em->getRepository('Entities\Account') ->findOneByUsername('wjgilmore');

$games = $account->getGames();

printf("%s owns the following games:<br />", $account->getUsername());

foreach ($games AS $game)

{

printf("%s<br />", $game->getName());

}

Adding games to an account's library is similarly easy. Just associate the game with the account by passing the game object into the account's add() method, as demonstrated here:

$em = $this->_helper->EntityManager();

$account = $em->getRepository('Entities\Account') ->findOneByUsername('wjgilmore');

$game = $em->getRepository('Entities\Game') ->findOneByName('Super Mario Brothers');

$account->getGames()->add($game);

$em->persist($account); $em->flush();

To remove a game from an account's library, use the removeElement() method:

$account = $em->getRepository('Entities\Account') ->findOneByUsername('wjgilmore');

$game = $em->getRepository('Entities\Game')->find(1);

$account->getGames()->removeElement($game);

$em->persist($account); $em->flush();

Configuring Associations

In order to take advantage of these fantastic features you'll need to define the nature of the associations within your entities. Doctrine supports a variety of associations, including one-to-one, one-to-many, many-to-one, and many-to-many. In this section I'll show you how to configure a many-to-many association, which is also referred to as a has-and-belongs-to-many relationship. For instance, the book's theme project is based in large part around providing registered users with the ability to build video game libraries. Therefore, an account can have many games, and a game can be owned by multiple users. This relationship would be represented like so:

CREATE TABLE accounts (

id INTEGER UNSIGNED NOT NULL AUTO_INCREMENT PRIMARY KEY, username VARCHAR(255) NOT NULL,

email VARCHAR(255) NOT NULL

);

CREATE TABLE games (

id INTEGER UNSIGNED NOT NULL AUTO_INCREMENT PRIMARY KEY,

name VARCHAR(255) NOT NULL, publisher VARCHAR(255) NOT NULL

);

CREATE TABLE accounts_games ( account_id INTEGER UNSIGNED NOT NULL, game_id INTEGER UNSIGNED NOT NULL,

);

ALTER TABLE accounts_games ADD FOREIGN KEY (account_id)

REFERENCES accounts(id);

ALTER TABLE accounts_games ADD FOREIGN KEY (game_id)

REFERENCES games(id);

Because the idea is to associate a collection of games with an account, you'll need to use Doctrine's Doctrine/Common/Collections/Collection interface. Incidentally this section is referring to the same code found in the z2d2 project Account entity so I suggest opening that file and follow along. We'll want to use the ArrayCollection class, so reference it at the top of your entity like this:

use Doctrine\Common\Collections\ArrayCollection;

Next you'll need to define the class attribute which will contain the collection, and with it the nature of the relationship it has with another entity. This is easily the most difficult step, however the Doctrine manual provides quite a few examples and if you rigorously model your code after that accompanying these examples then you'll be fine. For instance, we want the Account entity to manage a collection of games, and so the ManyToMany annotation will look like this:

/**

*@ManyToMany(targetEntity="Game", inversedBy="accounts")

*@JoinTable(name="accounts_games",

*joinColumns={@JoinColumn(name="account_id",

*inverseJoinColumns={@JoinColumn(name="game_id",

private $games;

With the relationship defined, you'll want to initialize the $games attribute, done within a class constructor:

public function __construct()

{

$this->games = new ArrayCollection();