From c584886afd5ed1a51dbcdf18e96817c540c69526 Mon Sep 17 00:00:00 2001 From: Francois Zaninotto Date: Sun, 23 Oct 2011 23:03:22 +0200 Subject: [PATCH] Document the new ORM feature --- readme.md | 82 ++++++++++++++++++------ src/Faker/ORM/Propel/EntityPopulator.php | 2 +- src/Faker/Provider/Miscellaneous.php | 11 ++++ test/test2.php | 20 ------ 4 files changed, 75 insertions(+), 40 deletions(-) delete mode 100644 test/test2.php diff --git a/readme.md b/readme.md index 6d78ebc4..d56d2a0c 100644 --- a/readme.md +++ b/readme.md @@ -116,30 +116,33 @@ Each of the generator properties (like `name`, `address`, and `lorem`) are calle ### `Faker\Provider\DateTime` - unixTime // 58754983 - dateTime // DateTime('2008-04-18 23:19:03') - iso8601 // '2007-05-25T12:33:15+0000' - date($format = 'Y-m-d') // '1978-12-07' - time($format = 'H:i:s') // '04:48:48' - dateTimeBetween($startDate = '-30 years', $endDate = 'now') // DateTime('2000-04-13 00:19:31') - dateTimeThisCentury // DateTime('1983-02-02 19:52:12') - dateTimeThisDecade // DateTime('2002-02-25 08:25:50') - dateTimeThisYear // DateTime('2011-05-09 04:16:23') - dateTimeThisMonth // DateTime('2011-09-27 07:42:29') + unixTime // 58781813 + dateTime // DateTime('2008-04-25 08:37:17') + dateTimeAD // DateTime('1800-04-29 20:38:49') + iso8601 // '1978-12-09T10:10:29+0000' + date($format = 'Y-m-d') // '1979-06-09' + time($format = 'H:i:s') // '20:49:42' + dateTimeBetween($startDate = '-30 years', $endDate = 'now') // DateTime('2003-03-15 02:00:49') + dateTimeThisCentury // DateTime('1915-05-30 19:28:21') + dateTimeThisDecade // DateTime('2007-05-29 22:30:48') + dateTimeThisYear // DateTime('2011-02-27 20:52:14') + dateTimeThisMonth // DateTime('2011-10-23 13:46:23') amPm // 'pm' dayOfMonth // '04' - dayOfWeek // 'Wednesday' - month // '09' - monthName // 'June' - year // '1985' - century // 'XII' + dayOfWeek // 'Friday' + month // '06' + monthName // 'January' + year // '1993' + century // 'VI' ### `Faker\Provider\Miscellaneous` - boolean // true - md5 // '67cc5698854132383fdad62fc845cd48' - sha1 // 'ea791e73ad1d3a7f78e8e3e61dfbf2fc44401663' - sha256 // '6327f9f323561921ae55041d39a03b7a515a58a9f780ae3a6c62a0ca8c4905f4' + boolean // true + md5 // 'de99a620c50f2990e87144735cd357e7' + sha1 // 'f08e7f04ca1a413807ebc47551a40a20a0b4de5c' + sha256 // '0061e4c60dac5c1d82db0135a42e00c89ae3a333e7c26485321f24348c7e98a5' + number($nbDigits = 3) // 23 + choose(array('a', 'b', 'c')) // 'b' ## Localization @@ -165,6 +168,47 @@ for ($i=0; $i < 10; $i++) { The localization of Faker is an ongoing process, for which we need your help. Don't hesitate to create localized providers to your own locale and submit a PR! +## Populating Entities Using an ORM + +Faker provides an adapter for the [Propel ORM](http://www.propelorm.org) to ease the population of a database using the Entity classes managed by the ORM. + +To populate entities, create a new populator class (using a generator instance as parameter), then list the class and number of all the entities that must be generated. To launch the actual data population, call the `execute()` method. + +Here is an example showing how to populate 5 `Author` and 10 `Book` objects: + +```php +addEntity('Author', 5); +$populator->addEntity('Book', 10); +$insertedPKs = $populator->execute(); +``` + +The populator uses name and column type guessers to populate each column with relevant data. For instance, Faker populates a column named `first_name` using the `firstName` formatter, and a column with a `TIMESTAMP` type using the `dateTime` formatter. The resulting entities are therefore coherent. If Faker misinterprets a column name, you can still specify a custom clusure to be used for populating a particular column, using the third argument to `addEntity()`: + +```php +addEntity('Book', 5, array( + 'ISBN' => function() use ($generator) { return $generator->randomNumber(13); } +)); +``` + +In this example, Faker will guess a formatter for all columns except `ISBN`, for which the given anonymous function will be used. + +Of course, Faker does not populate autoincremented primary keys. In addition, `Faker\ORM\Propel\Populator::execute()` returns the list of inserted PKs, indexed by class: + +```php + (34, 35, 36, 37, 38), +// 'Book' => (456, 457, 458, 459, 470, 471, 472, 473, 474, 475) +// ) +``` + +In the previous example, the `Book` and `Author` models share a relationship. Since `Author` entities are populated first, Faker is smart enough to relate the populated `Book` entities to one of the populated `Author` entities. + ## Seeding the Generator You may want to get always the same generated data - for instance when using Faker for unit testing purposes. The generator offers a `seed()` method, which seeds the random number generator. Calling the same script twice with the same seed produces the same results. diff --git a/src/Faker/ORM/Propel/EntityPopulator.php b/src/Faker/ORM/Propel/EntityPopulator.php index e274de39..9d2b951f 100644 --- a/src/Faker/ORM/Propel/EntityPopulator.php +++ b/src/Faker/ORM/Propel/EntityPopulator.php @@ -80,7 +80,7 @@ class EntityPopulator $obj = new $this->class(); foreach ($this->columnFormatters as $column => $format) { if (null !== $column) { - $obj->setByName($column, is_callable($format) ? $format($insertedEntities) : $format); + $obj->setByName($column, is_callable($format) ? $format($insertedEntities, $obj) : $format); } } $obj->save($con); diff --git a/src/Faker/Provider/Miscellaneous.php b/src/Faker/Provider/Miscellaneous.php index f720e3c4..5a636e20 100644 --- a/src/Faker/Provider/Miscellaneous.php +++ b/src/Faker/Provider/Miscellaneous.php @@ -38,4 +38,15 @@ class Miscellaneous extends \Faker\Provider\Base { return hash('sha256', mt_rand()); } + + public static function number($nbDigits = 3) + { + return static::randomNumber($nbDigits); + } + + public static function choose($list) + { + return static::randomElement($list); + } + } \ No newline at end of file diff --git a/test/test2.php b/test/test2.php deleted file mode 100644 index ac53cca4..00000000 --- a/test/test2.php +++ /dev/null @@ -1,20 +0,0 @@ -deleteAll(); -AuthorQuery::create()->deleteAll(); -$generator = \Faker\Factory::create(); -$populator = new Faker\ORM\Propel\Populator($generator); -$populator->addEntity('Author', 5, array( - 'Email' => function($entities) use ($generator) { return $generator->safeEmail; }, -)); -$populator->addEntity('Book', 10); -$inserted = $populator->execute(); - -echo BookQuery::create()->joinWith('Book.Author')->find(); \ No newline at end of file