Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse files

Fix various typos and deprecated code in guides

Update the typos in most guides and also update or remove some
deprecated code.
  • Loading branch information...
commit 366769426748267b1718c99f7655a3671aeba34c 1 parent 73f6079
@robin850 authored
View
157 documentation/documentation/01-installation.markdown
@@ -5,135 +5,144 @@ title: Installing Propel
# Installing Propel #
-Propel is available as a [PEAR](http://pear.php.net/manual/en/installation.getting.php) package, as a clone from the official [Github repository](http://github.com/propelorm/Propel2), as a checkout from Subversion through Github and as a "traditional" [tgz](https://github.com/propelorm/Propel2/tarball/master) or [zip](https://github.com/propelorm/Propel/zipball/master) package. Whatever installation method you may choose, getting Propel to work is pretty straightforward.
+Propel is available as a [PEAR](http://pear.php.net/manual/en/installation.getting.php) package, as a clone from the official [Github repository](http://github.com/propelorm/Propel2), as a checkout from Subversion through Github and as a "traditional" [tgz](https://github.com/propelorm/Propel2/tarball/master) or [zip](https://github.com/propelorm/Propel2/zipball/master) package. Whatever installation method you may choose, getting Propel to work is pretty straightforward.
## Prerequisites ##
-Propel runs on most PHP platforms. It just requires:
+Propel just requires:
-* [PHP 5.3.3](http://www.php.net/) or newer, with the DOM (libxml2) module enabled
+* [PHP 5.4](http://www.php.net/) or newer, with the DOM (libxml2) module enabled
* A supported database (MySQL, MS SQL Server, PostgreSQL, SQLite, Oracle)
+Propel also uses some Symfony2 components to work properly:
+
+* [Console](https://github.com/symfony/Console) : which manage the generators propel uses.
+* [Yaml](https://github.com/symfony/Yaml)
+* [Validator](https://github.com/symfony/Validator) : a way you manage validations with Propel.
+* [Finder](https://github.com/symfony/Finder) : uses in the source code to manage the files.
+
>**Tip**<br />Propel uses the PDO and SPL components, which are bundled and enabled by default in PHP5.
-## Project-Local Installation ##
+## Setup ##
-For a quick start, the best choice is to install Propel inside a project directory structure, typically under a `vendor/` subdirectory:
+### Via Composer ###
-```bash
-myproject/
- ...
- vendor/ <= This is where third-party libraries usually go
+We advise you to rely on [Composer](http://getcomposer.org/) to manage your projects' dependencies. If you want to install Propel via Composer, just create a new `composer.json` file at the root of your project's directory with the following content:
+
+```json
+{
+ "require": {
+ "propel/propel": ">= 2.0"
+ }
+}
```
-To install Propel there using Git, type:
+Then you have to download Composer itself so in a terminal just type the following:
```bash
-cd myproject/vendor
-git clone https://github.com/propelorm/Propel2.git propel
+$ wget http://getcomposer.org/composer.phar
+# If you haven't wget on your computer
+$ curl -s http://getcomposer.org/installer | php
```
-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:
+Finally, to install all your project's dependencies, type the following:
```bash
-cd myproject/vendor
-wget http://files.propelorm.org/propel-2.0.0.tar.gz
-tar zxvf propel-2.0.0.tar.gz
-mv propel-2.0.0 propel
+$ php composer.phar install
```
-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`.
+### Via Git ###
-## Propel Directory Structure ##
+If you want, you can also setup Propel using Git cloning the Github repository:
-The root directory of the Propel library includes the following folders:
+```bash
+$ git clone git://github.com/propelorm/Propel2 vendor/propel
+```
-|Folders |Explanations
-|---------------|----------------------------------------------------------------------
-|bin |Contains three scripts that manage propel command line tool (depending of your operating system)
-|src |The propel source code. Pass over if you just want to use Propel, not to contribute.
-|tests |Propel unit tests. Ignore this if you don't want to contribute to Propel.
+Propel is well unit-tested so the cloned version should be pretty stable. If you want to update Propel, just go to the repository and pull the remote:
-## Installing Dependencies ##
+```bash
+$ cd myproject/vendor/propel
+$ git pull
+```
-Propel uses the some Symfony2 components to work properly:
+### Global Installation Via PEAR ###
-- [Console](https://github.com/symfony/Console) : which manage the generators propel uses.
-- [Yaml](https://github.com/symfony/Yaml)
-- [Validator](https://github.com/symfony/Validator) : a way you manage validations with Propel.
-- [Finder](https://github.com/symfony/Finder) : uses in the source code to manage the files.
+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.
-To install these packages, we advise you to use Composer. Check out the [Composer's site](https://getcomposer.org) and then add the following to you composer.json file :
+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.
-```json
-{
- "require": {
- "symfony/yaml": ">=2.0",
- "symfony/console": ">=2.0",
- "monolog/monolog": ">=1.0.2",
- "symfony/finder": ">=2.0",
- "symfony/validator": ">=2.0"
- }
-}
-```
+So the commands to install Propel, Phing and PEAR Log globally sum up to this:
-Then, to install all of the dependencies, run in a terminal:
```bash
-php composer.phar install
+$ pear channel-discover pear.propelorm.org
+$ pear install -a propel/propel
```
-_Note_ : The composer.phar file must be at the same directory level of the composer.json file.
+Once Propel is installed globally, you can access the `propel` command from everywhere without symlink.
-## Testing Propel Installation ##
-
-The Propel generator component bundles a `propel` sh script (and a `propel.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` script from the CLI:
+>**Tip**<br />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
-cd myproject
-vendor/propel/bin/propel
+$ pear config-set preferred_state beta
```
-The command should output the propel version following by a list of the options and the available commands. We will learn to use these commands later.
+#### PEAR Directory In Include Path ####
->**Tip**<br />In order to allow an easier execution of the script, you can also add the propel generator's `bin/` directory to your PATH, or create a symlink. For example:
+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.
-```bash
-cd myproject
-ln -s vendor/propel/bin/propel propel
-```
+### Using a Tarball Or a Zipball ###
-Or simply edit your .bashrc or .zshrc file:
+Alternatively, to use a tarball, type the following commands on unix platforms:
```bash
-export PATH=$PATH:/path/to/vendor/bin/
+$ cd myproject/vendor
+$ wget http://files.propelorm.org/propel-2.0.0.tar.gz
+$ tar zxvf propel-2.0.0.tar.gz
+$ mv propel-2.0.0 propel
```
-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.
+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`.
-## Alternative: Global Installation Using PEAR ##
+## Propel Directory Structure ##
-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.
+The root directory of the Propel library includes the following folders:
-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).
+|Folders |Explanations
+|---------------|----------------------------------------------------------------------
+|bin |Contains three scripts that manage propel command line tool (depending of your operating system)
+|documentation |The Propel documentation source
+|features |Tests written with the Behat framework
+|resources |Contains some files such as the database XSD or DTD
+|src |The Propel source code. Pass over if you just want to use Propel, not to contribute.
+|tests |Propel unit tests. Ignore this if you don't want to contribute to Propel.
-So the commands to install Propel, Phing and PEAR Log globally sum up to this:
+## Testing Propel Installation ##
+
+The Propel generator component bundles a `propel` sh script (and a `propel.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` script from the CLI:
```bash
-pear channel-discover pear.propelorm.org
-pear install -a propel/propel_generator
-pear install -a propel/propel_runtime
+$ cd myproject
+$ vendor/propel/bin/propel
```
-Once Propel is installed globally, you can access the `propel-gen` command from everywhere without symlink.
+The command should output the propel version following by a list of the options and the available commands. We will learn to use these commands later.
+
+>**Tip**<br />In order to allow an easier execution of the script, you can also add the propel generator's `bin/` directory to your PATH, or create a symlink. For example:
->**Tip**<br />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
+$ cd myproject
+$ ln -s vendor/propel/bin/propel propel
+```
+
+Or simply edit your .bashrc or .zshrc file:
```bash
-pear config-set preferred_state beta
+export PATH=$PATH:/path/to/vendor/bin/
```
+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.
+
## Troubleshooting ##
### PHP Configuration ###
@@ -146,10 +155,6 @@ Propel requires the following settings in `php.ini`:
|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.
-
### 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.
View
136 documentation/documentation/02-buildtime.markdown
@@ -17,7 +17,7 @@ To illustrate Propel's build abilities, this chapter uses the data structure of
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.
+Create a `bookstore` directory then setup Propel into it as covered in the previous chapter. This will be the root of the bookstore project.
### Database Connection Name ###
@@ -89,7 +89,7 @@ Each column also requires a `type`. The XML schema is database agnostic, so the
As for the other column attributes, `required`, `primaryKey`, and `autoIncrement`, they mean exactly what their names imply.
->**Tip**<br />Propel supports namespaces (for PHP > 5.3). If you specify a `namespace` attribute in a `<table>` element, the generated PHP classes for this table will use this namespace.
+>**Tip**<br />If you specify a `namespace` attribute in a `<table>` element, the generated PHP classes for this table will use this namespace.
### Foreign Keys ###
@@ -147,41 +147,47 @@ Use your own database vendor driver, chosen among pgsql, mysql, sqlite, mssql, a
You can learn more about the available build settings and their possible values in the [build configuration reference](../reference/buildtime-configuration).
-### Using the `propel-gen` Script To Build The Model ###
+### Using the `propel` Script To Build The SQL Code ###
-The Propel generator uses the `propel-gen` script, as seen in the previous chapter. This executable expects a command name as its argument.
+As seen in the previous chapter, Propel ships with a script that allows you to realise different actions such as schemas generation.
-Open a terminal and browse to the `bookstore/` directory, where you saved the two previous files (`schema.xml`, and `build.properties`). Then use the `propel-gen` script to call the "Object Model generator" command using its shortcut - "om":
+Open a terminal and browse to your project's directory (here `bookstore/`), where you saved the two previous files (`schema.xml`, and `build.properties`). Then use the `propel` script to generate the SQL code of your schema:
```bash
-cd /path/to/bookstore
-propel-gen om
+$ cd /path/to/bookstore
+$ propel sql:build
```
-You should normally see a some colored lines appear in the terminal, logging all the class generation, and ending with "BUILD FINISHED". If not, look for red lines in the log and follow the directions in the error messages.
+Before insert it into your database, you should create a database, let's say we want to call it `bookstore`. If you are using MySQL for instance, just run:
-### Generated Object Model ###
+```bash
+$ mysqladmin -u root -p create bookstore
+```
+
+Then insert the SQL into your database:
+```bash
+$ propel sql:insert
+```
+
+You should normally have yours tables created. Propel will also generate a `generated-sql` containning the SQL files of your schema ; useful if you are using a SCM, you can so compare the different versions of your schema.
+
+Each time you will update your schema, you should run `sql:build` and `sql:insert`.
+
+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.
+
+>**Tip**<br />The `schema.sql` file will DROP any existing table before creating them, which will effectively erase your database.
-The "om" command added a new directory in the `bookstore/` project, called `build/`. The generated model classes are located under the `classes/bookstore/` subdirectory:
+### Generate Model Classes ###
+
+Now that your database is ready, we are going to generate our model files. These files are just classes that allows you to interact easily with your different tables. To generate these tables, just run:
```bash
-> cd /path/to/bookstore
-> cd build/classes/bookstore/
-> ls
- om/
- map/
- AuthorTableMap.php
- BookTableMap.php
- PublisherTableMap.php
- Author.php
- AuthorQuery.php
- Book.php
- BookQuery.php
- Publisher.php
- PublisherQuery.php
+$ propel model:build
```
-For every table in the database, Propel creates 3 PHP classes:
+Propel will generate a new `generated-classes` folder containning all the stuff you need to interact with your different tables.
+
+For every table in the database, Propel creates 2 PHP classes:
* a _model_ class (e.g. `Book`), which represents a row in the database;
* a _tablemap_ class (e.g. `Map\BookTableMap`), offering static constants and methods mostly for compatibility with previous Propel versions;
@@ -189,7 +195,7 @@ For every table in the database, Propel creates 3 PHP classes:
Propel uses the `phpName` attribute of each table as the base for the PHP class names.
-All these classes are empty, but they inherit from `Base` classes that you will find under the `om/` directory:
+All these classes are empty, but they inherit from `Base` classes that you will find under the `Base/` directory in the `generated-classes` one:
```php
<?php
@@ -202,83 +208,27 @@ class Book extends BaseBook
}
```
-These empty classes are called _stub_ classes. This is where you will add your own model code. These classes are generated only once by Propel ; on the other hand, the _base_ classes they extend are overwritten every time you call the `om` command, and that happens a lot in the course of a project, because the schema evolves with your needs.
-
-In addition to these classes, Propel generates one `TableMap` class for each table under the `map/` directory. You will probably never use the map classes directly, but Propel needs them to get metadata information about the table structure at runtime.
-
->**Tip**<br />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 ##
+These empty classes are called _stub_ classes. This is where you will add your own model code. These classes are generated only once by Propel ; on the other hand, the _base_ classes they extend are overwritten every time you call the `model:build` command, and that happens a lot in the course of a project, because the schema evolves with your needs.
-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`.
+In addition to these classes, Propel generates one `TableMap` class for each table under the `Map/` directory. You will probably never use the map classes directly, but Propel needs them to get metadata information about the table structure at runtime.
-### Using The SQL File ###
+>**Tip**<br />Never add any code of your own to the classes generated by Propel in the `Map/` directory; this code would be lost next time you call the `model:build` command.
-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**<br />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
-```
+Basically, all that means is that despite the fact that Propel generates _five_ classes for each table, you should only care about two of them: the model class and the query class.
## 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 tell Propel which database connection settings should be used to finish the setup.
-Propel stores the runtime settings in a service container, available from everywhere using `\Propel\Runtime\Propel::getServiceContainer()`. The service container uses lazy-loading to initiate connections only when necessary.
+Propel stores the runtime settings in a service container, available from everywhere using `\Propel\Runtime\Propel::getServiceContainer()`. The service container uses lazy-loading to initiate connections only when necessary.
Here is a sample setup file:
```php
<?php
// setup the autoloading
-require_once '/path/to/propel/vendor/autoload.php';
+require_once '/path/to/vendor/autoload.php';
use Propel\Runtime\Propel;
use Propel\Runtime\Connection\ConnectionManagerSingle;
$serviceContainer = Propel::getServiceContainer();
@@ -305,7 +255,7 @@ $defaultLogger->pushHandler(new StreamHandler('/var/log/propel.log', Logger::WAR
$serviceContainer->setLogger('defaultLogger', $defaultLogger);
```
-**Tip**: You may wish to write the setup code in a standalone script that is included at the beginning of your PHP scripts.
+>**Tip**<br/>: You may wish to write the setup code in a standalone script that is included at the beginning of your PHP scripts.
Now you are ready to start using your model classes!
@@ -346,11 +296,11 @@ See the [runtime configuration reference](../reference/runtime-configuration) fo
### Building the Runtime Configuration ###
-For performance reasons, Propel prefers to use a PHP version of the connection settings rather than the XML file you just defined. So you must use the `propel-gen` script one last time to build the PHP version of the `runtime-conf.xml` configuration:
+For performance reasons, Propel prefers to use a PHP version of the connection settings rather than the XML file you just defined. So you must use the `propel` script one last time to build the PHP version of the `runtime-conf.xml` configuration:
```bash
-cd /path/to/bookstore
-propel-gen config:convert-xml
+$ cd /path/to/bookstore
+$ propel config:convert-xml
```
The resulting file can be found under `build/conf/bookstore-conf.php`, where "bookstore" is the name of the project you defined in `build.properties`.
@@ -360,7 +310,7 @@ This simplifies the setup of Propel to the following script:
```php
<?php
// setup the autoloading
-require_once '/path/to/propel/vendor/autoload.php';
+require_once '/path/to/vendor/autoload.php';
// setup Propel
require_once 'build/conf/bookstore-conf.php';
View
18 documentation/documentation/03-basic-crud.markdown
@@ -244,14 +244,17 @@ echo $author->getFirstName(); // 'Jane'
The Query methods that don't return the current query object are called "Termination Methods". You've already seen come of them: `find()`, `findOne()`, `update()`, `delete()`. There are two more termination methods that you should know about:
+`count()` returns the number of results of the query.
+
```php
<?php
-// count() returns the number of results of the query.
$nbAuthors = AuthorQuery::create()->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
+```
+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:
-// paginate() returns a paginated list of results
+```php
$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.
@@ -259,7 +262,12 @@ $authorPager = AuthorQuery::create()->paginate($page = 1, $maxPerPage = 10);
foreach ($authorPager as $author) {
echo $author->getFirstName();
}
-// A pager object gives more information
+```
+
+A pager object gives more information:
+
+```php
+<?php
echo $pager->getNbResults(); // total number of results if not paginated
echo $pager->haveToPaginate(); // return true if the total number of results exceeds the maximum per page
echo $pager->getFirstIndex(); // index of the first result in the page
View
14 documentation/documentation/04-relationships.markdown
@@ -27,7 +27,7 @@ $book->save();
Propel generates the `setAuthor()` method based on the `phpName` attribute of the `<foreign-key>` element in the schema. When the attribute is not set, Propel uses the `phpName` of the related table instead.
-Internally, the call to `Book::setAuthor($author)` translates into `Book::setAuthorId($author->getId())`. But you don't actually have to save a Propel object before associating it to another. In fact, Propel automatically "cascades" INSERT statements when a new object has other related objects added to it.
+Internally, the call to `Book::setAuthor($author)` translates into `Book::setAuthorId($author->getId())`. But you don't actually have to save a Propel object before associating it to another. In fact, Propel automatically "cascades" `INSERT` statements when a new object has other related objects added to it.
For one-to-many relationships - meaning, from the other side of a many-to-one relationship - the process is a little different. In the previous example, one `Book` has one `Author`, but one `Author` has many `Books`. From the `Author` point of view, a one-to-many relationships relates it to `Book`. So Propel doesn't generate an `Author::setBook()`, but rather an `Author::addBook()`:
@@ -74,7 +74,7 @@ $book->setAuthor($author);
$book->save(); // saves all 3 objects!
```
-In practice, Propel _'cascades_' the `save()` action to the related objects.
+In practice, Propel _"cascades"_ the `save()` action to the related objects.
## Reading Related Object Properties ##
@@ -100,7 +100,7 @@ foreach ($books as $book) {
Notice that Propel generated a `getBooks()` method returning an array of `Book` objects, rather than a `getBook()` method. This is because the definition of a foreign key defines a many-to-one relationship, seen from the other end as a one-to-many relationship.
->**Tip**<br />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())`.
+>**Tip**<br />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:
@@ -131,7 +131,7 @@ You don't need to specify that the `author_id` column of the `Book` object shoul
### 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 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()`.
@@ -204,7 +204,7 @@ Databases typically use a cross-reference table, or junction table, to materiali
</table>
```
-Once you rebuild your model, the relationship is seen as a one-to-many relationship from both the `User` and the `Group` models. That means that you can deal with adding and reading relationships the same way as you usually do:
+Once you rebuild your model, the relationship is seen as a one-to-many relationship from both the `User` and the `Group` models. That means that you can deal with adding and reading relationships the same way as you usually do:
```php
<?php
@@ -244,7 +244,7 @@ $groups = GroupQuery::create()
## One-to-One Relationships ##
-Propel supports the special case of one-to-one relationships. These relationships are defined when the primary key is also a foreign key. For example :
+Propel supports the special case of one-to-one relationships. These relationships are defined when the primary key is also a foreign key. For example:
```xml
<table name="bookstore_employee" description="Employees of a bookstore">
@@ -310,7 +310,7 @@ $author = $book->getAuthor(); // Same result, with no supplementary query
Since the call to `with()` adds the columns of the related object to the SELECT part of the query, and uses these columns to populate the related object, that means that a query using `with()` is slower and consumes more memory. So use it only when you actually need the related objects afterwards.
-If you don't want to add a filter on a related object but still need to hydrate it, calling `useXXXQuery()`, `endUse()`, and then `with()` can be a little cumbersome. For this case, Propel provides a proxy method called `joinWith()`. It expects a string made of the initial query name and the foreign query name. For instance:
+If you don't want to add a filter on a related object but still need to hydrate it, calling `useXXXQuery()`, `endUse()`, and then `with()` can be a little cumbersome. For this case, Propel provides a proxy method called `joinWith()`. It expects a string made of the initial query name and the foreign query name. For instance:
```php
<?php
View
6 documentation/documentation/06-transactions.markdown
@@ -47,7 +47,7 @@ The transaction statements are `beginTransaction()`, `commit()` and `rollback()`
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::getReadConnection([ModelName]TableMap::DATABASE_NAME)` (for READ queries) and `Propel::getWriteConnection([ModelName]TableMap::DATABASE_NAME)` (for WRITE queries).
+>**Tip**<br/>: In order to build a transaction, you need a connection object. The connection object for a Propel model is always available through `Propel::getReadConnection([ModelName]TableMap::DATABASE_NAME)` (for READ queries) and `Propel::getWriteConnection([ModelName]TableMap::DATABASE_NAME)` (for WRITE queries).
## Denormalization And Transactions ##
@@ -130,7 +130,7 @@ class Book extends BaseBook
In this example, the `nb_books` column of the `author` table will always we synchronized with the number of books. If anything happens during the transaction, the saving of the book is rolled back, as well as the `nb_books` column update. The transaction serves to preserve data consistency in a denormalized schema ("Consistency" stands for the C in ACID).
->**Tip**<br />Check the [behaviors documentation]() for details about the pre- and post- hooks in Propel model objects.
+>**Tip**<br />Check the [behaviors documentation](07-behaviors.html#pre-and-post-hooks-for-save-and-delete-methods) for details about the pre- and post- hooks in Propel model objects.
## Nested Transactions ##
@@ -246,7 +246,7 @@ 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.
+>**Tip**<br/>: 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? ##
View
6 documentation/documentation/07-behaviors.markdown
@@ -6,7 +6,7 @@ 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.
+Behaviors are a great way to package model extensions for reusability. They are powerful, versatile, fast, and help you organize your code in a better way.
## Pre and Post Hooks For `save()` And `delete()` Methods ##
@@ -61,7 +61,7 @@ echo $b->getCreatedAt(); // 2009-10-02 18:14:23
_Warning_: If you implement `preInsert()`, `preUpdate()`, `preSave()` or `preDelete()`, these methods **must return a boolean value**. Any return value other than `true` stops the action (save or delete). This is a neat way to bypass persistence on some cases, but can also create unexpected problems if you forget to return `true`.
->**Tip**<br />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`.
+>**Tip**<br />Since this feature adds a small overhead to write operations, you can disable it completely in your build properties by setting `propel.addHooks` to `false`.
```ini
# -------------------
@@ -231,7 +231,7 @@ propel.behavior.default = archivable, timestampable
## Writing a Behavior ##
-Check the behaviors bundled with Propel to see how to implement your own behavior: they are the best starting point to understanding the power of behaviors and builders.
+Check [the behaviors bundled with Propel](https://github.com/propelorm/Propel2/tree/master/src/Propel/Generator/Behavior) to see how to implement your own behavior: they are the best starting point to understanding the power of behaviors and builders.
### Modifying the Data Model ###
View
7 documentation/documentation/09-inheritance.markdown
@@ -5,7 +5,12 @@ title: Inheritance
# Inheritance #
-Developers often need one model table to extend another model table. Inheritance being an object-oriented notion, it doesn't have a true equivalent in the database world, so this is something an ORM must emulate. Propel offers three types of table inheritance: [Single Table Inheritance](http://www.martinfowler.com/eaaCatalog/singleTableInheritance.html), which is the most efficient implementations from a SQL and query performance perspective, but is limited to a small number of inherited fields ; [Class Table Inheritance](http://martinfowler.com/eaaCatalog/classTableInheritance.html), which separates data into several tables and uses joins to fetch complete children entities, and [Concrete Table Inheritance](http://www.martinfowler.com/eaaCatalog/concreteTableInheritance.html), which provides the most features but adds a small overhead on write queries.
+Developers often need one model table to extend another model table. Inheritance being an object-oriented notion, it doesn't have a true equivalent in the database world, so this is something an ORM must emulate. Propel offers three types of table inheritance:
+
+* [Single Table Inheritance](http://www.martinfowler.com/eaaCatalog/singleTableInheritance.html), which is the most efficient implementations from a SQL and query performance perspective, but is limited to a small number of inherited fields
+* [Class Table Inheritance](http://martinfowler.com/eaaCatalog/classTableInheritance.html), which separates data into several tables and uses joins to fetch complete children entities
+* [Concrete Table Inheritance](http://www.martinfowler.com/eaaCatalog/concreteTableInheritance.html), which provides the most features but adds a small overhead on write queries.
+
## Single Table Inheritance ##
Please sign in to comment.
Something went wrong with that request. Please try again.