From 264d75564482e907a8de145acacb510910ef5d48 Mon Sep 17 00:00:00 2001 From: Francois Zaninotto Date: Sat, 15 Oct 2011 14:02:17 +0200 Subject: [PATCH] add a documentor class to introspect generator capabilities --- src/Documentor.php | 40 ++++++++++++++++++++++++++++++++++ src/Generator.php | 5 +++++ src/Provider/Address.php | 33 +++++++++++++++++++++++++--- src/Provider/Company.php | 8 ++++++- src/Provider/Lorem.php | 9 ++++++++ src/Provider/Name.php | 15 ++++++++++--- src/Provider/PhoneNumber.php | 5 ++++- src/Provider/en_US/Address.php | 18 ++++++++++++--- src/Provider/en_US/Company.php | 8 ++++++- src/Provider/en_US/Name.php | 10 +++++++-- test/documentor.php | 7 ++++++ test/test.php | 2 +- 12 files changed, 145 insertions(+), 15 deletions(-) create mode 100644 src/Documentor.php create mode 100644 test/documentor.php diff --git a/src/Documentor.php b/src/Documentor.php new file mode 100644 index 0000000000..b78c243c74 --- /dev/null +++ b/src/Documentor.php @@ -0,0 +1,40 @@ +generator = $generator; + } + + public function getFormatters() + { + $formatters = array(); + foreach ($this->generator->getProviders() as $provider) { + $providerClass = get_class($provider); + $formatters[$providerClass] = array(); + $refl = new \ReflectionObject($provider); + foreach ($refl->getMethods(\ReflectionMethod::IS_PUBLIC) as $reflmethod) { + if ($reflmethod->name == '__construct') { + continue; + } + $comment = $reflmethod->getDocComment(); + if (preg_match('/^\s+\*\s+@example\s+(.*)$/mi', $comment, $matches)) { + $example = $matches[1]; + } else { + $example = ''; + } + $formatters[$providerClass][$reflmethod->name] = $example; + } + ksort($formatters[$providerClass]); + } + ksort($formatters); + + return $formatters; + } + +} diff --git a/src/Generator.php b/src/Generator.php index c826f7b98d..aee09fbfb5 100644 --- a/src/Generator.php +++ b/src/Generator.php @@ -12,6 +12,11 @@ public function addProvider($providers) $this->providers[]= $providers; } + public function getProviders() + { + return $this->providers; + } + public function format($formatter, $arguments = array()) { return call_user_func_array($this->getFormatter($formatter), $arguments); diff --git a/src/Provider/Address.php b/src/Provider/Address.php index dc2d92ce07..14ea0d82fd 100644 --- a/src/Provider/Address.php +++ b/src/Provider/Address.php @@ -7,6 +7,7 @@ class Address extends \Faker\Provider\Base { protected static $citySuffix = array('Ville'); + protected static $streetSuffix = array('Street'); protected static $cityFormats = array( '{{firstName}}{{citySuffix}}', ); @@ -21,54 +22,80 @@ class Address extends \Faker\Provider\Base ); protected static $buildingNumber = array('##'); - protected static $streetSuffix = array('Street'); protected static $postcode = array('#####'); protected static $country = array(); + /** + * @example 'town' + */ public static function citySuffix() { return static::randomElement(static::$citySuffix); } + /** + * @example 'Avenue' + */ public static function streetSuffix() { return static::randomElement(static::$streetSuffix); } + /** + * @example '791' + */ public static function buildingNumber() { return static::numerify(static::randomElement(static::$buildingNumber)); } + /** + * @example 'Sashabury' + */ public function city() { $format = static::randomElement(static::$cityFormats); return $this->generator->parse($format); } - + + /** + * @example 'Crist Parks' + */ public function streetName() { $format = static::randomElement(static::$streetNameFormats); return $this->generator->parse($format); } - + + /** + * @example '791 Crist Parks' + */ public function streetAddress() { $format = static::randomElement(static::$streetAddressFormats); return $this->generator->parse($format); } + /** + * @example 86039-9874 + */ public static function postcode() { return static::numerify(static::randomElement(static::$postcode)); } + /** + * @example '791 Crist Parks, Sashabury, IL 86039-9874' + */ public function address() { $format = static::randomElement(static::$addressFormats); return $this->generator->parse($format); } + /** + * @example 'Japan' + */ public static function country() { return static::randomElement(static::$country); diff --git a/src/Provider/Company.php b/src/Provider/Company.php index f4ed6e8893..88ea3dde70 100644 --- a/src/Provider/Company.php +++ b/src/Provider/Company.php @@ -12,12 +12,18 @@ class Company extends \Faker\Provider\Base protected static $companySuffix = array('Ltd'); + /** + * @example 'Acme Ltd' + */ public function company() { $format = static::randomElement(static::$formats); return $this->generator->parse($format); } - + + /** + * @example 'Ltd' + */ public static function companySuffix() { return static::randomElement(static::$companySuffix); diff --git a/src/Provider/Lorem.php b/src/Provider/Lorem.php index 7228de3571..708a527f31 100644 --- a/src/Provider/Lorem.php +++ b/src/Provider/Lorem.php @@ -10,6 +10,9 @@ class Lorem extends \Faker\Provider\Base 'alias', 'consequatur', 'aut', 'perferendis', 'sit', 'voluptatem', 'accusantium', 'doloremque', 'aperiam', 'eaque', 'ipsa', 'quae', 'ab', 'illo', 'inventore', 'veritatis', 'et', 'quasi', 'architecto', 'beatae', 'vitae', 'dicta', 'sunt', 'explicabo', 'aspernatur', 'aut', 'odit', 'aut', 'fugit', 'sed', 'quia', 'consequuntur', 'magni', 'dolores', 'eos', 'qui', 'ratione', 'voluptatem', 'sequi', 'nesciunt', 'neque', 'dolorem', 'ipsum', 'quia', 'dolor', 'sit', 'amet', 'consectetur', 'adipisci', 'velit', 'sed', 'quia', 'non', 'numquam', 'eius', 'modi', 'tempora', 'incidunt', 'ut', 'labore', 'et', 'dolore', 'magnam', 'aliquam', 'quaerat', 'voluptatem', 'ut', 'enim', 'ad', 'minima', 'veniam', 'quis', 'nostrum', 'exercitationem', 'ullam', 'corporis', 'nemo', 'enim', 'ipsam', 'voluptatem', 'quia', 'voluptas', 'sit', 'suscipit', 'laboriosam', 'nisi', 'ut', 'aliquid', 'ex', 'ea', 'commodi', 'consequatur', 'quis', 'autem', 'vel', 'eum', 'iure', 'reprehenderit', 'qui', 'in', 'ea', 'voluptate', 'velit', 'esse', 'quam', 'nihil', 'molestiae', 'et', 'iusto', 'odio', 'dignissimos', 'ducimus', 'qui', 'blanditiis', 'praesentium', 'laudantium', 'totam', 'rem', 'voluptatum', 'deleniti', 'atque', 'corrupti', 'quos', 'dolores', 'et', 'quas', 'molestias', 'excepturi', 'sint', 'occaecati', 'cupiditate', 'non', 'provident', 'sed', 'ut', 'perspiciatis', 'unde', 'omnis', 'iste', 'natus', 'error', 'similique', 'sunt', 'in', 'culpa', 'qui', 'officia', 'deserunt', 'mollitia', 'animi', 'id', 'est', 'laborum', 'et', 'dolorum', 'fuga', 'et', 'harum', 'quidem', 'rerum', 'facilis', 'est', 'et', 'expedita', 'distinctio', 'nam', 'libero', 'tempore', 'cum', 'soluta', 'nobis', 'est', 'eligendi', 'optio', 'cumque', 'nihil', 'impedit', 'quo', 'porro', 'quisquam', 'est', 'qui', 'minus', 'id', 'quod', 'maxime', 'placeat', 'facere', 'possimus', 'omnis', 'voluptas', 'assumenda', 'est', 'omnis', 'dolor', 'repellendus', 'temporibus', 'autem', 'quibusdam', 'et', 'aut', 'consequatur', 'vel', 'illum', 'qui', 'dolorem', 'eum', 'fugiat', 'quo', 'voluptas', 'nulla', 'pariatur', 'at', 'vero', 'eos', 'et', 'accusamus', 'officiis', 'debitis', 'aut', 'rerum', 'necessitatibus', 'saepe', 'eveniet', 'ut', 'et', 'voluptates', 'repudiandae', 'sint', 'et', 'molestiae', 'non', 'recusandae', 'itaque', 'earum', 'rerum', 'hic', 'tenetur', 'a', 'sapiente', 'delectus', 'ut', 'aut', 'reiciendis', 'voluptatibus', 'maiores', 'doloribus', 'asperiores', 'repellat' ); + /** + * @example 'Lorem' + */ public static function word() { return static::randomElement(static::$wordList); @@ -18,6 +21,7 @@ public static function word() /** * Generate an array of random words * + * @example array('Lorem', 'ipsum', 'dolor') * @param integer $nb how many words to return * @return array */ @@ -33,6 +37,7 @@ public static function words($nb = 3) /** * Generate a random sentence * + * @example 'Lorem ipsum dolor sit amet.' * @param integer $nbWords around how many words the sentence should contain * @return string */ @@ -47,6 +52,7 @@ public function sentence($nbWords = 3) /** * Generate an array of sentences * + * @example array('Lorem ipsum dolor sit amet.', 'Consectetur adipisicing eli.') * @param integer $nb how many sentences to return * @return array */ @@ -62,6 +68,7 @@ public function sentences($nb = 3) /** * Generate a single paragraph * + * @example 'Sapiente sunt omnis. Ut pariatur ad autem ducimus et. Voluptas rem voluptas sint modi dolorem amet.' * @param integer $nbSentences around how many sentences the paragraph should contain * @return string */ @@ -73,6 +80,7 @@ public function paragraph($nbSentences = 3) /** * Generate an array of paragraphs * + * @example array($paragraph1, $paragraph2, $paragraph3) * @param integer $nb how many paragraphs to return * @return array */ @@ -88,6 +96,7 @@ public function paragraphs($nb) /** * Generate a long text string * + * @example 'Sapiente sunt omnis. Ut pariatur ad autem ducimus et. Voluptas rem voluptas sint modi dolorem amet.' * @param integer $nbParagraphs around how many paragraphs the text should contain * @return string */ diff --git a/src/Provider/Name.php b/src/Provider/Name.php index bcae2c8aaf..3bb5c21933 100644 --- a/src/Provider/Name.php +++ b/src/Provider/Name.php @@ -13,18 +13,27 @@ class Name extends \Faker\Provider\Base protected static $firstName = array('John', 'Jane'); protected static $lastName = array('Doe'); - + + /** + * @example 'John Doe' + */ public function name() { $format = static::randomElement(static::$formats); return $this->generator->parse($format); } - + + /** + * @example 'John' + */ public static function firstName() { return static::randomElement(static::$firstName); } - + + /** + * @example 'Doe' + */ public static function lastName() { return static::randomElement(static::$lastName); diff --git a/src/Provider/PhoneNumber.php b/src/Provider/PhoneNumber.php index c1a6e00fb6..3aa31edd77 100644 --- a/src/Provider/PhoneNumber.php +++ b/src/Provider/PhoneNumber.php @@ -7,7 +7,10 @@ class PhoneNumber extends \Faker\Provider\Base { protected static $formats = array('###-###-###'); - + + /** + * @example '555-123-546' + */ public static function phoneNumber() { return static::numerify(static::randomElement(static::$formats)); diff --git a/src/Provider/en_US/Address.php b/src/Provider/en_US/Address.php index c1e87fbdf1..b87a03fba3 100644 --- a/src/Provider/en_US/Address.php +++ b/src/Provider/en_US/Address.php @@ -64,22 +64,34 @@ class Address extends \Faker\Provider\Address "{{streetAddress}}\n{{city}}, {{stateAbbr}} {{postcode}}", ); protected static $secondaryAddressFormats = array('Apt. ###', 'Suite ###'); - + + /** + * @example 'East' + */ public static function cityPrefix() { return static::randomElement(static::$cityPrefix); } - + + /** + * @example 'Appt. 350' + */ public static function secondaryAddress() { return static::numerify(static::randomElement(static::$secondaryAddressFormats)); } + /** + * @example 'California' + */ public static function state() { return static::randomElement(static::$state); } - + + /** + * @example 'CA' + */ public static function stateAbbr() { return static::randomElement(static::$stateAbbr); diff --git a/src/Provider/en_US/Company.php b/src/Provider/en_US/Company.php index 4ccb8399db..9021dbeb09 100644 --- a/src/Provider/en_US/Company.php +++ b/src/Provider/en_US/Company.php @@ -38,6 +38,9 @@ class Company extends \Faker\Provider\Company protected static $companySuffix = array('Inc','and Sons','LLC','Group','PLC','Ltd'); + /** + * @example 'Robust full-range hub' + */ public function catchPhrase() { $result = array(); @@ -47,7 +50,10 @@ public function catchPhrase() return join($result, ' '); } - + + /** + * @example 'integrate extensible convergence' + */ public function bs() { $result = array(); diff --git a/src/Provider/en_US/Name.php b/src/Provider/en_US/Name.php index 0e782aca71..14372cb4d5 100644 --- a/src/Provider/en_US/Name.php +++ b/src/Provider/en_US/Name.php @@ -76,12 +76,18 @@ class Name extends \Faker\Provider\Name private static $prefix = array('Mr.','Mrs.','Ms.','Miss','Dr.'); private static $suffix = array('Jr.','Sr.','I','II','III','IV','V','MD','DDS','PhD','DVM'); - + + /** + * @example 'Mrs.' + */ public static function prefix() { return static::randomElement(static::$prefix); } - + + /** + * @example 'PhD' + */ public static function suffix() { return static::randomElement(static::$suffix); diff --git a/test/documentor.php b/test/documentor.php new file mode 100644 index 0000000000..b338abfc59 --- /dev/null +++ b/test/documentor.php @@ -0,0 +1,7 @@ +getFormatters()); diff --git a/test/test.php b/test/test.php index 0866a17f0f..cb3d2e5db7 100644 --- a/test/test.php +++ b/test/test.php @@ -33,4 +33,4 @@ - + \ No newline at end of file