The behavior does not take care of archiving the related objects. This may be surprising on deletions if the deleted object has 'ON DELETE CASCADE' foreign keys. If you want to archive relations, override the generated `archive()` method in the ActiveRecord class with your custom logic. - -To recover deleted objects, use `populateFromArchive()` on a new object and save it: - -```php -populateFromArchive($archivedBook); -$book->save(); -echo $book->getTitle(); // 'Sense and Sensibility' -``` - -If you want to delete an `archivable` object without archiving it, use the `deleteWithoutArchive()` method generated by the behavior: - -```php -deleteWithoutArchive(); -``` - -## Archiving A Set Of Objects ## - -The `archivable` behavior also generates an `archive()` method on the generated ActiveQuery class. That means you can easily archive a set of objects, in the same way you archive a single object: - -```php -filterByTitle('War%') - ->archive(); -``` - -`archive()` returns the number of archived objects, and not the current ActiveQuery object, so it's a termination method. - ->**Tip**
Since the `archive()` method doesn't duplicate archived objects, it must iterate over the results of the query to check whether each object has already been archived. In practice, `archive()` issues 2n+1 database queries, where `n` is the number of results of the query as returned by a `count()`. - -As explained earlier, an `archivable` model is archived just before deletion by default. This is also true when using the `delete()` and `deleteAll()` methods of the ActiveQuery class: - -```php -filterByTitle('War%') - ->delete(); - -// use deleteWithoutArchive() if you just want to delete -$nbDeletedObjects = BookQuery::create() - ->filterByTitle('War%') - ->deleteWithoutArchive(); - -// you can also turn off the query alteration on the current query -// by calling setArchiveOnDelete(false) before deleting -$nbDeletedObjects = BookQuery::create() - ->filterByTitle('War%') - ->setArchiveOnDelete(false) - ->delete(); -``` - -## Archiving on Insert, Update, or Delete ## - -As explained earlier, the `archivable` behavior archives objects on deletion by default, but insertions and updates don't trigger the `archive()` method. You can disable the auto archiving on deletion, as well as enable it for insertion and update, in the behavior `
The `archive_table` and `archive_class` parameters are mutually exclusive. You can only use either one of the two. - -You can also change the name of the column storing the archive date: - -```xml -
If the delegate table already has a foreign key to the main table, the behavior doesn't recreate it. It allows you to have full control over the relationship between the two tables. - -In addition, the ActiveRecord `Account` class now provides integrated delegation capabilities. That means that it offers to handle directly the columns of the `Profile` model, while in reality it finds or create a related `Profile` object and calls the methods on this delegate: - -```php -setLogin('francois'); -$account->setPassword('S€cr3t'); - -// Fill the profile via delegation -$account->setEmail('francois@example.com'); -$account->setTelephone('202-555-9355'); -// same as -$profile = new Profile(); -$profile->setEmail('francois@example.com'); -$profile->setTelephone('202-555-9355'); -$account->setProfile($profile); - -// save the account and its profile -$account->save(); - -// retrieve delegated data directly from the main object -echo $account->getEmail(); // francois@example.com -``` - -Getter and setter methods for delegate columns don't exist on the main object ; the delegation is handled by the magical `__call()` method. Therefore, the delegation also works for custom methods in the delegate table. - -```php -setEmail($fakeEmail); - } -} - -$account = new Account(); -$account->setFakeEmail(); // delegates to Profile::setFakeEmail() -``` - -## Delegating Using a Many-To-One Relationship ## - -Instead of adding a one-to-one relationship, the `delegate` behavior can take advantage of an existing many-to-one relationship. For instance: - -```xml -
In this example, table delegation is used to implement [Class Table Inheritance](http://martinfowler.com/eaaCatalog/classTableInheritance.html). See how Propel implements this inheritance type, and others, in the [inheritance chapter](../documentation/09-inheritance.html). - -## Delegating To Several Tables ## - -Delegation allows to delegate to several tables. Just separate the name of the delegate tables by commas in the `to` parameter of the `delegate` behavior tag in your schema to delegate to several tables: - -```xml -
Propel uses the [locale](http://en.wikipedia.org/wiki/Locale) concept to identify translations. A locale is a string composed of a language code and a territory code (such as 'en_US' and 'fr_FR'). This allows different translations for two countries using the same language (such as 'fr_FR' and 'fr_CA'); - -## Dealing With Locale And Translations ## - -If you prefer to deal with real translation objects, the behavior generates a `getTranslation()` method on the !ActiveRecord class, which returns a translation object with the required locale. - -```php -setPrice('12.99'); - -// get the English translation -$t1 = $item->getTranslation('en_US'); -// same as -$t1 = new ItemI18n(); -$t1->setLocale('en_US'); -$item->addItemI18n($t1); - -$t1->setName('Microwave oven'); - -// get the French translation -$t2 = $item->getTranslation('fr_FR'); - -$t2->setName('Four micro-ondes'); - -// these translation objects are already related to the main item -// and therefore get saved together with it -$item->save(); // already saves the two translations -``` - ->**Tip**
Or course, if a translation already exists for a given locale, `getTranslation()` returns the existing translation and not a new one. - -You can remove a translation using `removeTranslation()` and a locale: - -```php -findPk(1); -// remove the French translation -$item->removeTranslation('fr_FR'); -``` - -## Querying For Objects With Translations ## - -If you need to display a list, the following code will issue n+1 SQL queries, n being the number of items: - -```php -find(); // one query to retrieve all items -$locale = 'en_US'; -foreach ($items as $item) { - echo $item->getPrice(); - $item->setLocale($locale); - echo $item->getName(); // one query to retrieve the English translation -} -``` - -Fortunately, the behavior adds methods to the Query class, allowing you to hydrate both the `Item` objects and the related `ItemI18n` objects for the given locale: - -```php -joinWithI18n('en_US') - ->find(); // one query to retrieve both all items and their translations -foreach ($items as $item) { - echo $item->getPrice(); - echo $item->getName(); // no additional query -} -``` - -In addition to hydrating translations, `joinWithI18n()` sets the correct locale on results, so you don't need to call `setLocale()` for each result. - ->**Tip**
`joinWithI18n()` adds a left join with two conditions. That means that the query returns all items, including those with no translation. If you need to return only objects having translations, add `Criteria::INNER_JOIN` as second parameter to `joinWithI18n()`. - -If you need to search items using a condition on a translation, use the generated `useI18nQuery()` as you would with any `useXXXQuery()` method: - -```php -useI18nQuery('en_US') // tests the condition on the English translation - ->filterByName('Microwave oven') - ->endUse() - ->find(); -``` - -## Symfony Compatibility ## - -This behavior is entirely compatible with the i18n behavior for symfony. That means that it can generate `setCulture()` and `getCulture()` methods as aliases to `setLocale()` and `getLocale()`, provided that you add a `locale_alias` parameter. That also means that if you add the behavior to a table without translated columns, and that the translation table is present in the schema, the behavior recognizes them. - -So the following schema is exactly equivalent to the first one in this tutorial: - -```xml -
The more complex the query, the greater the boost you get from the query cache behavior. - -## Parameters ## - -You can change the cache backend and the cache lifetime (in seconds) by setting the `backend` and `lifetime` parameters: - -```xml -
The slug is unique by design. That means that if you create a new object and that the behavior calculates a slug that already exists, the string is modified to be unique: - -```php -setTitle('Hello, World!'); -$p2->save(); -echo $p2->getSlug(); // 'hello-world-1' -``` - -The generated model query offers a `findOneBySlug()` method to easily retrieve a model object based on its slug: - -```php -findOneBySlug('hello-world'); -``` - -## Parameters ## - -By default, the behavior adds one column to the model. If this column is already described in the schema, the behavior detects it and doesn't add it a second time. The behavior parameters allow you to use custom patterns for the slug composition. The following schema illustrates a complete customization of the behavior: - -```xml -
`ModelCriteria::paginate()` executes two queries, so `disableSoftDelete()` doesn't work in this case. Prefer `includeDeleted()` in queries using `paginate()`. - -If you want to recover a deleted object, use the `unDelete()` method: - -```php -unDelete(); -$books = BookQuery::create()->find(); -$book = $books[0]; -echo $book->getTitle(); // 'War And Peace' -``` - -If you want to force the real deletion of an object, call the `forceDelete()` method: - -```php -forceDelete(); -echo $book->isDeleted(); // true -$books = BookQuery::create()->find(); // empty collection -``` - -The query methods `delete()` and `deleteAll()` also perform a soft deletion, unless you disable the behavior on the peer class: - -```php -setTitle('War And Peace'); -$b->save(); - -BookQuery::create()->delete($b); -$books = BookQuery::create()->find(); // empty collection -// the rows look deleted, but they are still there -BookQuery::disableSoftDelete(); -$books = BookQuery::create()->find(); -$book = $books[0]; -echo $book->getTitle(); // 'War And Peace' - -// To perform a true deletion, disable the softDelete feature -BookQuery::disableSoftDelete(); -BookQuery::create()->delete(); -// Alternatively, use forceDelete() -BookQuery::create()->filterByTitle('%Lo%')->forceDelete(); -// To remove all use -BookQuery::create()->forceDeleteAll(); -``` - -## Parameters ## - -You can change the name of the column added by the behavior by setting the `deleted_column` parameter: - -```xml -
You can remove an object from the list without necessarily deleting it by calling `removeFromList()`. Don't forget to `save()` it afterwards so that the other objects in the lists are rearranged to fill the gap. - -## Multiple Lists ## - -When you need to store several lists for a single model - for instance, one task list for each user - use a _scope_ for each list. This requires that you enable scope support in the behavior definition by setting the `use_scope` parameter to `true`: - -```xml -
The behavior adds columns but no index. Depending on your table structure, you might want to add a column index by hand to speed up queries on sorted lists. - -## Complete API ## - -Here is a list of the methods added by the behavior to the model objects: - -```php - $rank associative array -// only for behavior with use_scope -array inList($scope) -``` - -The behavior also adds a few methods to the Peer classes: - -```php - $rank associative array -// only for behavior with use_scope -array retrieveList($scope) -int countList($scope) -int deleteList($scope) -``` diff --git a/behaviors/timestampable.markdown b/behaviors/timestampable.markdown deleted file mode 100644 index cc5b2dde..00000000 --- a/behaviors/timestampable.markdown +++ /dev/null @@ -1,114 +0,0 @@ ---- -layout: documentation -title: Timestampable Behavior ---- - -# Timestampable Behavior # - -The `timestampable` behavior allows you to keep track of the date of creation and last update of your model objects. - -## Basic Usage ## - -In the `schema.xml`, use the `
You may need to keep the update date unchanged after an update on the object, for instance when you only update a calculated row. In this case, call the `keepUpdateDateUnchanged()` method on the object before saving it. - - -## Parameters ## - -You can change the name of the columns added by the behavior by setting the `create_column` and `update_column` parameters: - -```xml -
Versioning of related objects is only possible for simple foreign keys. Relationships based on composite foreign keys cannot preserve relation versionning for now. - -## Parameters ## - -You can change the name of the column added by the behavior by setting the `version_column` parameter. Propel only adds the column if it's not already present, so you can easily customize this column by adding it manually to your schema: - -```xml -
properties, once loaded, are not overridden by properties with the same name unless explicitly told to do so. In the Propel build process, the order of precedence for property values is as follows: - -1. Commandline properties -2. Project `build.properties` -3. Top-level `build.properties` -4. Top-level `default.properties` - -This means, for example, that values specified in the project's `build.properties` files will override those in the top-level `build.properties` and `default.properties` files. - -### Changing values ### - -To get an idea of what you can modify in Propel, simply look through the `build.properties` and `default.properties` files. - -_Note, however, that some of the current values exist for legacy reasons and will be cleaned up in Propel 1.1._ - -#### New build output directories #### - -This can easily be customized on a project-by-project basis. For example, here is a `build.properties` file for the _bookstore _project that puts the generated classes in `/var/www/bookstore/classes` and puts the generated SQL in `/var/www/bookstore/db/sql`: - -```ini -propel.project = bookstore -propel.database = sqlite -propel.database.url = sqlite://localhost/./test/bookstore.db -propel.targetPackage = bookstore - -# directories -propel.output.dir = /var/www/bookstore -propel.php.dir = ${propel.output.dir}/classes -propel.phpconf.dir = ${propel.output.dir}/conf -propel.sql.dir = ${propel.output.dir}/db/sql -``` - -The _targetPackage_ property is also used in determining the path of the generated classes. In the example above, the `Book.php` class will be located at `/var/www/bookstore/classes/bookstore/Book.php`. You can change this `bookstore` subdir by altering the _targetPackage_ property: - -```ini -propel.targetPackage = propelom -``` - -Now the class will be located at `/var/www/bookstore/classes/propelom/Book.php` - -_Note that you can override the targetPackage property by specifying a package="" attribute in the `
If you separate tables related by a foreign key into separate packages (like `book` and `author` in this example), you must enable the `packageObjectModel` build property to let Propel consider other packages for relations. - -You can also override the `package` attribute at the `
You can use subnamespaces (i.e. namespaces containing backslashes) in the `namespace` attribute. - -## Using Namespaced Models ## - -Namespaced models benefit from the Propel runtime autoloading just like the other model classes. You just need to alias them, or to use their fully qualified name. - -```php -setAuthor($author); -$book->save(); -``` - -The namespace is used for the ActiveRecord class, but also for the Query and Peer classes. Just remember that when you use relation names in a query, the namespace should not appear: - -```php -useBookQuery() - ->filterByPrice(array('max' => 10)) - ->endUse() - ->findOne(); -``` - -Related tables can have different namespaces, it doesn't interfere with the functionality provided by the object model: - -```php -findOne(); -echo get_class($book->getPublisher()); -// \Bookstore\Book\Publisher -``` - ->**Tip**
Using namespaces make generated model code incompatible with versions of PHP less than 5.3. Beware that you will not be able to use your model classes in an older PHP application. - -## Using Namespaces As A Directory Structure ## - -In a schema, you can define a `package` attribute on a `
If you're currently starting a new project or just willing to update your `symfony` project, you should consider using the `Propel` i18n behavior integration with `symfony 1.4`. - -All you have to do is to write your `schema.xml` with the old SfPropelBehaviorI18n style `
Remember you should consider using the `Propel` i18n behavior integration with `symfony 1.4`. - - - - - diff --git a/cookbook/symfony1/index.markdown b/cookbook/symfony1/index.markdown deleted file mode 100644 index eff28efe..00000000 --- a/cookbook/symfony1/index.markdown +++ /dev/null @@ -1,12 +0,0 @@ ---- -layout: default -title: Working With symfony 1.4 ---- - -# Working with symfony 1.4 # - -* [Init A Symfony Project With Propel As Default ORM - The Git Way](init-a-Symfony-project-with-Propel-git-way.html) - -* [How To Use Propel i18n Behavior With Symfony 1.4](how-to-use-Propel i18n-behavior-with-sf1.4.html) - -* [How To Use Old SfPropelBehaviori18n (Aka symfony_i18n) With Symfony 1.4](how-to-use-old-SfPropelBehaviori18n-with-sf1.4.html) diff --git a/cookbook/symfony1/init-a-Symfony-project-with-Propel-git-way.markdown b/cookbook/symfony1/init-a-Symfony-project-with-Propel-git-way.markdown deleted file mode 100644 index 3b582e86..00000000 --- a/cookbook/symfony1/init-a-Symfony-project-with-Propel-git-way.markdown +++ /dev/null @@ -1,144 +0,0 @@ ---- -layout: default -title: Init A Symfony Project With Propel As Default ORM - The Git Way ---- - -# Init A Symfony Project With Propel As Default ORM - The Git Way # - -Since this summer (2011) `Propel` ORM has a new `symfony` integration plugin `sfPropelORMPlugin` replacing the old one `sfPropel15Plugin`. - -The old `sfPropel15Plugin` caused [some confusion at each new Propel's version](http://propel.posterous.com/sfpropel16plugin-is-already-there-didnt-you-k). -Now `sfPropelORMPlugin` will always integrate the last `Propel`'s version to `Symfony 1.4`. - -You'll learn how to set up a new `symfony 1.4` project with all necessary libraries as git submodules. - -First, set up a new project: - -{% highlight bash %} -mkdir propel_project -cd propel_project -git init -{% endhighlight %} - -Install `symfony 1.4` as a git submodule: - -{% highlight bash %} -git submodule add git://github.com/symfony/symfony1.git lib/vendor/symfony -{% endhighlight %} - -Generate a symfony project: - -{% highlight bash %} -php lib/vendor/symfony/data/bin/symfony generate:project propel -{% endhighlight %} - -Add the `sfPropelORMPlugin` plugin: - -{% highlight bash %} -git submodule add git://github.com/propelorm/sfPropelORMPlugin plugins/sfPropelORMPlugin -{% endhighlight %} - -Get Propel and Phing bundled with the plugin: - -{% highlight bash %} -cd plugins/sfPropelORMPlugin -git submodule update --init -{% endhighlight %} - -You should add a `.gitignore` file with the following content: - -{% highlight bash %} -config/databases.yml -cache/* -log/* -data/sql/* -lib/filter/base/* -lib/form/base/* -lib/model/map/* -lib/model/om/* -{% endhighlight %} - -Now, enable `sfPropelORMPlugin` in `config/ProjectConfiguration.class.php`: - -{% highlight php %} -enablePlugins('sfPropelORMPlugin'); - } -} -{% endhighlight %} - -Publish assets: - -{% highlight bash %} -php symfony plugin:publish-assets -{% endhighlight %} - -Copy the `propel.ini` default file in your project: - -{% highlight bash %} -cp plugins/sfPropelORMPlugin/config/skeleton/config/propel.ini config/propel.ini -{% endhighlight %} - -Verify behaviors lines look like: - -{% highlight ini %} -// config/propel.ini - -propel.behavior.symfony.class = plugins.sfPropelORMPlugin.lib.behavior.SfPropelBehaviorSymfony -propel.behavior.symfony_i18n.class = plugins.sfPropelORMPlugin.lib.behavior.SfPropelBehaviorI18n -propel.behavior.symfony_i18n_translation.class = plugins.sfPropelORMPlugin.lib.behavior.SfPropelBehaviorI18nTranslation -propel.behavior.symfony_behaviors.class = plugins.sfPropelORMPlugin.lib.behavior.SfPropelBehaviorSymfonyBehaviors -propel.behavior.symfony_timestampable.class = plugins.sfPropelORMPlugin.lib.behavior.SfPropelBehaviorTimestampable -{% endhighlight %} - -Adapt your `databases.yml` or copy the model in your project: - -{% highlight bash %} -cp plugins/sfPropelORMPlugin/config/skeleton/config/databases.yml config/databases.yml -{% endhighlight %} - -It has to look like this: - -{% highlight yaml %} -# You can find more information about this file on the symfony website: -# http://www.symfony-project.org/reference/1_4/en/07-Databases - -dev: - propel: - param: - classname: DebugPDO - debug: - realmemoryusage: true - details: - time: { enabled: true } - slow: { enabled: true, threshold: 0.1 } - mem: { enabled: true } - mempeak: { enabled: true } - memdelta: { enabled: true } - -test: - propel: - param: - classname: DebugPDO - -all: - propel: - class: sfPropelDatabase - param: - classname: PropelPDO - dsn: mysql:dbname=test;host=localhost - username: root - password: - encoding: utf8 - persistent: true - pooling: true -{% endhighlight %} - ->**Warning**
If your PHP version is under 5.3.6 you won't be allowed to set the `encoding` parameter due to a security issue in PHP. - -You're now ready for writing a `schema.xml` and building your project. \ No newline at end of file diff --git a/cookbook/symfony2/adding-a-new-behavior-in-symfony2.markdown b/cookbook/symfony2/adding-a-new-behavior-in-symfony2.markdown deleted file mode 100644 index d65666a1..00000000 --- a/cookbook/symfony2/adding-a-new-behavior-in-symfony2.markdown +++ /dev/null @@ -1,44 +0,0 @@ ---- -layout: default -title: Adding A New Behavior In Symfony2 ---- - -# Adding A New Behavior In Symfony2 # - -Propel provides a lot of [behaviors](../../documentation/07-behaviors.html) but there are also [third-party behaviors](../user-contributed-behaviors.html) provided by the community. - -In order to get these behaviors working in a Symfony2 application with Propel, you need to register them, here is -how you should do. - -The first step is to get the code. If the behavior is available on a Git repository, like GitHub for instance, -then you'll be able to add it to your `deps` file. -Assuming you want to use the [GeocodableBehavior](https://github.com/willdurand/GeocodableBehavior), you'll write: - -{% highlight bash %} -[GeocodableBehavior] - git=http://github.com/willdurand/GeocodableBehavior.git - target=/willdurand/propel-geocodable-behavior -{% endhighlight %} - -If you are using Git submodules, then run: - -{% highlight bash %} -git submodule add http://github.com/willdurand/GeocodableBehavior.git vendor/willdurand/propel-geocodable-behavior -{% endhighlight %} - -If you are using [Composer](http://getcomposer.org), then just require the behavior in your `composer.json`: - -{% highlight javascript %} -{ - "require": { - // ... - "willdurand/propel-geocodable-behavior": "dev-master" - } -} -{% endhighlight %} - -And run, `php composer.php update`. - ->**Tip**
If there is no available Git repository for a behavior, just copy it to `vendor/propel-thebehavior-behavior`. It's up to you to version it or not. - -You're done! diff --git a/cookbook/symfony2/images/basic_form.png b/cookbook/symfony2/images/basic_form.png deleted file mode 100644 index 6b723643..00000000 Binary files a/cookbook/symfony2/images/basic_form.png and /dev/null differ diff --git a/cookbook/symfony2/images/many_to_many_form.png b/cookbook/symfony2/images/many_to_many_form.png deleted file mode 100644 index bdd8f69e..00000000 Binary files a/cookbook/symfony2/images/many_to_many_form.png and /dev/null differ diff --git a/cookbook/symfony2/images/many_to_many_form_with_existing_objects.png b/cookbook/symfony2/images/many_to_many_form_with_existing_objects.png deleted file mode 100644 index 65581303..00000000 Binary files a/cookbook/symfony2/images/many_to_many_form_with_existing_objects.png and /dev/null differ diff --git a/cookbook/symfony2/images/one_to_many_form.png b/cookbook/symfony2/images/one_to_many_form.png deleted file mode 100644 index 3d0f7fb6..00000000 Binary files a/cookbook/symfony2/images/one_to_many_form.png and /dev/null differ diff --git a/cookbook/symfony2/images/one_to_many_form_with_collection.png b/cookbook/symfony2/images/one_to_many_form_with_collection.png deleted file mode 100644 index f316cd05..00000000 Binary files a/cookbook/symfony2/images/one_to_many_form_with_collection.png and /dev/null differ diff --git a/cookbook/symfony2/index.markdown b/cookbook/symfony2/index.markdown deleted file mode 100644 index cc46b7b8..00000000 --- a/cookbook/symfony2/index.markdown +++ /dev/null @@ -1,18 +0,0 @@ ---- -layout: default -title: Working With Symfony2 ---- - -# Working With Symfony2 # - -* [Working with Symfony2 (Introduction)](working-with-symfony2.html) - -* [Symfony2 And Propel In Real Life](symfony2-and-propel-in-real-life.html) - -* [Mastering Symfony2 Forms With Propel](mastering-symfony2-forms-with-propel.html) - -* [The Symfony2 Security Component And Propel](the-symfony2-security-component-and-propel.html) - -* [Adding A New Behavior In Symfony2](adding-a-new-behavior-in-symfony2.html) - -* [Testing](testing.html) diff --git a/cookbook/symfony2/mastering-symfony2-forms-with-propel.markdown b/cookbook/symfony2/mastering-symfony2-forms-with-propel.markdown deleted file mode 100644 index 9c40d467..00000000 --- a/cookbook/symfony2/mastering-symfony2-forms-with-propel.markdown +++ /dev/null @@ -1,535 +0,0 @@ ---- -layout: documentation -title: Mastering Symfony2 Forms With Propel ---- - -# Mastering Symfony2 Forms With Propel # - -In this chapter, you'll learn how to master Symfony2 forms with Propel. - ->**Code along with the example**
If you want to follow along with the example in this chapter, create a `LibraryBundle` bundle by using this command: `php app/console generate:bundle --namespace=Acme/LibraryBundle`. - -Assuming you manage `Book` and `Author` objects, you'll define the following `schema.xml`: - -{% highlight xml %} - -
-If you want a `Type` generated from a `Model`, you can use the Symfony2 console. -For the following example, the command is: -`php app/console propel:form:generate @AcmeLibraryBundle Book` - -{% highlight php %} -add('title'); - $builder->add('isbn'); - } - - public function setDefaultOptions(OptionsResolverInterface $resolver) - { - $resolver->setDefaults(array( - 'data_class' => 'Acme\LibraryBundle\Model\Book', - )); - } - - public function getName() - { - return 'book'; - } -} -{% endhighlight %} - ->**Setting the `data_class`**
Every form needs to know the name of the class that holds the underlying data (e.g. `Acme\LibraryBundle\Model\Book`). Usually, this is just guessed based off of the object passed to the second argument to createForm(). - -Basically, you will use this class in an action of one of your controllers. -Assuming you have a `BookController` controller in your `LibraryBundle`, you will -write the following code to create new books: - -{% highlight php %} -createForm(new BookType(), $book); - - return $this->render('AcmeLibraryBundle:Book:new.html.twig', array( - 'form' => $form->createView(), - )); - } -} -{% endhighlight %} - ->**Warning**
To quickly explain how forms are rendered, the controller above extends the `Controller` class which provides the `render()` method used to return a `Response` but this is not considered as a best practice. It's better to create a controller as a service. - -To render the form, you'll need to create a Twig template like below: - -{% highlight django %} -{# src/Acme/LibraryBundle/Resources/views/Book/new.html.twig #} - - -{% endhighlight %} - -You'll get this result: - - - -As such, the topic of persisting the `Book` object to the database is entirely -unrelated to the topic of forms. But, if you've created a `Book` class with Propel, -then persisting it after a form submission can be done when the form is valid: - -{% highlight php %} -createForm(new BookType(), $book); - - $request = $this->getRequest(); - - if ('POST' === $request->getMethod()) { - $form->handleRequest($request); - - if ($form->isValid()) { - $book->save(); - - return $this->redirect($this->generateUrl('book_success')); - } - } - - return $this->render('AcmeLibraryBundle:Book:new.html.twig', array( - 'form' => $form->createView(), - )); - } -} -{% endhighlight %} - ->**Note**
`handleRequest` has been introduced in Symfony 2.3. Be sure to use -`bindRequest` instead in previous versions of Symfony. - -If, for some reason, you don't have access to your original `$book` object, -you can fetch it from the form: - -{% highlight php %} -getData(); -{% endhighlight %} - -As you can see, this is really easy to manage basic forms with both Symfony2 -and Propel. But, in real life, this kind of forms is not enought and you'll probably -manage objects with relations, this is the next part of this chapter. - - -## One-To-Many relations ## - -A `Book` has an `Author`, this is a **One-To-Many** relation. Let's modifing your -`BookType` to handle this relation: - -{% highlight php %} -add('title'); - $builder->add('isbn'); - // Author relation - $builder->add('author', new AuthorType()); - } - - public function setDefaultOptions(OptionsResolverInterface $resolver) - { - $resolver->setDefaults(array( - 'data_class' => 'Acme\LibraryBundle\Model\Book' - )); - } - - public function getName() - { - return 'book'; - } -} -{% endhighlight %} - -You now have to write an `AuthorType` to reflect the new requirements: - -{% highlight php %} -add('first_name'); - $builder->add('last_name'); - } - - public function setDefaultOptions(OptionsResolverInterface $resolver) - { - $resolver->setDefaults(array( - 'data_class' => 'Acme\LibraryBundle\Model\Author', - ); - } - - public function getName() - { - return 'author'; - } -} -{% endhighlight %} - -If you refresh your page, you'll now get the following result: - - - -When the user submits the form, the submitted data for the `Author` fields are used to construct an -instance of `Author`, which is then set on the author field of the `Book` instance. -The `Author` instance is accessible naturally via $book->getAuthor(). - -But you could have the following use case: to add books to an author. The main type will be the `AuthorType` as below: - -{% highlight php %} -add('first_name'); - $builder->add('last_name'); - $builder->add('books', 'collection', array( - 'type' => new \Acme\LibraryBundle\Form\Type\BookType(), - 'allow_add' => true, - 'allow_delete' => true, - 'by_reference' => false, - )); - } - - public function setDefaultOptions(OptionsResolverInterface $resolver) - { - $resolver->setDefaults(array( - 'data_class' => 'Acme\LibraryBundle\Model\Author', - ); - } - - public function getName() - { - return 'author'; - } -} -{% endhighlight %} - -You'll also need to refactor your `BookType`: - -{% highlight php %} -add('title'); - $builder->add('isbn'); - } - - public function setDefaultOptions(OptionsResolverInterface $resolver) - { - $resolver->setDefaults(array( - 'data_class' => 'Acme\LibraryBundle\Model\Book', - ); - } - - public function getName() - { - return 'book'; - } -} -{% endhighlight %} - -When you'll create a new `Author` object, you'll be able to add a set of new `Books` objects and they will be -linked to this author without any effort thanks to Propel and specific methods to handle collections on related objects. - - - - -## Many-To-Many relations ## - -Now, imagine you want to add your books to some lists for book clubs. A `BookClubList` can have many -`Book` objects and a `Book` can be in many lists (`BookClubList`). This is a **Many-To-Many** relation. - -Add the following defintion to your `schema.xml ` and rebuild your model classes: - -{% highlight xml %} -
The parameter `by_reference` has to be defined and set to `false`. This is required to tell the Form Component to call the setter method (`setBooks()` in this example). - -Thanks to the smart collection setter provided by Propel, there is nothing more to configure. -Use the `BookClubListType` as you previously did with the `BookType`. Note the Symfony2 Form Component -doesn't handle the add/remove abilities in the view. You have to write some JavaScript for that. - - - -### The ModelType ### - -In the previous example, you always create new objects. - -If you want to select existing authors when you create new books, you'll have to - use a `Model` type. -You can change the text wich be displayed by passing the `property` argument. If - left blank, the `__toString()` method will be used. - -{% highlight php %} -add('title'); - $builder->add('isbn'); - - //$builder->add('author', new AuthorType()); - $builder->add('author', 'model', array( - 'class' => 'Acme\LibraryBundle\Model\Author', - 'property' => 'fullname', - )); - } - - public function setDefaultOptions(OptionsResolverInterface $resolver) - { - $resolver->setDefaults(array( - 'data_class' => 'Acme\LibraryBundle\Model\Book', - ); - } - - public function getName() - { - return 'book'; - } -} -{% endhighlight %} - -You'll obtain the following result: - - - ->**Information**
The `ModelType` is part of the [`Symfony Propel Bridge`](https://github.com/symfony/symfony/blob/master/src/Symfony/Bridge/Propel1/). - -## Validation ## - -Using Propel in a Symfony2 project lacks a convenient way to use validation through annotation. -Instead you have to use classic validation process, using a validation (in yml, xml or php format) file. - -In order to use this type of validation you must configure your application. - -In YAML: - -{% highlight yaml %} -# in app/config/config.yml -framework: - validation: { enabled: true } -{% endhighlight %} - -In XML: - -{% highlight xml %} - -
This documentation is for Symfony2 2.1. If you are using Symfony2 2.0.x, please follow [this documentation](https://github.com/propelorm/propelorm.github.com/blob/d1dbefdd6346f36e72d3349934ef2768ebe1a0c8/cookbook/symfony2/the-symfony2-security-component-and-propel.markdown). - -If you've started to play with the awesome Symfony2 Security Component, you'll know that you can configure a **provider** -to retrieve your users. Symfony2, and the PropelBundle provide a `propel` provider, so you just need to add the following -configuration to your `security.yml` file: - -{% highlight yaml %} -# app/config/security.yml -providers: - main: - propel: - class: My\AwesomeBundle\Model\User - property: username -{% endhighlight %} - -Your `User` class have to implement the [`UserInterface`](https://github.com/symfony/symfony/blob/master/src/Symfony/Component/Security/Core/User/UserInterface.php): - -{% highlight php %} -**Tip**
Different bundle version may be needed for different Symfony2 version. Check [PropelBundle](https://github.com/propelorm/PropelBundle) for details. - -Alternatively, you can use Git, SVN, Git submodules, or the Symfony vendor management (deps file): - -Clone this bundle in the `vendor/bundles/Propel` directory: - - > git submodule add https://github.com/propelorm/PropelBundle.git vendor/bundles/Propel/PropelBundle - -Checkout Propel and Phing in the `vendor` directory: - - > svn checkout http://svn.github.com/propelorm/Propel.git vendor/propel - - > svn checkout http://svn.phing.info/tags/2.4.6/ vendor/phing - -Instead of using svn, you can clone the unofficial Git repositories: - - > git submodule add https://github.com/phingofficial/phing.git vendor/phing - - > git submodule add https://github.com/propelorm/Propel.git vendor/propel - -Instead of doing this manually, you can use the Symfony vendor management via the deps file. -If you are using a Symfony2 2.x.x version (actually, a version which is not 2.1 or above), -be sure to deps.lock the PropelBundle to a commit on the 2.0 branch, which does not use the Bridge - - -The second step is to register this bundle in the `AppKernel` class: - -{% highlight php %} -registerNamespaces(array( - // ... - 'Propel' => __DIR__.'/../vendor/bundles', -)); -$loader->registerPrefixes(array( - // ... - 'Phing' => __DIR__.'/../vendor/phing/classes/phing', -)); -{% endhighlight %} - -You are almost ready, the next steps are: - -* to [configure the bundle](#configuration); -* to [configure Propel](#propel-configuration); -* to [write an XML schema](#xml-schema). - -Now, you can build your model classes, and SQL by running the following command: - - > php app/console propel:build [--classes] [--sql] [--insert-sql] - -To insert SQL statements, use the `propel:sql:insert` command: - - > php app/console propel:sql:insert [--force] - -Note that the `--force` option is needed to actually execute the SQL statements. - -Congratulations! You're done; just use the Model classes as any other class in Symfony2: - -{% highlight php %} -setFirstName($name); - $author->save(); - - return $this->render('AcmeDemoBundle:Hello:index.html.twig', array( - 'name' => $name, 'author' => $author) - ); - } -} -{% endhighlight %} - -## Bundle Inheritance ## - -The `PropelBundle` makes use of the bundle inheritance. Currently only schema inheritance is provided. - -### Schema Inheritance ### - -You can override the defined schema of a bundle from within its child bundle. -To make use of the inheritance you only need to drop a schema file in the `Resources/config` folder of the child bundle. - -Each file can be overridden without interfering with other schema files. -If you want to remove parts of a schema, you only need to add an empty schema file. - -## Configuration ## - -### Symfony configuration ### - -In order to use Propel, you have to configure few parameters in your `app/config/config.yml` file. - -If you are **not** using Composer, add this configuration: - -{% highlight yaml %} -# in app/config/config.yml -propel: - path: "%kernel.root_dir%/../vendor/propel" - phing_path: "%kernel.root_dir%/../vendor/phing" -{% endhighlight %} - -Now, you can configure your application. - - -#### Basic Configuration #### - -If you have just one database connection, your configuration will look like as following: - -{% highlight yaml %} -# app/config/config*.yml -propel: - dbal: - driver: mysql - user: root - password: null - dsn: mysql:host=localhost;dbname=test;charset=UTF8 - options: {} - attributes: {} -{% endhighlight %} - -The recommended way to fill in these information is to use parameters: - - -{% highlight yaml %} -# app/config/config*.yml -# define the parameters in app/config/parameters.yml -propel: - dbal: - driver: %database_driver% - user: %database_user% - password: %database_password% - dsn: %database_driver%:host=%database_host%;dbname=%database_name%;charset=UTF8 - options: {} - attributes: {} -{% endhighlight %} - - -#### Configure Multiple Connection #### - -If you have more than one connection, or want to use a named connection, the configuration -will look like: - -{% highlight yaml %} -# app/config/config*.yml -propel: - dbal: - default_connection: conn1 - connections: - conn1: - driver: mysql - user: root - password: null - dsn: mysql:host=localhost;dbname=db1 - conn2: - driver: mysql - user: root - password: null - dsn: mysql:host=localhost;dbname=db2 -{% endhighlight %} - - -#### Configure Master/Slaves #### - -You can also configure Master/Slaves: - -{% highlight yaml %} -# app/config/config*.yml -propel: - dbal: - default_connection: default - connections: - default: - driver: mysql - user: root - password: null - dsn: mysql:host=localhost;dbname=master - slaves: - slave_1: - user: root - password: null - dsn: mysql:host=localhost;dbname=slave_1 -{% endhighlight %} - - -#### Attributes, Options, Settings #### - -{% highlight yaml %} -# app/config/config*.yml -propel: - dbal: - default_connection: default - connections: - default: - # ... - options: - ATTR_PERSISTENT: false - attributes: - ATTR_EMULATE_PREPARES: true - settings: - charset: { value: UTF8 } - queries: { query: 'INSERT INTO BAR ('hey', 'there')' } -{% endhighlight %} - -`options`, `attributes` and `settings` are parts of the runtime configuration. See [Runtime Configuration File](http://www.propelorm.org/reference/runtime-configuration.html) documentation for more explanation. - - -#### Logging #### - -You can disable the logging by changing the `logging` parameter value: - -{% highlight yaml %} -# in app/config/config.yml -propel: - logging: %kernel.debug% -{% endhighlight %} - -### Propel Configuration ### - -You can add a `app/config/propel.ini` file in your project to specify some -configuration parameters. See the [Build properties Reference]( -http://www.propelorm.org/reference/buildtime-configuration.html) to get more -information. However, **the recommended way** to configure Propel is to rely -on **build properties**, see the section below. - -By default the PropelBundle is configured with the default parameters: - -{% highlight ini %} -# Enable full use of the DateTime class. -# Setting this to true means that getter methods for date/time/timestamp -# columns will return a DateTime object when the default format is empty. -propel.useDateTimeClass = true - -# Specify a custom DateTime subclass that you wish to have Propel use -# for temporal values. -propel.dateTimeClass = DateTime - -# These are the default formats that will be used when fetching values from -# temporal columns in Propel. You can always specify these when calling the -# methods directly, but for methods like getByName() it is nice to change -# the defaults. -# To have these methods return DateTime objects instead, you should set these -# to empty values -propel.defaultTimeStampFormat = -propel.defaultTimeFormat = -propel.defaultDateFormat = - -# A better Pluralizer -propel.builder.pluralizer.class = builder.util.StandardEnglishPluralizer -{% endhighlight %} - - -#### Build properties #### - -You can define _build properties_ by creating a `propel.ini` file in `app/config` like below, but you can also follow -the Symfony2 convention by adding build properties in `app/config/config.yml`: - -{% highlight yaml %} -# app/config/config.yml -propel: - build_properties: - xxxxx.xxxx.xxxxx: XXXX - xxxxx.xxxx.xxxxx: XXXX - // ... -{% endhighlight %} - - -#### Behaviors #### - -You can register Propel behaviors using the following syntax: - -{% highlight yaml %} -# app/config/config.yml -propel: - behaviors: - behavior_name: My\Bundle\Behavior\BehaviorClassName -{% endhighlight %} - -If you rely on third party behaviors, most of them are autoloaded so you don't -need to register them. But, for your own behaviors, you can either configure the -autoloader to autoload them, or register them in this section (this is the -recommended way when you namespace your behaviors). - -## XML Schema ## - -Place the following schema in `src/Acme/DemoBundle/Resources/config/schema.xml`: - -{% highlight xml %} - -
The convention is to prefix your package name with propel-, and to suffix it with -behavior. - - -## Configuring PHPUnit ## - -If you run the command below, Composer will setup your behavior to run the test suite: - - php composer.phar install --dev - -Now, you have to configure your project for PHPUnit. It's really easy. Start by copying the following `phpunit.xml.dist` file: - -```xml - -
On RDBMS that do not support SQL schemas (Oracle, SQLite), the `schema` attribute is ignored. - -You can also assign a table to a given schema individually ; this overrides the `schema` of the parent `
Propel does not take care of creating the schema. The target database must already contain the required schemas, and the user credentials must allow Propel to access this schema. - -## Schemas in PHP Code ## - -Just like actual table names, SQL schemas don't appear in the PHP code. For the PHP developer, who manipulates phpNames, it's as if schemas didn't existed. - -Of course, you can make queries spanning across several schemas. - ->**Tip**
in Mysql, "SCHEMA" and "DATABASE" are synonyms. Therefore, the ability to define another schema for a given table actually allows cross-database queries. - -## Using the Schema As Base for PHP code Organization ## - -Propel provides other features to organize your model: - -* _Packages_ are subdirectories in which Model classes get generated (see [Multi-Component Data Model](./multi-component-data-model.html)) -* _Namespaces_ are actual PHP5.3 namespaces for generated Model classes (see [PHP 5.3 Namespaces](./namespaces.html)) - -You can easily tell Propel to copy the `schema` attribute to both the `package` and the `namespace` attributes, in order to reproduce the SQL organization at the PHP level. To that extent, modify the following settings in `build.properties`: - -```ini -propel.schema.autoPackage = true -propel.schema.autoNamespace = true -``` - -With such a configuration, a `book` table assigned to the `bookstore` schema will generate a `Bookstore\Book` ActiveRecord class under the `bookstore/` subdirectory. - -If you're stuck with PHP 5.2, you probably need to use the schema name as a class prefix rather than a namespace. That's what the `autoPrefix` setting is for: - -```ini -propel.schema.autoPrefix = true -``` - -With such a configuration, a `book` table assigned to the `bookstore` schema will generate a `BookstoreBook` ActiveRecord class. diff --git a/cookbook/working-with-advanced-column-types.markdown b/cookbook/working-with-advanced-column-types.markdown deleted file mode 100644 index 41bcf9c5..00000000 --- a/cookbook/working-with-advanced-column-types.markdown +++ /dev/null @@ -1,215 +0,0 @@ ---- -layout: documentation -title: Working with Advanced Column Types ---- - -# Working with Advanced Column Types # - -Propel offers a set of advanced column types. The database-agnostic implementation allows these types to work on all supported RDBMS. - -## LOB Columns ## - -Propel uses PHP streams internally for storing _Binary_ Locator Objects (BLOBs). This choice was made because PDO itself uses streams as a convention when returning LOB columns in a resultset and when binding values to prepared statements. Unfortunately, not all PDO drivers support this (see, for example, [http://bugs.php.net/bug.php?id=40913](http://bugs.php.net/bug.php?id=40913)); in those cases, Propel creates a `php://temp` stream to hold the LOB contents and thus provide a consistent API. - -Note that CLOB (_Character_ Locator Objects) are treated as strings in Propel, as there is no convention for them to be treated as streams by PDO. - -### Getting BLOB Values ### - -BLOB values will be returned as PHP stream resources from the accessor methods. Alternatively, if the value is NULL in the database, then the accessors will return the PHP value NULL. - -```php -getCoverImage(); -if ($fp !== null) { - echo stream_get_contents($fp, -1, 0); // important to use 0 as offset so it works when being called multiple times -} -``` - -### Setting BLOB Values ### - -When setting a BLOB column, you can either pass in a stream or the blob contents. - -```php -setCoverImage($fp); - -// Setting using file contents -$media = new Media(); -$media->setCoverImage(file_get_contents("/path/to/file.ext")); -``` - -Regardless of which setting method you choose, the BLOB will always be represented internally as a stream resource -- _and subsequent calls to the accessor methods will return a stream._ - -For example: -```php -setCoverImage(file_get_contents("/path/to/file.ext")); - -$fp = $media->getCoverImage(); -print gettype($fp); // "resource" -``` - -### Setting BLOB columns and isModified() ### - -Note that because a stream contents may be externally modified, _mutator methods for BLOB columns will always set the _isModified()_ to report true_ -- even if the stream has the same identity as the stream that was returned. - -For example: -```php -getCoverImage(); -$media->setCoverImage($fp); - -var_export($media->isModified()); // TRUE -``` - -## ENUM Columns ## - -Although stored in the database as integers, ENUM columns let users manipulate a set of predefined values, without worrying about their storage. - -```xml -
Filters on array columns translate to SQL as LIKE conditions. That means that the resulting query often requires a full table scan, and is not suited for large tables. - -### Using default values ### - -You may want to add default values to your `ARRAY` column, Propel 1.6.6, and upper allows to use the `defaultValue` -attribute in your XML schema to set a list of values as comma separated values: - -```xml -
The reverse engineering classes may not be able to provide the same level of detail for all databases. In particular, metadata information for SQLite is often very basic since SQLite is a typeless database. - -### Migrating Structure to a New RDBMS ### - -Because Propel has both the ability to create XML schema files based on existing database structures and to create RDBMS-specific DDL SQL from the XML schema file, you can use Propel to convert one database into another. - -To do this you would simply: - - 1. Follow the steps above to create the `schema.xml` file from existing db. - 2. Then you would change the target database type and specify connection URL for new database in the project's `build.properties` file: - -```ini -propel.database = pgsql -propel.database.url = pgsql://unix+localhost/newlegacyapp -``` - - 3. And then run the `sql` task to generate the new DDL: - -```bash -> propel-gen sql -``` - - 4. And (optionally) the `insert-sql` task to create the new database: - -```bash -> propel-gen insert-sql -``` - -## Working with Database Data ## - -Propel also provides several tasks to facilitate data import/export. The most important of these are `datadump` and `datasql`. The first dumps data to XML and the second converts the XML data dump to a ready-to-insert SQL file. - ->**Tip**
Both of these tasks require that you already have generated the `schema.xml` for your database. - -### Dumping Data to XML ### - -Once you have created (or reverse-engineered) your `schema.xml` file, you can run the `datadump` task to dump data from the database into a `data.xml` file. - -```bash -> propel-gen datadump -``` - -The task transfers database records to XML using a simple format, where each row is an element, and each column is an attribute. So for instance, the XML representation of a row in a `publisher` table: - -|publisher_id |name -|---------------|-------------- -|1 |William Morrow - -... is rendered in the `data.xml` as follows: - -```xml -
To run the unit tests for the namespace support in PHP 5.3, you must also configure the `fixtures/namespaced` project. - -
- ->**Tip**
To run the unit tests for the database schema support, you must also configure the `fixtures/schemas` project. This projects requires that your database supports schemas, and already contains the following schemas: `bookstore_schemas`, `contest`, and `second_hand_books`. Note that the user defined in `build.properties` and `runtime-conf.xml` must have access to these schemas. - - -### Get PHPUnit ### - -You can get PHPUnit here: [https://github.com/sebastianbergmann/phpunit/](https://github.com/sebastianbergmann/phpunit/). - -The fastest way to get it is: - - wget http://pear.phpunit.de/get/phpunit.phar - chmod +x phpunit.phar - -This manual is based on this `phpunit.phar`. - -### Get Phing ### - -To get phing, you can download it manually -([http://www.phing.info/trac/wiki/Users/Download](http://www.phing.info/trac/wiki/Users/Download)) -or use [Composer](http://getcomposer.org/). - - curl -s https://getcomposer.org/installer | php - -or - - wget http://getcomposer.org/composer.phar - -and then: - - php composer.phar install - - -## Preparing fixures ## - -Every time you start using the test suite with a new Propel repository you should fire: - - ./test/reset_tests.sh - -It prepares all required `fixures` and creates some tables in your databases. -So if you re-setup your databases, re-run this script. - -If you get something like: - - [ bookstore ] - No VERSION.TXT file found; try setting phing.home environment variable. - -then you don't have setup Phing correctly. - -If you get messages like: - - BUILD FAILED - Propel/generator/build.xml:95:15: No project directory specified - -then this is OK - just ignore them. - -## Writing Tests ## - -### How the Tests Work ### - -Every method in the test classes that begins with `test` is run as a test case by PHPUnit. -All tests are run in isolation; the `setUp()` method is called at the beginning of "each" -test and the `tearDown()` method is called at the end. - -The `BookstoreTestBase` class specifies `setUp()` and `tearDown()` methods which populate -and depopulate, respectively, the database. -This means that every unit test is run with a cleanly populated database. -To see the sample data that is populated, take a look at the `BookstoreDataPopulator` class. -You can also add data to this class, if needed by your tests; however, proceed cautiously when -changing existing data in there as there may be unit tests that depend on it. More typically, -you can simply create the data you need from within your test method. It will be deleted by the -`tearDown()` method, so no need to clean up after yourself. - - -If you've made a change to a template or to Propel behavior, the right thing to do is write a -unit test that ensures that it works properly -- and continues to work in the future. - -### Write one ### - -Writing a unit test often means adding a method to one of the existing test classes. For example, -let's test a feature in the Propel templates that supports saving of objects when only default -values have been specified. Just add a `testSaveWithDefaultValues()` method to the -`GeneratedObjectTest` class (test/testsuite/generator/builder/om/GeneratedObjectTest.php), as -follows: - -```php -setName('Penguin'); - // in the past this wouldn't have marked object as modified - // since 'Penguin' is the value that's already set for that attrib - $pub->save(); - - // if getId() returns the new ID, then we know save() worked. - $this->assertNotNull($pub->getId(), "Expect Publisher->save() to work with only default values."); - } - -[...] - -} - -?> -``` - - -You can also write additional unit test classes to any of the directories in `test/testsuite/` -(or add new directories if needed). PHPUnit command will find these files automatically and run them. - - -## Start the magic ## - -Now you should be ready to go with PHPUnit. - -To start all tests, run: - - ./phpunit.phar - -To start only one test, run: - - ./phpunit.phar test/testsuite/generator/model/TableTest.php - - -If you get - - OK, but incomplete or skipped tests! - -then anything looks quite good :-) - - - -### Errors #### - -If you get something like: - - Fatal error: Call to a member function isCommitable() on a non-object in test/tools/helpers/bookstore/BookstoreTestBase.php on line 43 - -then you have probably not created all necessary databases or you credentials are wrong. - -If you get a lot of errors in your first line, then you probably didn't fire the `./test/reset_tests.sh`. diff --git a/cookbook/writing-behavior.markdown b/cookbook/writing-behavior.markdown deleted file mode 100644 index b53eed33..00000000 --- a/cookbook/writing-behavior.markdown +++ /dev/null @@ -1,432 +0,0 @@ ---- -layout: documentation -title: How to Write A Behavior ---- - -# How to Write A Behavior # - -Behaviors are a good way to reuse code across models without requiring inheritance (a.k.a. horizontal reuse). This step-by-step tutorial explains how to port model code to a behavior, focusing on a simple example. - -In the tutorial "[Keeping an Aggregate Column up-to-date](http://propel.posterous.com/getting-to-know-propel-15-keeping-an-aggregat)", posted in the [Propel blog](http://propel.posterous.com/), the `TotalNbVotes` property of a `PollQuestion` object was updated each time a related `PollAnswer` object was saved, edited, or deleted. This "aggregate column" behavior was implemented by hand using hooks in the model classes. To make it truly reusable, the custom model code needs to be refactored and moved to a Behavior class. - -## Boostrapping A Behavior ## - -A behavior is a class that can alter the generated classes for a table of your model. It must only extend the `Behavior` class and implement special "hook" methods. Here is the class skeleton to start with for the `aggregate_column` behavior: - -```php - null, - ); -} -``` - -Save this class in a file called `AggregateColumnBehavior.php`, and set the path for the class file in the project `build.properties` (just replace directory separators with dots). Remember that the `build.properties` paths are relative to the include path: - -```ini -propel.behavior.aggregate_column.class = path.to.AggregateColumnBehavior -``` - -Test the behavior by adding it to a table of your model, for instance to a `poll_question` table: - -```xml -
Propel uses the PDO and SPL components, which are bundled and enabled by default in PHP5. - -## Project-Local Installation ## - -For a quick start, the best choice is to install Propel inside a project directory structure, typically under a `vendor/` subdirectory: -You could install propel manually into the your `vendor` directory, or let [composer](http://getcomposer.org/) do the job for you. - -### Composer Installation ### - - -The only thing you need to do is, to drop the following line into your projects' `composer.json` file. - -```yaml -{ - "require": { - "propel/propel1": "~1.6" - } -} -``` - -composer will also take care to download all dependencies which are required by Propel. - ->**Note**
Composer requires [PHP 5.3.2+](http://www.php.net/). In case you are running PHP5.2.X you should stick to the "Manual Installation" - -### Manual Installation ### - -```bash -myproject/ - ... - vendor/ <= This is where third-party libraries usually go -``` - -To install Propel there using Git, type: - -```bash -cd myproject/vendor -git clone https://github.com/propelorm/Propel.git propel -``` - -This will export the propel library to a local `myproject/vendor/propel/` directory. - -Alternatively, to use a tarball, type the following commands on unix platforms: - -```bash -cd myproject/vendor -wget http://files.propelorm.org/propel-1.6.X.tar.gz -tar zxvf propel-1.6.X.tar.gz -mv propel-1.6.X propel -``` - -Or, in Windows, download a ZIP from [files.propelorm.org](http://files.propelorm.org), unzip it under the `vendor/` directory, and rename it to `propel`. - -## Propel Directory Structure ## - -The root directory of the Propel library includes the following folders: - -|Folders |Explanations -|---------------|---------------------------------------------------------------------- -|generator |Contains the classes required to run Propel in the command line. Propel commands can build the object model, compile configuration files, execute migrations, etc. -|runtime |Contains the classes required to access Propel models and the database. Typically, applications using a web server will only access the `runtime` directory and not the `generator`. -|tests |Propel unit tests. Ignore this if you don't want to contribute to Propel. - -Usually, both the generator and the runtime components are installed on development environments, while the actual test or production servers may need only the runtime component installed. - -## Installing Dependencies ## - -The Propel generator uses [Phing 2.4.5](http://phing.info/) to manage command line tasks; both the generator and the runtime classes use [PEAR Log](http://pear.php.net/package/Log/) to log events. - -To install these packages, use the PEAR command as follows: - -```bash -pear channel-discover pear.phing.info -pear install phing/phing -pear install Log -``` - -Refer to their respective websites for alternative installation strategies for Phing and PEAR Log. - -## Testing Propel Installation ## - -The Propel generator component bundles a `propel-gen` sh script (and a `propel-gen.bat` script for Windows). This script makes it easy to execute build commands. You can test this component is properly installed by calling the `propel-gen` script from the CLI: - -```bash -cd myproject -vendor/propel/generator/bin/propel-gen -``` - -The script should output a welcome message, followed by a 'BUILD FAILED' message, which is normal - you haven't defined a model to build yet. - ->**Tip**
In order to allow an easier execution the script, you can also add the propel generator's `bin/` directory to your PATH, or create a symlink. For example: - -```bash -cd myproject -ln -s vendor/propel/generator/bin/propel-gen propel-gen # Make a symlink to the propel generator file -``` - -Or edit your ~/.bashrc or ~/.zshrc file with : - -```bash -export PATH=$PATH:/path/to/propel/bin -``` - -On Windows you could set the PATH for the opened command with : - -``` -set PATH=%PATH%;C:/path/to/propel/generator/bin/ -``` - -To globally define the PATH adjust it inside the "Environment Variables", which you can find in your system advanced settings panel. - -At this point, Propel should be setup and ready to use. You can follow the steps in the [Build Guide](02-buildtime.html) to try it out. - -## Alternative: Global Installation Using PEAR ## - -Alternatively, you can install Propel globally on your system using PEAR. All your projects will use the same Propel version - that may or may not be a good idea, depending on how often you update your projects. - -Propel has its own PEAR channel, that you must "discover". Using the `pear install -a` command, you can let PEAR download and install all dependencies (Phing and PEAR Log). - -So the commands to install Propel, Phing and PEAR Log globally sum up to this: - -```bash -pear channel-discover pear.propelorm.org -pear install -a propel/propel_generator -pear install -a propel/propel_runtime -``` - -Once Propel is installed globally, you can access the `propel-gen` command from everywhere without symlink. - ->**Tip**
If you want to install non-stable versions of Propel, change your `preferred_state` PEAR environment variable before installing the Propel packages. Valid states include 'stable', 'beta', 'alpha', and 'devel': - -```bash -pear config-set preferred_state beta -``` - -## Troubleshooting ## - -### PHP Configuration ### - -Propel requires the following settings in `php.ini`: - -|Variable |Value -|-----------------------|----- -|ze1_compatibility_mode |Off -|magic_quotes_gpc |Off -|magic_quotes_sybase |Off - -### PEAR Directory In Include Path ### - -If you choose to install Propel via PEAR, and if it's your first use of PEAR, the PEAR directory may not be on your PHP `include_path`. Check the [PEAR documentation](http://pear.php.net/manual/en/installation.checking.php) for details on how to do that. - -### Phing Version ### - -Phing versions 2.4.3 and 2.4.4 are incompatible with Propel. Check your Phing version by calling: - -```bash -phing -v -``` - -In case you're using a version less than 2.4.5, upgrade to the latest stable version: - -```bash -pear upgrade phing/phing -``` - -### Getting Help ### - -If you can't manage to install Propel, don't hesitate to ask for help. See [Support](../support) for details on getting help. diff --git a/documentation/02-buildtime.markdown b/documentation/02-buildtime.markdown deleted file mode 100644 index 35ecb319..00000000 --- a/documentation/02-buildtime.markdown +++ /dev/null @@ -1,355 +0,0 @@ ---- -layout: documentation -title: The Build Time ---- - -# The Build Time # - -The initial step in every Propel project is the "build". During build time, a developer describes the structure of the datamodel in a XML file called the "schema". From this schema, Propel generates PHP classes, called "model classes", made of object-oriented PHP code optimized for a given RDMBS. The model classes are the primary interface to find and manipulate data in the database in Propel. - -The XML schema can also be used to generate SQL code to setup your database. Alternatively, you can generate the schema from an existing database (see the [Existing-Database reverse engineering chapter](../cookbook/working-with-existing-databases) for more details), or from a DBDesigner 4 model (see the [DBDesigner2Propel chapter](../cookbook/dbdesigner)). - -During build time, a developer also defines the connection settings for communicating with the database. - -To illustrate Propel's build abilities, this chapter uses the data structure of a bookstore as an example. It is made of three tables: a `book` table, with a foreign key to two other tables, `author` and `publisher`. - -## Describing Your Database as XML Schema ## - -Propel generates PHP classes based on a _relational_ description of your data model. This "schema" uses XML to describe tables, columns and relationships. The schema syntax closely follows the actual structure of the database. - -Create a `bookstore` directory. This will be the root of the bookstore project. - -### Database Connection Name ### - -Create a file called `schema.xml` in the new `bookstore/` directory. - -The root tag of the XML schema is the `
You can define several schemas for a single project. Just make sure that each of the schema filenames end with `schema.xml`. - -### Tables And Columns ### - -Within the `
Propel supports namespaces (for PHP > 5.3). If you specify a `namespace` attribute in a `
Never add any code of your own to the classes generated by Propel in the `om/` and `map/` directories; this code would be lost next time you call the `propel-gen` script. - -Basically, all that means is that despite the fact that Propel generates _seven_ classes for each table, you should only care about two of them: the model class and the query class. - -## Building The Database ## - -To save you the burden of defining your model twice, Propel can initialize a database based on the schema, by creating the tables and foreign keys. - -### Building The SQL File ### - -Once again, use the `propel-gen` script to generate the SQL files necessary to create the tables, this time with the "sql" command: - -```bash -cd /path/to/bookstore -propel-gen sql -``` - -The generated SQL definition can be found in the `build/sql/schema.sql` file. The code is optimized for the database driver defined in the `build.properties`. - -### Using The SQL File ### - -Create the database and setup the access permissions using your favorite database client. For instance, to create the `my_db_name` database with MySQL, type: - -```bash -mysqladmin -u root -p create my_db_name -``` - -Now you can use the generated code directly: - -```bash -mysql -u root -p my_db_name < build/sql/schema.sql -``` - ->**Tip**
The `schema.sql` file will DROP any existing table before creating them, which will effectively erase your database. - -Depending on which RDBMS you are using, it may be normal to see some errors (e.g. "unable to DROP...") when you first run this command. This is because some databases have no way of checking to see whether a database object exists before attempting to DROP it (MySQL is a notable exception). It is safe to disregard these errors, and you can always run the script a second time to make sure that the errors are no longer present. - -### Inserting SQL With `propel-gen` ### - -As an alternative to using the generated sql code directly, you can ask Propel to insert it directly into your database. Start by defining the database connection settings in the `build.properties`, as follows: - -```ini -# Connection parameters -propel.database.url = mysql:host=localhost;dbname=my_db_name -propel.database.user = my_db_user -propel.database.password = my_db_password - -# Other examples: -# propel.database.url = sqlite:/path/to/bookstore.db -# propel.database.url = pgsql:host=localhost dbname=my_db_name user=my_db_user password=my_db_password -``` - -The `propel.database.url` setting should be a PDO DSN (see the [PDO documentation](http://www.php.net/pdo) for more information about vendor-specific DSN). The `user` and `password` are only necessary for the `mysql` and `oracle` drivers. - -Then use the `propel-gen` script with the "insert-sql" command to connect to the database and inject the generated SQL code: - -```bash -cd /path/to/bookstore -propel-gen insert-sql -``` - -## Runtime Connection Settings ## - -The database and PHP classes are now ready to be used. But they don't know yet how to communicate with each other at runtime. You must add a configuration file so that the generated object model classes and the shared Propel runtime classes can connect to the database, and log the Propel activity. - -### Writing The XML Runtime Configuration ### - -Create a file called `runtime-conf.xml` at the root of the `bookstore` project, using the following content: - -```xml - -
If you uncomment the `
As you saw, a Propel project setup requires that you call three commands with the `propel-gen` script: `om`, `sql`, and `convert-conf`. This is so usual that if you call the `propel-gen` script with no parameter, it will execute these three commands in a row: - -```bash -cd /path/to/bookstore -propel-gen -``` - -## Setting Up Propel ## - -This is the final step: initialize Propel in your PHP script. You may wish to do this step in an init or setup script that is included at the beginning of your PHP scripts. - -Here is a sample initialization file: - -```php -**Tip**
If you installed Propel using PEAR, you can replace the first line of this script with the more simple: - -```php -setFirstName('Jane'); -$author->setLastName('Austen'); -$author->save(); -``` - -The column names used in the `setXXX()` methods correspond to the `phpName` attribute of the `
For each export method, Propel also provides an import method counterpart. So you can easily populate an object from an array using `fromArray()`, and from a string using any of `fromXML()`, `fromYAML()`, `fromJSON()`, and `fromCSV()`. - -There are a lot more useful methods offered by the generated objects. You can find an extensive list of these methods in the [Active Record reference](../reference/active-record). - -## Retrieving Rows ## - -Retrieving objects from the database, also referred to as _hydrating_ objects, is essentially the process of executing a SELECT query against the database and populating a new instance of the appropriate object with the contents of each returned row. - -In Propel, you use the generated Query objects to retrieve existing rows from the database. - -### Retrieving by Primary Key ### - -The simplest way to retrieve a row from the database, is to use the generated `findPK()` method. It simply expects the value of the primary key of the row to be retrieved. - -```php -findPK(1); -// now $firstAuthor is an Author object, or NULL if no match was found. -``` - -This issues a simple SELECT SQL query. For instance, for MySQL: - -```sql -SELECT author.id, author.first_name, author.last_name -FROM `author` -WHERE author.id = 1 -LIMIT 1; -``` - -When the primary key consists of more than one column, `findPK()` accepts multiple parameters, one for each primary key column. - ->**Tip**
Every generated Query objects offers a factory method called `create()`. This methods creates a new instance of the query, and allows you to write queries in a single line: - -```php -findPK(1); -``` - -You can also select multiple objects based on their primary keys, by calling the generated `findPKs()` method. It takes an array of primary keys as a parameter: - -```php -findPKs(array(1,2,3,4,5,6,7)); -// $selectedAuthors is a collection of Author objects -``` - -### Querying the Database ### - -To retrieve rows other than by the primary key, use the Query `find()` method. - -An empty Query object carries no condition, and returns all the rows of the table -```php -find(); -// $authors contains a collection of Author objects -// one object for every row of the author table -foreach($authors as $author) { - echo $author->getFirstName(); -} -``` - -To add a simple condition on a given column, use one of the generated `filterByXXX()` methods of the Query object, where `XXX` is a column phpName. Since `filterByXXX()` methods return the current query object, you can continue to add conditions or end the query with the result of the method call. For instance, to filter by first name: - -```php -filterByFirstName('Jane') - ->find(); -``` - -When you pass a value to a `filterByXXX()` method, Propel uses the column type to escape this value in PDO. This protects you from SQL injection risks. - ->**Tip**
`filterByXXX()` is the preferred method for creating queries. It is very flexible and accepts values with wildcards as well as arrays for more complex use cases. See [Column Filter Methods](../reference/model-criteria.html#column_filter_methods) for details. - -You can also easily limit and order the results on a query. Once again, the Query methods return the current Query object, so you can easily chain them: - -```php -orderByLastName() - ->limit(10) - ->find(); -``` - -`find()` always returns a collection of objects, even if there is only one result. If you know that you need a single result, use `findOne()` instead of `find()`. It will add the limit and return a single object instead of an array: - -```php -filterByFirstName('Jane') - ->findOne(); -``` - ->**Tip**
Propel provides magic methods for this simple use case. So you can write the above query as: - -```php -findOneByFirstName('Jane'); -``` - -The Propel Query API is very powerful. The next chapter will teach you to use it to add conditions on related objects. If you can't wait, jump to the [Query API reference](../reference/model-criteria). - ->**Tip**
The `findPk` method and `findOneByXXX` magic methods (for primary key attributes) do not always query the database, but sometimes give you information from a cache. See the section about the [instance pool](#propel-instance-pool) for more information. - -### Using Custom SQL ### - -The `Query` class provides a relatively simple approach to constructing a query. Its database neutrality and logical simplicity make it a good choice for expressing many common queries. However, for a very complex query, it may prove more effective (and less painful) to simply use a custom SQL query to hydrate your Propel objects. - -As Propel uses PDO to query the underlying database, you can always write custom queries using the PDO syntax. For instance, if you have to use a sub-select: - -```php -prepare($sql); -$stmt->execute(array(':name' => 'Austen')); -``` - -With only a little bit more work, you can also populate `Book` objects from the resulting statement. Create a new `PropelObjectCollection` for the `Book` model, and call the `format()` method using the statement: - -```php -setClass('Book'); -$books = $formatter->format($stmt); -// $books contains a collection of Book objects -``` - ->**Tip**
->There are a few important things to remember when using custom SQL to populate Propel: -> -> * The resultset columns must be numerically indexed -> * The resultset must contain all the columns of the table (except lazy-load columns) -> * The resultset must have columns _in the same order_ as they are defined in the `schema.xml` file - -## Updating Objects ## - -Updating database rows basically involves retrieving objects, modifying the contents, and then saving them. In practice, for Propel, this is a combination of what you've already seen in the previous sections: - -```php -findOneByFirstName('Jane'); -$author->setLastName('Austen'); -$author->save(); -``` - -Alternatively, you can update several rows based on a Query using the query object's `update()` method: - -```php -filterByFirstName('Jane') - ->update(array('LastName' => 'Austen')); -``` - -This last method is better for updating several rows at once, or if you didn't retrieve the objects before. - -## Deleting Objects ## - -Deleting objects works the same as updating them. You can either delete an existing object: - -```php -findOneByFirstName('Jane'); -$author->delete(); -``` - -Or use the `delete()` method in the query: - -```php -filterByFirstName('Jane') - ->delete(); -``` - ->**Tip**
A deleted object still lives in the PHP code. It is marked as deleted and cannot be saved anymore, but you can still read its properties: - -```php -isDeleted(); // true -echo $author->getFirstName(); // 'Jane' -``` - -## Query Termination Methods ## - -The Query methods that don't return the current query object are called "Termination Methods". You've already seen some of them: `find()`, `findOne()`, `update()`, `delete()`. There are two more termination methods that you should know about: - -```php -count(); -// You could also count the number of results from a find(), but that would be less effective, -// since it implies hydrating objects just to count them - -// paginate() returns a paginated list of results -$authorPager = AuthorQuery::create()->paginate($page = 1, $maxPerPage = 10); -// This method will compute an offset and a limit -// based on the number of the page and the max number of results per page. -// The result is a PropelModelPager object, over which you can iterate: -foreach ($authorPager as $author) { - echo $author->getFirstName(); -} -// A pager object gives more information -echo $authorPager->getNbResults(); // total number of results if not paginated -echo $authorPager->haveToPaginate(); // return true if the total number of results exceeds the maximum per page -echo $authorPager->getFirstIndex(); // index of the first result in the page -echo $authorPager->getLastIndex(); // index of the last result in the page -$links = $authorPager->getLinks(5); // array of page numbers around the current page; useful to display pagination controls -``` - -## Collections And On-Demand Hydration ## - -The `find()` method of generated Model Query objects returns a `PropelCollection` object. You can use this object just like an array of model objects, iterate over it using `foreach`, access the objects by key, etc. - -```php -limit(5) - ->find(); -foreach ($authors as $author) { - echo $author->getFirstName(); -} -``` - -The advantage of using a collection instead of an array is that Propel can hydrate model objects on demand. Using this feature, you'll never fall short of memory when retrieving a large number of results. Available through the `setFormatter()` method of Model Queries, on-demand hydration is very easy to trigger: - -```php -limit(50000) - ->setFormatter(ModelCriteria::FORMAT_ON_DEMAND) // just add this line - ->find(); -foreach ($authors as $author) { - echo $author->getFirstName(); -} -``` - -In this example, Propel will hydrate the `Author` objects row by row, after the `foreach` call, and reuse the memory between each iteration. The consequence is that the above code won't use more memory when the query returns 50,000 results than when it returns 5. - -`ModelCriteria::FORMAT_ON_DEMAND` is one of the many formatters provided by the Query objects. You can also get a collection of associative arrays instead of objects, if you don't need any of the logic stored in your model object, by using `ModelCriteria::FORMAT_ARRAY`. - -The [ModelCriteria Query API reference](../reference/model-criteria) describes each formatter, and how to use it. - -## Propel Instance Pool ## - -Propel keeps a list of the objects that you already retrieved in memory to avoid calling the same request twice in a PHP script. This list is called the instance pool, and is automatically populated from your past requests. -The instance pool is consulted whenever searching for an object using its primary key via `findPk` or `findOneById` (which is an alias for the former). - -```php -findPk(1); -// Issues a SELECT query -... -// second call -$author2 = AuthorQuery::create()->findPk(1); // or AuthorQuery::create()->findOneById(1); -// Skips the SQL query and returns the existing $author1 object -``` - -The instance pool is located in and managed via an entity's peer class (e.g. `AuthorPeer::getInstanceFromPool((string) $key)`) but there should seldom or never be the need to call it manually. - -That said, remember that in some cases, executing an actual query to the database might be necessary, e.g. if the state of the object differs from the database state. -This is frequently the case if for instance the attributes are set externally by e.g. binding it to a form. -If the values as of the database state of an entity are needed within an entity, for instance in its `save()` function, using `findPk($this->id)` and `findOneById($this->getId())` won't work, since the instance pool will answer this request, giving you the data you already have. -To retrieve the object either use one of the other `find` methods or disable instance pooling for the moment: - -```php -findOneById($this->getId()); - if( null !== $uq ){ - $oldPassword = $uq->getPassword(); - $this->setPassword($oldPassword); - } - - \Propel::enableInstancePooling(); -``` diff --git a/documentation/04-relationships.markdown b/documentation/04-relationships.markdown deleted file mode 100644 index 7dc571fc..00000000 --- a/documentation/04-relationships.markdown +++ /dev/null @@ -1,401 +0,0 @@ ---- -layout: documentation -title: Basic Relationships ---- - -# Basic Relationships # - -The definition of foreign keys in your schema allows Propel to add smart methods to the generated model and query objects. In practice, these generated methods mean that you will never actually have to deal with primary and foreign keys yourself. It makes the task of dealing with relations extremely straightforward. - -## Inserting A Related Row ## - -Propel creates setters for related objects that simplify the foreign key handling. You don't actually have to define a foreign key value. Instead, just set a related object, as follows: - -```php -setFirstName("Leo"); -$author->setLastName("Tolstoy"); -$author->save(); - -$book = new Book(); -$book->setTitle("War & Peace"); -// associate the $author object with the current $book -$book->setAuthor($author); -$book->save(); -``` - -Propel generates the `setAuthor()` method based on the `phpName` attribute of the `
Propel also generates a `countBooks()` methods to get the number of related objects without hydrating all the `Book` objects. for performance reasons, you should prefer this method to `count($author->getBooks())`. - -Getters for one-to-many relationship accept an optional query object. This allows you to hydrate related objects, or retrieve only a subset of the related objects, or to reorder the list of results: - -```php -orderByTitle() - ->joinWith('Book.Publisher'); -$books = $author->getBooks($query); -``` - -## Using Relationships In A Query ## - -### Finding Records Related To Another One ### - -If you need to find objects related to a model object that you already have, you can take advantage of the generated `filterByXXX()` methods in the query objects, where `XXX` is a relation name: - -```php -findPk(1); -$books = BookQuery::create() - ->filterByAuthor($author) - ->orderByTitle() - ->find(); -``` - -You don't need to specify that the `author_id` column of the `Book` object should match the `id` column of the `Author` object. Since you already defined the foreign key mapping in your schema, Propel knows enough to figure it out. - -### Embedding Queries ### - -In SQL queries, relationships often translate to a JOIN statement. Propel abstracts this relational logic in the query objects, by allowing you to _embed_ a related query into another. - -In practice, Propel generates one `useXXXQuery()` method for every relation in the Query objects. So the `BookQuery` class offers a `useAuthorQuery()` and a `usePublisherQuery()` method. These methods return a new Query instance of the related query class, that you can eventually merge into the main query by calling `endUse()`. - -To illustrate this, let's see how to write the following SQL query with the Propel Query API: - -```sql -SELECT book.* -FROM book INNER JOIN author ON book.AUTHOR_ID = author.ID -WHERE book.ISBN = '0140444173' AND author.FIRST_NAME = 'Leo' -ORDER BY book.TITLE ASC -LIMIT 10; -``` - -That would simply give: - -```php -filterByISBN('0140444173') - ->useAuthorQuery() // returns a new AuthorQuery instance - ->filterByFirstName('Leo') // this is an AuthorQuery method - ->endUse() // merges the Authorquery in the main Bookquery and returns the BookQuery - ->orderByTitle() - ->limit(10) - ->find(); -``` - -Propel knows the columns to use in the `ON` clause from the definition of foreign keys in the schema. The ability to use methods of a related Query object allows you to keep your model logic where it belongs. - -Of course, you can embed several queries to issue a query of any complexity level: - -```php -useBookQuery() - ->usePublisherQuery() - ->filterByName('Viking Press') - ->endUse() - ->endUse() - ->find(); -``` - -You can see how the indentation of the method calls provide a clear explanation of the embedding logic. That's why it is a good practice to format your Propel queries with a single method call per line, and to add indentation every time a `useXXXQuery()` method is used. - -## Many-to-Many Relationships ## - -Databases typically use a cross-reference table, or junction table, to materialize the relationship. For instance, if the `user` and `group` tables are related by a many-to-many relationship, this happens through the rows of a `user_group` table. To inform Propel about the many-to-many relationship, set the `isCrossRef` attribute of the cross reference table to true: - ->**Warning**
Use only `isCrossRef` with a middle table that is design the same way as the example (user_group), two foreign keys that are also primary keys. If you use a different schema for the middle table, use it at your own risk - -```xml -
`with()` also works for left joins on one-to-many relationships, but you mustn't use a `limit()` in the query in this case. This is because Propel has no way to determine the actual number of rows of the main object in such a case. - -```php -leftJoinWith('Author.Book') - ->find(); -// this does not work -$authors = AuthorQuery::create() - ->leftJoinWith('Author.Book') - ->limit(5) - ->find(); -``` - -However, it is quite easy to achieve hydration of related objects with only one additional query: - -```php -limit(5) - ->find(); -// $authors is a PropelObjectCollection -$authors->populateRelation('Book'); -foreach ($authors as $author) { - // now you can iterate over each author's book without further queries - foreach ($author->getBooks() as $book) { // no database query, the author already has a Books collection - // do stuff with $book and $author - } -} -``` - -## Model-Only Relationships ## - -Propel models can share relationships even though the underlying tables aren't linked by a foreign key. This ability may be of great use when using Propel on top of a legacy database. - -For example, a `review` table designed for a MyISAM database engine is linked to a `book` table by a simple `book_id` column: - -```xml -
Propel expects your pattern defined within `value` either without delimiters or in case you need a delimiter to be surrounded by `/`. Other pattern delimiters are not supported. - -### NotMatchValidator ### - -Opposite of `MatchValidator`, this validator returns false if the regex returns true - -```xml -
Propel expects your pattern defined within `value` either without delimiters or in case you need a delimiter to be surrounded by `/`. Other pattern delimiters are not supported. - -### MaxLengthValidator ### - -When you want to limit the size of the string to be inserted in a column, use the `MaxLengthValidator`. Internally, it uses `strlen()` to get the length of the string. For instance, some database completely ignore the length of `LONGVARCHAR` columns; you can enforce it using a validator: - -```xml -
If you have specified the `size` attribute in the `
The `MaxLengthValidator` uses `mb_strlen` internally when available. Therefore make sure you defined the correct `mb_internal_encoding` when handling e.g. UTF-8 Strings. - -### MinLengthValidator ### - -```xml -
You can run multiple validators against a single column. - -```xml -
Make sure that `isValid()` returns a boolean, so really true or false. Propel is very strict about this. Returning a mixed value just won't do. - -To enable the new validator on a column, add a corresponding `
If the [ACID](http://en.wikipedia.org/wiki/ACID) acronym doesn't ring a bell, you should probably learn some [fundamentals about database transactions](http://en.wikipedia.org/wiki/Database_transaction) before reading further. - -## Wrapping Queries Inside a Transaction ## - -Propel uses PDO as database abstraction layer, and therefore uses [PDO's built-in support for database transactions](http://www.php.net/manual/en/pdo.transactions.php). The syntax is the same, as you can see in the classical "money transfer" example: - -```php -beginTransaction(); - - try { - // remove the amount from $fromAccount - $fromAccount->setValue($fromAccount->getValue() - $amount); - $fromAccount->save($con); - // add the amount to $toAccount - $toAccount->setValue($toAccount->getValue() + $amount); - $toAccount->save($con); - - $con->commit(); - } catch (Exception $e) { - $con->rollback(); - throw $e; - } -} -``` - -The transaction statements are `beginTransaction()`, `commit()` and `rollback()`, which are methods of the PDO connection object. Transaction methods are typically used inside a `try/catch` block. The exception is rethrown after rolling back the transaction: That ensures that the user knows that something wrong happened. - -In this example, if something wrong happens while saving either one of the two accounts, an `Exception` is thrown, and the whole operation is rolled back. That means that the transfer is cancelled, with an insurance that the money hasn't vanished (that's the A in ACID, which stands for "Atomicity"). If both account modifications work as expected, the whole transaction is committed, meaning that the data changes enclosed in the transaction are persisted in the database. - -Tip: In order to build a transaction, you need a connection object. The connection object for a Propel model is always available through `Propel::getConnection([ModelName]Peer::DATABASE_NAME)`. - -## Denormalization And Transactions ## - -Another example of the use of transactions is for [denormalized schemas](http://en.wikipedia.org/wiki/Denormalization). - -For instance, suppose that you have an `Author` model with a one to many relationship to a `Book` model. every time you need to display the number of books written by an author, you call `countBooks()` on the author object, which issues a new query to the database: - -```php -
-
-
-
- getName() ?> (countBooks() ?> books) - -
Check the [behaviors documentation]() for details about the pre- and post- hooks in Propel model objects. - -## Nested Transactions ## - -Some RDBMS offer the ability to nest transactions, to allow partial rollback of a set of transactions. PDO does not provide this ability at the PHP level; nevertheless, Propel emulates nested transactions for all supported database engines: - -```php -beginTransaction(); - try { - $c = new Criteria(); - $c->add(BookPeer::PRICE, null, Criteria::ISNULL); - BookPeer::doDelete($c, $con); - $con->commit(); - } catch (Exception $e) { - $con->rollback(); - throw $e; - } -} - -function deleteAuthorsWithNoEmail(PropelPDO $con) -{ - $con->beginTransaction(); - try { - $c = new Criteria(); - $c->add(AuthorPeer::EMAIL, null, Criteria::ISNULL); - AuthorPeer::doDelete($c, $con); - $con->commit(); - } catch (Exception $e) { - $con->rollback(); - throw $e; - } -} - -function cleanup(PropelPDO $con) -{ - $con->beginTransaction(); - try { - deleteBooksWithNoPrice($con); - deleteAuthorsWithNoEmail($con); - $con->commit(); - } catch (Exception $e) { - $con->rollback(); - throw $e; - } -} -``` - -All three functions alter data in a transaction, ensuring data integrity for each. In addition, the `cleanup()` function actually executes two nested transactions inside one main transaction. - -Propel deals with this case by seeing only the outermost transaction, and ignoring the `beginTransaction()`, `commit()` and `rollback()` statements of nested transactions. If nothing wrong happens, then the last `commit()` call (after both `deleteBooksWithNoPrice()` and `deleteAuthorsWithNoEmail()` end) triggers the actual database commit. However, if an exception is thrown in either one of these nested transactions, it is escalated to the main `catch` statement in `cleanup()` so that the entire transaction (starting at the main `beginTransaction()`) is rolled back. - -So you can use transactions everywhere it's necessary in your code, without worrying about nesting them. Propel will always commit or rollback everything altogether, whether the RDBMS supports nested transactions or not. - ->**Tip**
This allows you to wrap all your application code inside one big transaction for a better integrity. - -## Using Transactions To Boost Performance ## - -A database transaction has a cost in terms of performance. In fact, for simple data manipulation, the cost of the transaction is more important than the cost of the query itself. Take the following example: - -```php -setTitle($i . ': A Space Odyssey'); - $book->save($con); -} -``` - -As explained earlier, Propel wraps every save operation inside a transaction. In terms of execution time, this is very expensive. Here is how the above code would translate to MySQL in an InnodDB table: - -```sql -BEGIN; -INSERT INTO book (`ID`,`TITLE`) VALUES (NULL,'0: A Space Odyssey'); -COMMIT; -BEGIN; -INSERT INTO book (`ID`,`TITLE`) VALUES (NULL,'1: A Space Odyssey'); -COMMIT; -BEGIN; -INSERT INTO book (`ID`,`TITLE`) VALUES (NULL,'2: A Space Odyssey'); -COMMIT; -... -``` - -You can take advantage of Propel's nested transaction capabilities to encapsulate the whole loop inside one single transaction. This will reduce the execution time drastically: - -```php -beginTransaction(); -for ($i=0; $i<2002; $i++) -{ - $book = new Book(); - $book->setTitle($i . ': A Space Odyssey'); - $book->save($con); -} -$con->commit(); -``` - -The transactions inside each `save()` will become nested, and therefore not translated into actual database transactions. Only the outmost transaction will become a database transaction. So this will translate to MySQL as: - -```sql -BEGIN; -INSERT INTO book (`ID`,`TITLE`) VALUES (NULL,'0: A Space Odyssey'); -INSERT INTO book (`ID`,`TITLE`) VALUES (NULL,'1: A Space Odyssey'); -INSERT INTO book (`ID`,`TITLE`) VALUES (NULL,'2: A Space Odyssey'); -... -COMMIT; -``` - -In practice, encapsulating a large amount of simple queries inside a single transaction significantly improves performance. - -Tip: Until the final `commit()` is called, most database engines lock updated rows, or even tables, to prevent any query outside the transaction from seeing the partially committed data (this is how transactions preserve Isolation, which is the I in ACID). That means that large transactions will queue every other queries for potentially a long time. Consequently, use large transactions only when concurrency is not a requirement. - -## Why Is The Connection Always Passed As Parameter? ## - -All the code examples in this chapter show the connection object passed a a parameter to Propel methods that trigger a database query: - -```php -setValue($fromAccount->getValue() - $amount); -$fromAccount->save($con); -``` - -The same code works without explicitly passing the connection object, because Propel knows how to get the right connection from a Model: - -```php -setValue($fromAccount->getValue() - $amount); -$fromAccount->save(); -``` - -However, it's a good practice to pass the connection explicitly, and for three reasons: - -* Propel doesn't need to look for a connection object, and this results in a tiny boost in performance. -* You can use a specific connection, which is required in distributed (master/slave) environments, in order to distinguish read and write operations. -* Most importantly, transactions are tied to a single connection. You can't enclose two queries using different connections in a single transaction. So it's very useful to identify the connection you want to use for every query, as Propel will throw an exception if you use the wrong connection. - -## Limitations ## - -* Currently there is no support for row locking (e.g. `SELECT blah FOR UPDATE`). -* You must rethrow the exception caught in the `catch` statement of nested transactions, otherwise there is a risk that the global rollback doesn't occur. -* True nested transactions, with partial rollback, are only possible in MSSQL, and can be emulated in other RDBMS through savepoints. This feature may be added to Propel in the future, but for the moment, only the outermost PHP transaction triggers a database transaction. -* If you rollback a partially executed transaction and ignore the exception thrown, there are good chances that some of your objects are out of sync with the database. The good practice is to always let a transaction exception escalate until it stops the script execution. diff --git a/documentation/07-behaviors.markdown b/documentation/07-behaviors.markdown deleted file mode 100644 index 54a95f94..00000000 --- a/documentation/07-behaviors.markdown +++ /dev/null @@ -1,433 +0,0 @@ ---- -layout: documentation -title: Behaviors ---- - - -# Behaviors # - -Behaviors are a great way to package model extensions for reusability. They are the powerful, versatile, fast, and help you organize your code in a better way. - -## Pre and Post Hooks For `save()` And `delete()` Methods ## - -The `save()` and `delete()` methods of your generated objects are easy to override. In fact, Propel looks for one of the following methods in your objects and executes them when needed: - -```php - - ... -
Since this feature adds a small overhead to write operations, you can deactivate it completely in your build properties by setting `propel.addHooks` to `false`. - -```ini -# ------------------- -# TEMPLATE VARIABLES -# ------------------- -propel.addHooks = false -``` - -## Introducing Behaviors ## - -When several of your custom model classes end up with similar methods added, it is time to refactor the common code. - -For example, you may want to add the same ability you gave to `Book` to all the other objects in your model. Let's call this the "Timestampable behavior", because then all of your rows have a timestamp marking their creation. In order to achieve this behavior, you have to repeat the same operations on every table. First, add a `created_at` column to the other tables: - -```xml -
If you use autoloading during the build process, and if the behavior classes benefit from the autoloading, then you don't even need to declare the path to the behavior class. - -## Applying a Behavior To All Tables ## - -You can add a `
Install PEAR Log using `pear install Log` - - -### Logger Configuration ### - -The Propel log handler is configured in the `
Remember to run `propel-gen convert-conf` after modifying the configuration files. - -Using these parameters, Propel creates a `file` Log handler in the background, and keeps it for later use: - -```php -` nested elements may vary, depending on which log handler you are using. Most common accepted logger types are `file`, `console`, `syslog`, `display`, `error_log`, `firebug`, and `sqlite`. Refer to the [PEAR::Log](http://www.indelible.org/php/Log/guide.html#standard-log-handlers) documentation for more details on log handlers configuration and options. - -Note that the `
All serious errors coming from the Propel core do not only issue a log message, they are also thrown as `PropelException`. - -### Using An Alternative PEAR Log Handler ### - -In many cases you may wish to integrate Propel's logging facility with the rest of your web application. In `runtime-conf.xml`, you can customize a different PEAR logger. Here are a few examples: - -_Example 1:_ Using `display` handler (for output to HTML) - -```xml -
' . $message . '
'; - } - - private function priorityToColor($priority) - { - switch($priority) { - case Propel::LOG_EMERG: - case Propel::LOG_ALERT: - case Propel::LOG_CRIT: - case Propel::LOG_ERR: - return 'red'; - break; - case Propel::LOG_WARNING: - return 'orange'; - break; - case Propel::LOG_NOTICE: - return 'green'; - break; - case Propel::LOG_INFO: - return 'blue'; - break; - case Propel::LOG_DEBUG: - return 'grey'; - break; - } - } -} -``` - ->**Tip**There is also a bundled `MojaviLogAdapter` class which allows you to use a Mojavi logger with Propel. - -## Debugging Database Activity ## - -By default, Propel uses `PropelPDO` for database connections. This class, which extends PHP's `PDO`, offers a debug mode to keep track of all the database activity, including all the executed queries. - -### Enabling The Debug Mode ### - -The debug mode is disabled by default, but you can enable it at runtime as follows: - -```php -useDebug(true); -``` - -You can also disable the debug mode at runtime, by calling `PropelPDO::useDebug(false)`. Using this method, you can choose to enable the debug mode for only one particular query, or for all queries. - -Alternatively, you can ask Propel to always enable the debug mode for a particular connection by using the `DebugPDO` class instead of the default `PropelPDO` class. This is accomplished in the `runtime-conf.xml` file, in the `
You can use your own connection class there, but make sure that it extends `PropelPDO` and not only `PDO`. Propel requires certain fixes to PDO API that are provided by `PropelPDO`. - -### Counting Queries ### - -In debug mode, `PropelPDO` keeps track of the number of queries that are executed. Use `PropelPDO::getQueryCount()` to retrieve this number: - -```php -getQueryCount(); // 1 -``` - -Tip: You cannot use persistent connections if you want the query count to work. Actually, the debug mode in general requires that you don't use persistent connections in order for it to correctly log bound values and count executed statements. - -### Retrieving The Latest Executed Query ### - -For debugging purposes, you may need the SQL code of the latest executed query. It is available at runtime in debug mode using `PropelPDO::getLastExecutedQuery()`, as follows: - -```php -getLastExecutedQuery(); // 'SELECT * FROM my_obj'; -``` - -Tip: You can also get a decent SQL representation of the criteria being used in a SELECT query by using the `Criteria->toString()` method. - -Propel also keeps track of the queries executed directly on the connection object, and displays the bound values correctly. - -```php -prepare('SELECT * FROM my_obj WHERE name = :p1'); -$stmt->bindValue(':p1', 'foo'); -$stmt->execute(); -echo $con->getLastExecutedQuery(); // 'SELECT * FROM my_obj where name = "foo"'; -``` - ->**Tip**
The debug mode is intended for development use only. Do not use it in production environment, it logs too much information for a production server, and adds a small overhead to the database queries. - -## Full Query Logging ## - -The combination of the debug mode and a logging facility provides a powerful debugging tool named _full query logging_. If you have properly configured a log handler, enabling the debug mode (or using `DebugPDO`) automatically logs the executed queries into Propel's default log file: - -```text -Oct 04 00:00:18 propel-bookstore [debug] INSERT INTO publisher (`ID`,`NAME`) VALUES (NULL,'William Morrow') -Oct 04 00:00:18 propel-bookstore [debug] INSERT INTO author (`ID`,`FIRST_NAME`,`LAST_NAME`) VALUES (NULL,'J.K.','Rowling') -Oct 04 00:00:18 propel-bookstore [debug] INSERT INTO book (`ID`,`TITLE`,`ISBN`,`PRICE`,`PUBLISHER_ID`,`AUTHOR_ID`) VALUES (NULL,'Harry Potter and the Order of the Phoenix','043935806X',10.99,53,58) -Oct 04 00:00:18 propel-bookstore [debug] INSERT INTO review (`ID`,`REVIEWED_BY`,`REVIEW_DATE`,`RECOMMENDED`,`BOOK_ID`) VALUES (NULL,'Washington Post','2009-10-04',1,52) -... -Oct 04 00:00:18 propel-bookstore [debug] SELECT bookstore_employee_account.EMPLOYEE_ID, bookstore_employee_account.LOGIN FROM `bookstore_employee_account` WHERE bookstore_employee_account.EMPLOYEE_ID=25 -``` - -By default, Propel logs all SQL queries, together with the date of the query and the name of the connection. - -### Setting The Data To Log ### - -The full query logging feature can be configured either in the `runtime-conf.xml` configuration file, or using the runtime configuration API. - -In `runtime-conf.xml`, tweak the feature by adding a `
-
- true
-
-
-
- true
-
-
- An inherited class can extend another inherited class. That mean that you can add a `Manga` kind of book that extends `Comic` instead of `Book`. - -
- ->**Tip**
If you define an `
You can override the base peer's `getOMClass()` to return the classname to use based on more complex logic (or query). - -### Abstract Entities ### - -If you wish to enforce using subclasses of an entity, you may declare a table "abstract" in your XML data model: - -```xml -
Delegation only works for a single level. If you have a deep inheritance hierarchy, you will need to delegate to each ancestors in the hierarchy by simulating multiple inheritance (see below). - -### Delegation in Practice ### - -Using the previous schema, here is how you create a `Basketballer` and set his stats and identity: - -```php -setPoints(101); -$basketballer->setFieldGoals(47); -$basketballer->setThreePointsFieldGoals(7); -// set player identity via delegation -$basketballer->setFirstName('Michael'); -$basketballer->setLastName('Giordano'); -// same as -$player = new Player(); -$player->setFirstName('Michael'); -$player->setLastName('Giordano'); -$basketballer->setPlayer($player); - -// save basketballer and player -$basketballer->save(); - -// retrieve delegated data directly from the main object -echo $basketballer->getFirstName(); // Michael -``` - -The `Basketballer` object delegates `Player` methods to its related `Player` object. If no `Player` object exists, the `delegate` behavior creates one and relates it to the current `basketballer`, so that both objects can be persisted together. - -The same happens for `Footballer` class, which also delegates to `Player`. And since a `Basketballer` and a `Footballer` instance can delegate to the same `Player` instance, a player can play both soccer and basketball. - ->**Tip**
Again, delegation isn't really inheritance. The `Basketballer` class doesn't inherit from `Player`, but _proxies_ method calls to `Player`. And since Propel uses `__call()` magic to achieve this proxying, an IDE won't see the `Player` methods accessible to a `Basketballer` instance. - -### Multiple Inheritance ### - -The `delegate` behavior allows to delegate to more than one class, effectively simulating multiple inheritance. Here is an example: - -```xml -
The `concrete_inheritance` behavior copies columns, foreign keys, indices and validators. - -### Using Inherited Model Classes ### - -For each of the tables in the schema above, Propel generates a Model class: - -```php -setName('Movie'); -$cat->save(); -// create a new Article -$art = new Article(); -$art->setTitle('Avatar Makes Best Opening Weekend in the History'); -$art->setCategory($cat); -$art->setContent('With $232.2 million worldwide total, Avatar had one of the best-opening weekends in the history of cinema.'); -$art->save(); -// create a new Video -$vid = new Video(); -$vid->setTitle('Avatar Trailer'); -$vid->setCategory($cat); -$vid->setResourceLink('http://www.avatarmovie.com/index.html') -$vid->save(); -``` - -And since the `concrete_inheritance` behavior tag defines a parent table, the `Article` and `Video` classes extend the `Content` class (same for the generated Query classes): - -```php -getCategory()->getName(); - } -} -echo $art->getCategoryName(); // 'Movie' -echo $vid->getCategoryName(); // 'Movie' - -// methods of the parent query are accessible to the child query -class ContentQuery extends BaseContentQuery -{ - public function filterByCategoryName($name) - { - return $this - ->useCategoryQuery() - ->filterByName($name) - ->endUse(); - } -} -$articles = ArticleQuery::create() - ->filterByCategoryName('Movie') - ->find(); -``` - -That makes of Concrete Table Inheritance a powerful way to organize your model logic and to avoid repetition, both in the schema and in the model code. - -### Data Replication ### - -By default, every time you save an `Article` or a `Video` object, Propel saves a copy of the `title` and `category_id` columns in a `Content` object. Consequently, retrieving objects regardless of their child type becomes very easy: - -```php -find(); -foreach ($conts as $content) { - echo $content->getTitle() . "(". $content->getCategoryName() ")/n"; -} -// Avatar Makes Best Opening Weekend in the History (Movie) -// Avatar Trailer (Movie) -``` - -Propel also creates a one-to-one relationship between a object and its parent copy. That's why the schema definition above doesn't define any primary key for the `article` and `video` tables: the `concrete_inheritance` behavior creates the `id` primary key which is also a foreign key to the parent `id` column. So once you have a parent object, getting the child object is just one method call away: - -```php -getContent(); - } -} -class Movie extends BaseMovie -{ - public function getPreview() - { - return $this->getResourceLink(); - } -} -$conts = ContentQuery::create()->find(); -foreach ($conts as $content) { - echo $content->getTitle() . "(". $content->getCategoryName() ")/n" - if ($content->hasChildObject()) { - echo ' ' . $content->getChildObject()->getPreview(), "\n"; -} -// Avatar Makes Best Opening Weekend in the History (Movie) -// With $232.2 million worldwide total, Avatar had one of the best-opening -// weekends in the history of cinema. -// Avatar Trailer (Movie) -// http://www.avatarmovie.com/index.html -``` - -The `hasChildObject()` and `getChildObject()` methods are automatically added by the behavior to the parent class. Behind the curtain, the saved `content` row has an additional `descendant_column` field allowing it to use the right model for the job. - ->**Tip**
You can disable the data replication by setting the `copy_data_to_parent` parameter to "false". In that case, the `concrete_inheritance` behavior simply modifies the table at buildtime and does nothing at runtime. Also, with `copy_data_to_parent` disabled, any primary key copied from the parent table is not turned into a foreign key: - -```xml -
Propel only supports migrations in MySQL and PostgreSQL for now. - -## Migration Workflow ## - -The workflow of Propel migrations is very simple: - -1. Edit the XML schema to modify the model -2. Call the `diff` task to create a migration class containing the SQL statements altering the database structure -3. Review the migration class Propel just generated, and add data migration code if necessary -4. Execute the migration using the `migrate` task. -5. Call the `om` task to generate the updated object model classes. - -Here is a concrete example. On a new bookstore project, a developer creates an XML schema with a single `book` table: - -```xml -
On a project using version control, it is important to commit the migration classes to the code repository. That way, other developers checking out the project will just have to run the same migrations to get a database in a similar state. - -Now, to actually create the `book` table in the database, the developer has to call the `migrate` task: - -```text -> propel-gen migrate - -[propel-migration] Executing migration PropelMigration_1286483354 up -[propel-migration] 1 of 1 SQL statements executed successfully on datasource "bookstore" -[propel-migration] Migration complete. No further migration to execute. -``` - -The `book` table is now created in the database. It can be populated with data. - -Finally, in order to use the newly added table in application development, the developer has to call the `om` task to generate the updated object model classes: - -```text -> propel-gen om -``` - -After a few days, the developer wants to add a new `author` table, with a foreign key in the `book` table. The schema is modified as follows: - -```xml -
`diff` and `migrate` often come one after the other, so you may want to execute them both in one call. That's possible, provided that the first argument of the `propel-gen` script is the path to the current project: - -```text -> propel-gen . diff migrate -``` - -## Migration Tasks ## - -The two basic migration tasks are `diff` and `migrate` - you already know them. `diff` creates a migration class, and `migrate` executes the migrations. But there are three more migration tasks that you will find very useful. - -### Migration Up or Down, One At A Time ### - -In the previous example, two migrations were executed. But the developer now wants to revert the last one. The `down` task provides exactly this feature: it reverts only one migration. - -```text -> propel-gen down - -[propel-migration-down] Executing migration PropelMigration_1286484196 down -[propel-migration-down] 4 of 4 SQL statements executed successfully on datasource "bookstore" -[propel-migration-down] Reverse migration complete. 1 more migrations available for reverse. -``` - -Notice that the `PropelMigration_1286484196` was executed _down_, not _up_ like the previous time. You can call this command several times to continue reverting the database structure, up to its original state: - -```text -> propel-gen down - -[propel-migration-down] Executing migration PropelMigration_1286483354 down -[propel-migration-down] 1 of 1 SQL statements executed successfully on datasource "bookstore" -[propel-migration-down] Reverse migration complete. No more migration available for reverse -``` - -As you may have guessed, the `up` task does exactly the opposite: it executes the next migration up: - -```text -> propel-gen up - -[propel-migration-up] Executing migration PropelMigration_1286483354 up -[propel-migration-up] 1 of 1 SQL statements executed successfully on datasource "bookstore" -[propel-migration-up] Migration complete. 1 migrations left to execute. -``` - ->**Tip**
The difference between the `up` and `migrate` tasks is that `up` executes only one migration, while `migrate` executes all the migrations that were not yet executed. - -### Migration Status ### - -If you followed the latest example, you may notice that the schema and the database should now be desynchronized. By calling `down` twice, and `up` just once, there is one migration left to execute. This kind of situation sometimes happen in the life of a project: you don't really know which migrations were already executed, and which ones need to be executed now. - -For these situations, Propel provides the `status` task. It simply lists the migrations not yet executed, to help you understand where you are in the migration process. - -```text -> propel-gen status - -[propel-migration-status] Checking Database Versions... -[propel-migration-status] Listing Migration files... -[propel-migration-status] 1 migration needs to be executed: -[propel-migration-status] PropelMigration_1286484196 -[propel-migration-status] Call the "migrate" task to execute it -``` - ->**Tip**
Like all other Propel tasks, `status` offers a "verbose" mode, where the CLI output shows a lot more details. Add `-verbose` at the end of the call to enable it - but remember to add the path to the project as first argument: - -```text -> propel-gen . status -verbose -[propel-migration-status] Checking Database Versions... -[propel-migration-status] Connecting to database "bookstore" using DSN "mysql:dbname=bookstore" -[propel-migration-status] Latest migration was executed on 2010-10-07 22:29:14 (timestamp 1286483354) -[propel-migration-status] Listing Migration files... -[propel-migration-status] 2 valid migration classes found in "/Users/francois/propel/1.6/test/fixtures/migration/build/migrations" -[propel-migration-status] 1 migration needs to be executed: -[propel-migration-status] > PropelMigration_1286483354 (executed) -[propel-migration-status] PropelMigration_1286484196 -[propel-migration-status] Call the "migrate" task to execute it -``` - -`up`, `down`, and `status` will help you to find your way in migration files, especially when they become numerous or when you need to revert more than one. - ->**Tip**
There is no need to keep old migration files if you are sure that you won't ever need to revert to an old state. If a new developer needs to setup the project from scratch, the `sql` and `insert-sql` tasks will initialize the database structure to the current XML schema. - -## How Do Migrations Work? ## - -The Propel `diff` task creates migration class names (like `PropelMigration_1286483354`) using the timestamp of the date they were created. Not only does it make the classes automatically sorted by date in a standard directory listing, it also avoids collision between two developers working on two structure changes at the same time. - -Propel creates a special table in the database, where it keeps the date of the latest executed migration. That way, by comparing the available migrations and the date of the latest ones, Propel can determine the next migration to execute. - -```text -mysql> select * from propel_migration; -+------------+ -| version | -+------------+ -| 1286483354 | -+------------+ -1 row in set (0.00 sec) -``` - -So don't be surprised if your database show a `propel_migration` table that you never added to your schema - this is the Propel migration table. Propel doesn't use this table at runtime, and it never contains more than one line, so it should not bother you. - -## Migration Configuration ## - -The migration tasks support customization through a few settings from `build.properties`: - -```ini -# Name of the table Propel creates to keep the latest migration date -propel.migration.table = propel_migration -# Whether the comparison between the XML schema and the database structure -# cares for differences in case (e.g. 'my_table' and 'MY_TABLE') -propel.migration.caseInsensitive = true -# The directory where migration classes are generated and looked for -propel.migration.dir = ${propel.output.dir}/migrations -``` - ->**Tip**
The `diff` task supports an additional parameter, called `propel.migration.editor`, which specifies a text editor to be automatically launched at the end of the task to review the generated migration. Unfortunately, only editors launched in another window are accepted due to a Phing limitation. Mac users will find it useful, though: - -```text -> propel-gen . diff -Dpropel.migration.editor=mate -``` - -## Migrating Data ## - -Propel generates the SQL code to alter the database structure, but your project may require more. For instance, in the newly added `author` table, the developer may want to add a few records. - -That's why Propel automatically executes the `preUp()` and `postUp()` migration before and after the structure migration. If you want to add data migration, that's the place to put the related code. - -Each of these methods receive a `PropelMigrationManager` instance, which is a good way to get PDO connection instances based on the buildtime configuration. - -Here is an example implementation of data migration: - -```php - ' -ALTER TABLE `book` ADD -( - `author_id` INTEGER -); -//... -'); - } - - public function postUp($manager) - { - // post-migration code - $sql = "INSERT INTO author (first_name,last_name) values('Leo','Tolstoi')"; - $pdo = $manager->getPdoConnection('bookstore'); - $stmt = $pdo->prepare($sql); - $stmt->execute(); - } -} -``` - ->**Tip**
If you return `false` in the `preUp()` method, the migration is aborted. - -You can also use Propel ActiveRecord and Query objects, but you'll then need to bootstrap the `Propel` class and the runtime autoloading in the migration class. This is because the Propel CLI does not know where the runtime classes are. - -```php -getPdoConnection('bookstore'); - $author = new Author(); - $author->setFirstName('Leo'); - $author->setLastname('Tolstoi'); - $author->save($pdo); - } - - public function getUpSQL() - { - // ... - } -} -``` - -Of course, you can add code to the `preDown()` and `postDown()` methods to execute a data migration when reverting migrations. diff --git a/documentation/index.markdown b/documentation/index.markdown deleted file mode 100644 index 0233942d..00000000 --- a/documentation/index.markdown +++ /dev/null @@ -1,97 +0,0 @@ ---- -layout: documentation -title: Documentation ---- - -# Documentation # - - * [What's New in Propel 1.6](whats-new.html) Users of previous versions can check the changes here. - * [Changelog](https://raw.github.com/propelorm/Propel/master/CHANGELOG) Updates in the 1.6 branch since the release of 1.6.0 stable. - * [API Documentation](http://api.propelorm.org/) The generated API documentation. - -## Project Setup ## - - * [Installing Propel](01-installation.html) Install Propel using Git, PEAR, or a tarball. - * [Building A Project](02-buildtime.html) Generate a PHP model based on a XML schema - -## Propel Basics ## - -* [Basic CRUD](03-basic-crud.html) The basics of Propel C.R.U.D. (Create, Retrieve, Update, Delete) operations -* [Relationships](04-relationships.html) Searching and manipulating data from related tables. -* [Validators](05-validators.html) The validation framework checks data before insertion based on column type. -* [Transactions](06-transactions.html) Where and when to use transactions. -* [Behaviors](07-behaviors.html) The behavior system allows to package and reuse common model features. -* [Logging And Debugging](08-logging.html) Propel can log a lot of information, including the SQL queries it executes. -* [Inheritance](09-inheritance.html) Single Table Inheritance, Class Table Inheritance, and Concrete Table Inheritance come free with Propel. -* [Migrations](10-migrations.html) Change the structure of the database without altering the data. - -## Reference ## - -* [XML Schema Format](../reference/schema.html) All the database, table, column and foreign key options explained -* [Active Record Classes](../reference/active-record.html) Complete list of the methods of Active Record classes. -* [Active Query Classes](../reference/model-criteria.html) Complete list of the methods of Propel Query classes. -* [Build Properties](../reference/buildtime-configuration.html) Reference for the `build.properties` file (`propel.ini` in symfony). -* [Runtime Configuration File](../reference/runtime-configuration.html) Reference for the `runtime-conf.xml` file. - -## Behaviors Reference ## - -* [`aggregate_column`](../behaviors/aggregate-column.html) -* [`alternative_coding_standards`](../behaviors/alternative-coding-standards.html) -* [`archivable`](../behaviors/archivable.html) -* [`auto_add_pk`](../behaviors/auto-add-pk.html) -* [`delegate`](../behaviors/delegate.html) -* [`i18n`](../behaviors/i18n.html) -* [`nested_set`](../behaviors/nested-set.html) -* [`query_cache`](../behaviors/query-cache.html) -* [`sluggable`](../behaviors/sluggable.html) -* *[`soft_delete`](../behaviors/soft-delete.html) (deprecated, use `archivable` instead)* -* [`timestampable`](../behaviors/timestampable.html) -* [`sortable`](../behaviors/sortable.html) -* [`versionable`](../behaviors/versionable.html) -* And [`concrete_inheritance`](09-inheritance.html), documented in the Inheritance Chapter even if it's a behavior - -You can also look at [user contributed behaviors](../cookbook/user-contributed-behaviors.html). - -## Cookbook ## - -### Common Tasks ### - -* [Additional SQL Files](../cookbook/adding-additional-sql-files.html) How to execute custom SQL statements at buildtime -* [Advanced Column Types](../cookbook/working-with-advanced-column-types.html) How to work with BLOBs, serialized PHP objects, ENUM, and ARRAY column types. -* [Customizing build](../cookbook/customizing-build.html) How to customize the Phing build process. -* [DB Designer](../cookbook/dbdesigner.html) How to import an XML schema from existing DBDesigner 4 file. -* [How to Use PHP 5.3 Namespaces](../cookbook/namespaces.html) How to generate model classes with namespaces, and how to use them. -* [Model Introspection At Runtime](../cookbook/runtime-introspection.html) How to use the Map classes to discover table properties at runtime. -* [Multi-Component Data Model](../cookbook/multi-component-data-model.html) How to generate model classes in subdirectories, and organize your model into independent packages / modules. -* [Object Copy](../cookbook/copying-persisted-objects.html) How to clone and copy persisted objects. -* [Replication](../cookbook/replication.html) How to use Propel in a Master-Slave Replication Environment. -* [Using Propel With MSSQL Server](../cookbook/using-mssql-server.html) How to choose and configure Propel to persist data to a Microsoft SQL Server database. -* [Using SQL Schemas](../cookbook/using-sql-schemas.html) How to organize tables into SQL schemas (only for MySQL, PostgreSQL, and MSSQL). -* [Working With Existing Databases](../cookbook/working-with-existing-databases.html) How to build an XML schema from an existing db structure, how to dump data to XML, how to import it into a new database, etc. - -### Contribute to Propel ### - -* [Writing A Behavior](../cookbook/writing-behavior.html) How to write a custom behavior to reuse model code horizontally. -* [Testing Your Behaviors](../cookbook/testing-your-behaviors.html) How to unit test your behaviors. -* [Working with unit tests](../cookbook/working-with-unit-tests.html) How to setup propel's required environment and use PHPUnit. - -### Working with symfony 1.4 ### - -* [Using Propel as Default ORM](../cookbook/symfony1/init-a-Symfony-project-with-Propel-git-way.html) How to initialize a symfony project with Propel as default ORM - the git way. -* [Using the `i18n` behavior](../cookbook/symfony1/how-to-use-old-SfPropelBehaviori18n-with-sf1.4.html) How to use Propel's `i18n` behavior with symfony 1.4. -* [Using the legacy `symfony_i18n` behavior](../cookbook/symfony1/how-to-use-old-SfPropelBehaviori18n-with-sf1.4.html) How to use the old `SfPropelBehaviori18n` (a.k.a. `symfony_i18n`) with symfony 1.4. - -### Working with Symfony2 ### - -* [Working with Symfony2 (Introduction)](../cookbook/symfony2/working-with-symfony2.html) -* [Symfony2 And Propel In Real Life](../cookbook/symfony2/symfony2-and-propel-in-real-life.html) -* [Mastering Symfony2 Forms With Propel](../cookbook/symfony2/mastering-symfony2-forms-with-propel.html) -* [The Symfony2 Security Component And Propel](../cookbook/symfony2/the-symfony2-security-component-and-propel.html) -* [Adding A New Behavior In Symfony2](../cookbook/symfony2/adding-a-new-behavior-in-symfony2.html) -* [Testing](../cookbook/symfony2/testing.html) - -### Working with Silex ### - -* [Working with Silex](../cookbook/silex/working-with-silex.html) - ->**Tip**
This is the up-to-date documentation for the last Propel version. To access the old documentation, please visit [trac.propelorm.org](http://trac.propelorm.org). diff --git a/documentation/whats-new.markdown b/documentation/whats-new.markdown deleted file mode 100644 index e780b4e3..00000000 --- a/documentation/whats-new.markdown +++ /dev/null @@ -1,723 +0,0 @@ ---- -layout: documentation -title: What's new in Propel 1.6? ---- - -# What's new in Propel 1.6? # - -Propel 1.6 is a new backwards compatible iteration of the Propel 1.x branch. As usual, don't forget to rebuild your model once you upgrade to this new version. - -## Migrations ## - -How do you manage changes to your database as the Model evolves and the schema changes? Calling the `sql` and `insert-sql` task each time the schema is updated has one dreadful drawback: it erases all the data in the database. - -Starting with Propel 1.6, the `sql`-`insert-sql` sequence is replaced by the `diff`-`migrate` sequence: - - > propel-gen diff - - [propel-sql-diff] Reading databases structure... - [propel-sql-diff] 1 tables imported from databases. - [propel-sql-diff] Loading XML schema files... - [propel-sql-diff] 2 tables found in 1 schema file. - [propel-sql-diff] Comparing models... - [propel-sql-diff] Structure of database was modified: 1 added table, 1 modified table - [propel-sql-diff] "PropelMigration_1286484196.php" file successfully created in /path/to/project/build/migrations - [propel-sql-diff] Please review the generated SQL statements, and add data migration code if necessary. - [propel-sql-diff] Once the migration class is valid, call the "migrate" task to execute it. - - > propel-gen migrate - - [propel-migration] Executing migration PropelMigration_1286484196 up - [propel-migration] 4 of 4 SQL statements executed successfully on datasource "bookstore" - [propel-migration] Migration complete. No further migration to execute. - -`diff` compares the schema to the database, and generates a class with all the required `ALTER TABLE` and `CREATE TABLE` statements to update the database structure. This migration class then feeds the `migrate` task, which connects to the database and executes the migrations - with no data loss. - -Migrations are a fantastic way to work on complex projects with always evolving models ; they are also a great tool for team work, since migration classes can be shared among all developers. That way, when a developer adds a table to the model, a second developer just needs to run the related migration to have the table added to the table. - -Propel migrations can also be executed incrementally - the new `up` and `down` tasks are there for that. And when you're lost in migration, call the `status` task to check which migrations were already executed, and which ones should be executed to update the database structure. - -The Propel documentation offers [an entire chapter on Migrations](10-migrations.html) to explain how to use them and how they work. - -Migrations only work on MySQL and PostgreSQL for now. On other platforms, you should continue to use `sql` and `insert-sql`. - -## New Behaviors ## - -Propel 1.6 ships with more core behaviors than ever. - -### Versionable behavior ### - -Once enabled on a table, the `versionable` behavior will store a copy of the ActiveRecord object in a separate table each time it is saved. This allows to keep track of the changes made on an object, whether to review modifications, or revert to a previous state. - -The classic Wiki example is a good illustration of the utility of the `versionable` behavior: - -```xml -
