Configuring the Database

Before you can start, you'll need to configure your database connection information. By convention, this information is usually configured in an app/config/parameters.yml file:

1
2
3
4
5
6
7
8

# app/config/parameters.yml
parameters:
    database_driver:   mysql
    database_host:     localhost
    database_name:     test_project
    database_user:     root
    database_password: password
    database_charset:  UTF8

These parameters defined in parameters.yml can now be included in the configuration file (config.yml):

1
2
3
4
5
6

propel:
    dbal:
        driver:   "%database_driver%"
        user:     "%database_user%"
        password: "%database_password%"
        dsn:      "%database_driver%:host=%database_host%;dbname=%database_name%;charset=%database_charset%"

Now that Propel knows about your database, Symfony can create the database for you:

1

$ php app/console propel:database:create

Creating a Model Class

In the Propel world, ActiveRecord classes are known as models because classes generated by Propel contain some business logic.

Suppose you're building an application where products need to be displayed. First, create a schema.xml file inside the Resources/config directory of your AcmeStoreBundle:

1
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
28

<?xml version="1.0" encoding="UTF-8" ?>
<database
    name="default"
    namespace="Acme\StoreBundle\Model"
    defaultIdMethod="native">

    <table name="product">
        <column
            name="id"
            type="integer"
            required="true"
            primaryKey="true"
            autoIncrement="true" />

        <column
            name="name"
            type="varchar"
            primaryString="true"
            size="100" />
        <column
            name="price"
            type="decimal" />

        <column
            name="description"
            type="longvarchar" />
    </table>
</database>

Building the Model

After creating your schema.xml, generate your model from it by running:

1

$ php app/console propel:model:build

This generates each model class to quickly develop your application in the Model/ directory of the AcmeStoreBundle bundle.

Creating the Database Tables/Schema

Now you have a usable Product class and all you need to persist it. Of course, you don't yet have the corresponding product table in your database. Fortunately, Propel can automatically create all the database tables needed for every known model in your application. To do this, run:

1
2

$ php app/console propel:sql:build
$ php app/console propel:sql:insert --force

Your database now has a fully-functional product table with columns that match the schema you've specified.

Persisting Objects to the Database

Now that you have a Product object and corresponding product table, you're ready to persist data to the database. From inside a controller, this is pretty easy. Add the following method to the DefaultController of the bundle:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

// src/Acme/StoreBundle/Controller/DefaultController.php

// ...
use Acme\StoreBundle\Model\Product;
use Symfony\Component\HttpFoundation\Response;

public function createAction()
{
    $product = new Product();
    $product->setName('A Foo Bar');
    $product->setPrice(19.99);
    $product->setDescription('Lorem ipsum dolor');

    $product->save();

    return new Response('Created product id '.$product->getId());
}

In this piece of code, you instantiate and work with the $product object. When you call the save() method on it, you persist it to the database. No need to use other services, the object knows how to persist itself.

Fetching Objects from the Database

Fetching an object back from the database is even easier. For example, suppose you've configured a route to display a specific Product based on its id value:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

// ...
use Acme\StoreBundle\Model\ProductQuery;

public function showAction($id)
{
    $product = ProductQuery::create()
        ->findPk($id);

    if (!$product) {
        throw $this->createNotFoundException(
            'No product found for id '.$id
        );
    }

    // ... do something, like pass the $product object into a template
}

Updating an Object

Once you've fetched an object from Propel, updating it is easy. Suppose you have a route that maps a product id to an update action in a controller:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

// ...
use Acme\StoreBundle\Model\ProductQuery;

public function updateAction($id)
{
    $product = ProductQuery::create()
        ->findPk($id);

    if (!$product) {
        throw $this->createNotFoundException(
            'No product found for id '.$id
        );
    }

    $product->setName('New product name!');
    $product->save();

    return $this->redirect($this->generateUrl('homepage'));
}

Updating an object involves just three steps:

1. fetching the object from Propel (line 6 - 13);
2. modifying the object (line 15);
3. saving it (line 16).

Deleting an Object

Deleting an object is very similar to updating, but requires a call to the delete() method on the object:

1

$product->delete();

Saving Related Objects

Now, try the code in action. Imagine you're inside a controller:

1
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

// ...
use Acme\StoreBundle\Model\Category;
use Acme\StoreBundle\Model\Product;
use Symfony\Component\HttpFoundation\Response;

class DefaultController extends Controller
{
    public function createProductAction()
    {
        $category = new Category();
        $category->setName('Main Products');

        $product = new Product();
        $product->setName('Foo');
        $product->setPrice(19.99);
        // relate this product to the category
        $product->setCategory($category);

        // save the whole
        $product->save();

        return new Response(
            'Created product id: '.$product->getId().' and category id: '.$category->getId()
        );
    }
}

Now, a single row is added to both the category and product tables. The product.category_id column for the new product is set to whatever the id is of the new category. Propel manages the persistence of this relationship for you.

Fetching Related Objects

When you need to fetch associated objects, your workflow looks just like it did before. First, fetch a $product object and then access its related Category:

1
2
3
4
5
6
7
8
9
10
11
12
13

// ...
use Acme\StoreBundle\Model\ProductQuery;

public function showAction($id)
{
    $product = ProductQuery::create()
        ->joinWithCategory()
        ->findPk($id);

    $categoryName = $product->getCategory()->getName();

    // ...
}

Note, in the above example, only one query was made.

More Information on Associations

You will find more information on relations by reading the dedicated chapter on Relationships.