diff --git a/documentation/cookbook/runtime-introspection.markdown b/documentation/cookbook/runtime-introspection.markdown index 8cafffe5c7..b1963d7ace 100644 --- a/documentation/cookbook/runtime-introspection.markdown +++ b/documentation/cookbook/runtime-introspection.markdown @@ -7,7 +7,7 @@ title: Model Introspection At Runtime In addition to the object and peer classes used to do C.R.U.D. operations, Propel generates an object mapping for your tables to allow runtime introspection. -The intospection objects are instances of the map classes. Propel maps databases, tables, columns, validators, and relations into objects that you can easily use. +The intospection objects are instances of the map classes. Propel maps databases, tables, columns and relations into objects that you can easily use. ## Retrieving a TableMap ## @@ -82,7 +82,6 @@ $bookTitleColumn->isNumeric(); // false $bookTitleColumn->isText(); // true $bookTitleColumn->isPrimaryKey(); // false $bookTitleColumn->isForeignKey(); // false -$bookTitleColumn->hasValidators(); // false $bookTitleColumn->isPrimaryString(); // true {% endhighlight %} diff --git a/documentation/cookbook/writing-behavior.markdown b/documentation/cookbook/writing-behavior.markdown index 515b5bd23e..02213c12ef 100644 --- a/documentation/cookbook/writing-behavior.markdown +++ b/documentation/cookbook/writing-behavior.markdown @@ -93,7 +93,7 @@ class AggregateColumnBehavior extends Behavior This method shows that a behavior class has access to the `` defined for it in the `schema.xml` through the `getParameter()` command. Behaviors can also always access the `Table` object attached to them, by calling `getTable()`. A `Table` can check if a column exists and add a new one easily. The `Table` class is one of the numerous generator classes that serve to describe the object model at buildtime, together with `Column`, `ForeignKey`, `Index`, and a lot more classes. You can find all the buildtime model classes under the `generator/lib/model` directory. -_Tip_: Don't mix up the _runtime_ database model (`DatabaseMap`, `TableMap`, `ColumnMap`, `ValidatorMap`, `RelationMap`) with the _buildtime_ database model (`Database`, `Table`, `Column`, `Validator`, etc.). The buildtime model is very detailed, in order to ease the work of the builders that write the ActiveRecord and Query classes. On the other hand, the runtime model is optimized for speed, and carries minimal information to allow correct hydration and binding at runtime. Behaviors use the buildtime object model, because they are run at buildtime, so they have access to the most powerful model. +_Tip_: Don't mix up the _runtime_ database model (`DatabaseMap`, `TableMap`, `ColumnMap`, `RelationMap`) with the _buildtime_ database model (`Database`, `Table`, `Column`, etc.). The buildtime model is very detailed, in order to ease the work of the builders that write the ActiveRecord and Query classes. On the other hand, the runtime model is optimized for speed, and carries minimal information to allow correct hydration and binding at runtime. Behaviors use the buildtime object model, because they are run at buildtime, so they have access to the most powerful model. Now rebuild the model and the SQL, and sure enough, the new column is there. `BasePollQuestion` offers a `getTotalNbVotes()` and a `setTotalNbVotes()` method, and the table creation SQL now includes the additional `total_nb_votes` column: diff --git a/documentation/documentation/05-validators.markdown b/documentation/documentation/05-validators.markdown deleted file mode 100644 index 679faec3a7..0000000000 --- a/documentation/documentation/05-validators.markdown +++ /dev/null @@ -1,240 +0,0 @@ ---- -layout: documentation -title: Validators ---- - -# Validators # - -Validators help you to validate an input before persisting it to the database. In Propel, validators are rules describing what type of data a column accepts. Validators are referenced in the `schema.xml` file, using `` tags. - -Validators are applied at the PHP level, they are not created as constraints on the database itself. That means that if you also use another language to work with the database, the validator rules will not be enforced. -You can also apply multiple rule entries per validator entry in the schema.xml file. - -## Overview ## - -In the following example, the `username` column is defined to have a minimum length of 4 characters: - -{% highlight xml %} - - - - - - -
-{% endhighlight %} - -Every column rule is represented by a `` tag. A `` is a set of `` tags bound to a column. - -At runtime, you can validate an instance of the model by calling the `validate()` method: - -{% highlight php %} -setUsername("foo"); // only 3 in length, which is too short... -if ($objUser->validate()) { - // no validation errors, so the data can be persisted - $user->save(); -} else { - // Something went wrong. - // Use the validationFailures to check what - foreach ($objUser->getValidationFailures() as $failure) { - echo $failure->getMessage() . "\n"; - } -} -{% endhighlight %} - -`validate()` returns a boolean. If the validation failed, you can access the array `ValidationFailed` objects by way of the `getValidationFailures()` method. Each `ValidationFailed` instance gives access to the column, the messagen and the validator that caused the failure. - -## Core Validators ## - -Propel bundles a set of validatorts that should help you deal with the most common cases. - -### MatchValidator ### - -The `MatchValidator` is used to run a regular expression of choice against the column. Note that this is a `preg`, not `ereg` (check [the preg_match documentation](http://www.php.net/preg_match) for more information about regexps). - -{% highlight xml %} - - - - -{% endhighlight %} - -### NotMatchValidator ### - -Opposite of `MatchValidator`, this validator returns false if the regex returns true - -{% highlight xml %} - - - - - -{% endhighlight %} - -### 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 lentgh of `LONGVARCHAR` columns; you can enforce it using a validator: - -{% highlight xml %} - - - - -{% endhighlight %} - ->**Tip**
If you have specified the `size` attribute in the `` tag, you don't have to specify the `value` attribute in the validator rule again, as this is done automatically. - -### MinLengthValidator ### - -{% highlight xml %} - - - - -{% endhighlight %} - -### MaxValueValidator ### - -To limit the value of an integer column, use the `MaxValueValidator`. Note that this validator uses a non-strict comparison ('less than or equal'): - -{% highlight xml %} - - - - -{% endhighlight %} - -### MinValueValidator ### - -{% highlight xml %} - - - - -{% endhighlight %} - ->**Tip**
You can run multiple validators against a single column. - -{% highlight xml %} - - - - - -{% endhighlight %} - -### RequiredValidator ### - -This validator checks the same rule as a `required=true` on the column at the database level. This, however, will give you a clean error to work with. - -{% highlight xml %} - - - - -{% endhighlight %} - -### UniqueValidator ### - -To check whether the value already exists in the table, use the `UniqueValidator`: - -{% highlight xml %} - - - - -{% endhighlight %} - -### ValidValuesValidator ### - -This rule restricts the valid values to a list delimited by a pipe ('|'). - -{% highlight xml %} - - - - -{% endhighlight %} - -### TypeValidator ### - -Restrict values to a certain PHP type using the `TypeValidator`: - -{% highlight xml %} - - - - -{% endhighlight %} - -## Adding A Custom Validator ## - -You can easily add a custom validator. A validator is a class extending `BasicValidator` providing a public `isValid()` method. For instance: - -{% highlight php %} -` tag. So `$map->getValue()` returns the `value` attribute. - ->**Tip**
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 `` in your schema and use 'class' as the rule `name`. - -{% highlight xml %} - - - -{% endhighlight %} - -The `class` attribute of the `` tag should contain a path to the validator class accessible from the include_path, where the directory separator is replaced by a dot. diff --git a/documentation/documentation/09-inheritance.markdown b/documentation/documentation/09-inheritance.markdown index 28d0a277a3..009451c5f7 100644 --- a/documentation/documentation/09-inheritance.markdown +++ b/documentation/documentation/09-inheritance.markdown @@ -369,7 +369,7 @@ Since the columns of the main table are copied to the child tables, this schema {% endhighlight %} ->**Tip**
The `concrete_inheritance` behavior copies columns, foreign keys, indices and validators. +>**Tip**
The `concrete_inheritance` behavior copies columns, foreign keys and indices. If you've configured the `validate` behavior, it copies also validators. ### Using Inherited Model Classes ### diff --git a/documentation/documentation/index.markdown b/documentation/documentation/index.markdown index f82439f168..4be199f7e4 100644 --- a/documentation/documentation/index.markdown +++ b/documentation/documentation/index.markdown @@ -18,7 +18,6 @@ title: Documentation * [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. diff --git a/documentation/reference/active-record.markdown b/documentation/reference/active-record.markdown index e893dd729c..22352f03d7 100644 --- a/documentation/reference/active-record.markdown +++ b/documentation/reference/active-record.markdown @@ -250,7 +250,7 @@ echo $book->getAuthor()->getLastName(); // Tolstoi - {% endhighlight %} ### Many-to-one Relationships ### @@ -280,7 +280,7 @@ $author->clearBooks(); // removes the relationship {% endhighlight %} ### Many-to-many relationships ### @@ -522,7 +522,7 @@ propel.addGenericMutators = false ## Validation ## -Active Record classes for tables using validation rules (defined in the schema using the `` and `` tags) have two additional methods: `validate()`, and `getValidationFailures()`. +Active Record classes for tables using validate behavior have three additional methods: `validate()`, `getValidationFailures()` and `loadValidatorMetadata()`. {% highlight php %} validate()) { } {% endhighlight %} -See the [Validators documentation](../documentation/05-validators) for more details. +See the [Validate behavior documentation](../behaviors/validate.html) for more details. ## Import and Export Capabilities ##