Skip to content

Commit d72d96e

Browse files
author
Bram Ceulemans
authored
Better documentation for base provider functionality (FakerPHP#10)
* wip: better documentation for base provider functionality * wip: better documentation for base provider functionality * wip: added docs for lorem formatter * Added documentation for date and time provider * Added documentation for Internet and User Agent providers * Added documentation for Payment provider * Added documentation for Color provider * Added documentation for File provider * Added documentation for Image provider * Added documentation for UUID provider * Added documentation for Barcode provider * Added documentation for Miscellaneous provider * Added documentation for Biased and HtmlLorem provider
1 parent e83ea2b commit d72d96e

17 files changed

+1490
-196
lines changed

docs/formatters.md

Lines changed: 5 additions & 188 deletions
Original file line numberDiff line numberDiff line change
@@ -1,38 +1,12 @@
1-
# Formatters
2-
Each of the generator properties (like `name`, `address`, and `lorem`) are called "formatters". A faker generator has many of them, packaged in "providers". Here is a list of the bundled formatters in the default locale.
1+
# Available Formatters
32

4-
### `Faker\Provider\Base`
3+
Each of the generator properties (like `name`, `address`, and `lorem`) are called "formatters". A faker generator has
4+
many of them, packaged in "providers". Here is a list of the bundled formatters in the default locale.
55

6-
```php
7-
randomDigit // 7
8-
randomDigitNot(5) // 0, 1, 2, 3, 4, 6, 7, 8, or 9
9-
randomDigitNotNull // 5
10-
randomNumber($nbDigits = NULL, $strict = false) // 79907610
11-
randomFloat($nbMaxDecimals = NULL, $min = 0, $max = NULL) // 48.8932
12-
numberBetween($min = 1000, $max = 9000) // 8567
13-
randomLetter // 'b'
14-
// returns randomly ordered subsequence of a provided array
15-
randomElements($array = ['a', 'b', 'c'], $count = 1) // ['c']
16-
randomElement($array = ['a', 'b', 'c']) // 'b'
17-
shuffle('hello, world') // 'rlo,h eoldlw'
18-
shuffle([1, 2, 3]) // [2, 1, 3]
19-
numerify('Hello ###') // 'Hello 609'
20-
lexify('Hello ???') // 'Hello wgt'
21-
bothify('Hello ##??') // 'Hello 42jz'
22-
asciify('Hello ***') // 'Hello R6+'
23-
regexify('[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,4}'); // sm0@y8k96a.ej
24-
```
25-
26-
### `Faker\Provider\Lorem`
6+
In all examples, a faker instance is made using the `en_US` default locale.
277

288
```php
29-
word // 'aut'
30-
words($nb = 3, $asText = false) // ['porro', 'sed', 'magni']
31-
sentence($nbWords = 6, $variableNbWords = true) // 'Sit vitae voluptas sint non voluptates.'
32-
sentences($nb = 3, $asText = false) // ['Optio quos qui illo error.', 'Laborum vero a officia id corporis.', 'Saepe provident esse hic eligendi.']
33-
paragraph($nbSentences = 3, $variableNbSentences = true) // 'Ut ab voluptas sed a nam. Sint autem inventore aut officia aut aut blanditiis. Ducimus eos odit amet et est ut eum.'
34-
paragraphs($nb = 3, $asText = false) // ['Quidem ut sunt et quidem est accusamus aut. Fuga est placeat rerum ut. Enim ex eveniet facere sunt.', 'Aut nam et eum architecto fugit repellendus illo. Qui ex esse veritatis.', 'Possimus omnis aut incidunt sunt. Asperiores incidunt iure sequi cum culpa rem. Rerum exercitationem est rem.']
35-
text($maxNbChars = 200) // 'Fuga totam reiciendis qui architecto fugiat nemo. Consequatur recusandae qui cupiditate eos quod.'
9+
$faker = \Faker\Factory::create();
3610
```
3711

3812
### `Faker\Provider\en_US\Person`
@@ -92,160 +66,3 @@ jobTitle // 'Cashier'
9266
```php
9367
realText($maxNbChars = 200, $indexSize = 2) // "And yet I wish you could manage it?) 'And what are they made of?' Alice asked in a shrill, passionate voice. 'Would YOU like cats if you were never even spoke to Time!' 'Perhaps not,' Alice replied."
9468
```
95-
96-
### `Faker\Provider\DateTime`
97-
98-
```php
99-
unixTime($max = 'now') // 58781813
100-
dateTime($max = 'now', $timezone = null) // DateTime('2008-04-25 08:37:17', 'UTC')
101-
dateTimeAD($max = 'now', $timezone = null) // DateTime('1800-04-29 20:38:49', 'Europe/Paris')
102-
iso8601($max = 'now') // '1978-12-09T10:10:29+0000'
103-
date($format = 'Y-m-d', $max = 'now') // '1979-06-09'
104-
time($format = 'H:i:s', $max = 'now') // '20:49:42'
105-
dateTimeBetween($startDate = '-30 years', $endDate = 'now', $timezone = null) // DateTime('2003-03-15 02:00:49', 'Africa/Lagos')
106-
dateTimeInInterval($startDate = '-30 years', $interval = '+ 5 days', $timezone = null) // DateTime('2003-03-15 02:00:49', 'Antartica/Vostok')
107-
dateTimeThisCentury($max = 'now', $timezone = null) // DateTime('1915-05-30 19:28:21', 'UTC')
108-
dateTimeThisDecade($max = 'now', $timezone = null) // DateTime('2007-05-29 22:30:48', 'Europe/Paris')
109-
dateTimeThisYear($max = 'now', $timezone = null) // DateTime('2011-02-27 20:52:14', 'Africa/Lagos')
110-
dateTimeThisMonth($max = 'now', $timezone = null) // DateTime('2011-10-23 13:46:23', 'Antarctica/Vostok')
111-
amPm($max = 'now') // 'pm'
112-
dayOfMonth($max = 'now') // '04'
113-
dayOfWeek($max = 'now') // 'Friday'
114-
month($max = 'now') // '06'
115-
monthName($max = 'now') // 'January'
116-
year($max = 'now') // '1993'
117-
century // 'VI'
118-
timezone // 'Europe/Paris'
119-
```
120-
121-
Methods accepting a `$timezone` argument default to `date_default_timezone_get()`. You can pass a custom timezone string to each method, or define a custom timezone for all time methods at once using `$faker::setDefaultTimezone($timezone)`.
122-
123-
### `Faker\Provider\Internet`
124-
125-
```php
126-
email // 'tkshlerin@collins.com'
127-
safeEmail // 'king.alford@example.org'
128-
freeEmail // 'bradley72@gmail.com'
129-
companyEmail // 'russel.durward@mcdermott.org'
130-
freeEmailDomain // 'yahoo.com'
131-
safeEmailDomain // 'example.org'
132-
userName // 'wade55'
133-
password // 'k&|X+a45*2['
134-
domainName // 'wolffdeckow.net'
135-
domainWord // 'feeney'
136-
tld // 'biz'
137-
url // 'http://www.skilesdonnelly.biz/aut-accusantium-ut-architecto-sit-et.html'
138-
slug // 'aut-repellat-commodi-vel-itaque-nihil-id-saepe-nostrum'
139-
ipv4 // '109.133.32.252'
140-
localIpv4 // '10.242.58.8'
141-
ipv6 // '8e65:933d:22ee:a232:f1c1:2741:1f10:117c'
142-
macAddress // '43:85:B7:08:10:CA'
143-
```
144-
145-
### `Faker\Provider\UserAgent`
146-
147-
```php
148-
userAgent // 'Mozilla/5.0 (Windows CE) AppleWebKit/5350 (KHTML, like Gecko) Chrome/13.0.888.0 Safari/5350'
149-
chrome // 'Mozilla/5.0 (Macintosh; PPC Mac OS X 10_6_5) AppleWebKit/5312 (KHTML, like Gecko) Chrome/14.0.894.0 Safari/5312'
150-
firefox // 'Mozilla/5.0 (X11; Linuxi686; rv:7.0) Gecko/20101231 Firefox/3.6'
151-
safari // 'Mozilla/5.0 (Macintosh; U; PPC Mac OS X 10_7_1 rv:3.0; en-US) AppleWebKit/534.11.3 (KHTML, like Gecko) Version/4.0 Safari/534.11.3'
152-
opera // 'Opera/8.25 (Windows NT 5.1; en-US) Presto/2.9.188 Version/10.00'
153-
internetExplorer // 'Mozilla/5.0 (compatible; MSIE 7.0; Windows 98; Win 9x 4.90; Trident/3.0)'
154-
```
155-
156-
### `Faker\Provider\Payment`
157-
158-
```php
159-
creditCardType // 'MasterCard'
160-
creditCardNumber // '4485480221084675'
161-
creditCardExpirationDate // 04/13
162-
creditCardExpirationDateString // '04/13'
163-
creditCardDetails // ['MasterCard', '4485480221084675', 'Aleksander Nowak', '04/13']
164-
// Generates a random IBAN. Set $countryCode to null for a random country
165-
iban($countryCode) // 'IT31A8497112740YZ575DJ28BP4'
166-
swiftBicNumber // 'RZTIAT22263'
167-
```
168-
169-
### `Faker\Provider\Color`
170-
171-
```php
172-
hexcolor // '#fa3cc2'
173-
rgbcolor // '0,255,122'
174-
rgbColorAsArray // [0, 255, 122]
175-
rgbCssColor // 'rgb(0, 255, 122)'
176-
safeColorName // 'fuchsia'
177-
colorName // 'Gainsbor'
178-
hslColor // '340,50,20'
179-
hslColorAsArray // [340, 50, 20]
180-
```
181-
182-
### `Faker\Provider\File`
183-
184-
```php
185-
fileExtension // 'avi'
186-
mimeType // 'video/x-msvideo'
187-
// Copy a random file from the source to the target directory and returns the fullpath or filename
188-
file($sourceDir = '/tmp', $targetDir = '/tmp') // '/path/to/targetDir/13b73edae8443990be1aa8f1a483bc27.jpg'
189-
file($sourceDir, $targetDir, false) // '13b73edae8443990be1aa8f1a483bc27.jpg'
190-
```
191-
192-
### `Faker\Provider\Image`
193-
194-
```php
195-
// Image generation provided by Placeholder (https://placeholder.com/)
196-
imageUrl($width = 640, $height = 480) // 'https://via.placeholder.com/640x480.png/000044?text=inventore'
197-
imageUrl($width, $height, 'cats') // 'https://via.placeholder.com/640x480.png/0022ff?text=cats+quia'
198-
imageUrl($width, $height, 'cats', true, 'Faker') // 'https://via.placeholder.com/640x480.png/00ddcc?text=cats+Faker+labore'
199-
imageUrl($width, $height, 'cats', true, 'Faker', true) // 'https://via.placeholder.com/640x480.png/CCCCCC?text=cats+Faker+sit' Monochrome image
200-
image($dir = '/tmp', $width = 640, $height = 480) // '/tmp/13b73edae8443990be1aa8f1a483bc27.jpg'
201-
image($dir, $width, $height, 'cats') // 'tmp/13b73edae8443990be1aa8f1a483bc27.jpg' it's a cat!
202-
image($dir, $width, $height, 'cats', false) // '13b73edae8443990be1aa8f1a483bc27.jpg' it's a filename without path
203-
image($dir, $width, $height, 'cats', true, false) // it's a no randomize images (default: `true`)
204-
image($dir, $width, $height, 'cats', true, true, 'Faker') // 'tmp/13b73edae8443990be1aa8f1a483bc27.jpg' it's a cat with 'Faker' text. Default, `null`.
205-
```
206-
207-
### `Faker\Provider\Uuid`
208-
209-
```php
210-
uuid // '7e57d004-2b97-0e7a-b45f-5387367791cd'
211-
```
212-
213-
### `Faker\Provider\Barcode`
214-
215-
```php
216-
ean13 // '4006381333931'
217-
ean8 // '73513537'
218-
isbn13 // '9790404436093'
219-
isbn10 // '4881416324'
220-
```
221-
222-
### `Faker\Provider\Miscellaneous`
223-
224-
```php
225-
boolean // false
226-
boolean($chanceOfGettingTrue = 50) // true
227-
md5 // 'de99a620c50f2990e87144735cd357e7'
228-
sha1 // 'f08e7f04ca1a413807ebc47551a40a20a0b4de5c'
229-
sha256 // '0061e4c60dac5c1d82db0135a42e00c89ae3a333e7c26485321f24348c7e98a5'
230-
locale // en_UK
231-
countryCode // UK
232-
languageCode // en
233-
currencyCode // EUR
234-
emoji // 😁
235-
```
236-
237-
### `Faker\Provider\Biased`
238-
239-
```php
240-
// get a random number between 10 and 20,
241-
// with more chances to be close to 20
242-
biasedNumberBetween($min = 10, $max = 20, $function = 'sqrt')
243-
```
244-
245-
### `Faker\Provider\HtmlLorem`
246-
247-
```php
248-
// Generate HTML document which is no more than 2 levels deep, and no more than 3 elements wide at any level.
249-
randomHtml(2, 3)
250-
// <html><head><title>Aut illo dolorem et accusantium eum.</title></head><body><form action="example.com" method="POST"><label for="username">sequi</label><input type="text" id="username"><label for="password">et</label><input type="password" id="password"></form><b>Id aut saepe non mollitia voluptas voluptas.</b><table><thead><tr><tr>Non consequatur.</tr><tr>Incidunt est.</tr><tr>Aut voluptatem.</tr><tr>Officia voluptas rerum quo.</tr><tr>Asperiores similique.</tr></tr></thead><tbody><tr><td>Sapiente dolorum dolorem sint laboriosam commodi qui.</td><td>Commodi nihil nesciunt eveniet quo repudiandae.</td><td>Voluptates explicabo numquam distinctio necessitatibus repellat.</td><td>Provident ut doloremque nam eum modi aspernatur.</td><td>Iusto inventore.</td></tr><tr><td>Animi nihil ratione id mollitia libero ipsa quia tempore.</td><td>Velit est officia et aut tenetur dolorem sed mollitia expedita.</td><td>Modi modi repudiandae pariatur voluptas rerum ea incidunt non molestiae eligendi eos deleniti.</td><td>Exercitationem voluptatibus dolor est iste quod molestiae.</td><td>Quia reiciendis.</td></tr><tr><td>Inventore impedit exercitationem voluptatibus rerum cupiditate.</td><td>Qui.</td><td>Aliquam.</td><td>Autem nihil aut et.</td><td>Dolor ut quia error.</td></tr><tr><td>Enim facilis iusto earum et minus rerum assumenda quis quia.</td><td>Reprehenderit ut sapiente occaecati voluptatum dolor voluptatem vitae qui velit.</td><td>Quod fugiat non.</td><td>Sunt nobis totam mollitia sed nesciunt est deleniti cumque.</td><td>Repudiandae quo.</td></tr><tr><td>Modi dicta libero quisquam doloremque qui autem.</td><td>Voluptatem aliquid saepe laudantium facere eos sunt dolor.</td><td>Est eos quis laboriosam officia expedita repellendus quia natus.</td><td>Et neque delectus quod fugit enim repudiandae qui.</td><td>Fugit soluta sit facilis facere repellat culpa magni voluptatem maiores tempora.</td></tr><tr><td>Enim dolores doloremque.</td><td>Assumenda voluptatem eum perferendis exercitationem.</td><td>Quasi in fugit deserunt ea perferendis sunt nemo consequatur dolorum soluta.</td><td>Maxime repellat qui numquam voluptatem est modi.</td><td>Alias rerum rerum hic hic eveniet.</td></tr><tr><td>Tempore voluptatem.</td><td>Eaque.</td><td>Et sit quas fugit iusto.</td><td>Nemo nihil rerum dignissimos et esse.</td><td>Repudiandae ipsum numquam.</td></tr><tr><td>Nemo sunt quia.</td><td>Sint tempore est neque ducimus harum sed.</td><td>Dicta placeat atque libero nihil.</td><td>Et qui aperiam temporibus facilis eum.</td><td>Ut dolores qui enim et maiores nesciunt.</td></tr><tr><td>Dolorum totam sint debitis saepe laborum.</td><td>Quidem corrupti ea.</td><td>Cum voluptas quod.</td><td>Possimus consequatur quasi dolorem ut et.</td><td>Et velit non hic labore repudiandae quis.</td></tr></tbody></table></body></html>
251-
```

docs/formatters/barcode.md

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
# Barcode
2+
3+
## `ean13`
4+
5+
Generate a random [EAN-13](https://en.wikipedia.org/wiki/International_Article_Number) barcode.
6+
7+
```php
8+
echo $faker->ean13();
9+
10+
// '5803352818140', '4142935337533'
11+
```
12+
13+
## `ean8`
14+
15+
Generate a random [EAN-8](https://en.wikipedia.org/wiki/International_Article_Number) barcode.
16+
17+
```php
18+
echo $faker->ean8();
19+
20+
// '30272446', '00484527'
21+
```
22+
23+
## `isbn10`
24+
25+
[ISBN-10]: <https://en.wikipedia.org/wiki/International_Standard_Book_Number#ISBN-10_check_digit_calculation>
26+
27+
Generate a random [ISBN-10][ISBN-10] compliant `string`.
28+
29+
```php
30+
echo $faker->isbn10();
31+
32+
// '4250151735', '8395066937'
33+
```
34+
35+
## `isbn13`
36+
37+
[ISBN-13]: <https://en.wikipedia.org/wiki/International_Standard_Book_Number#ISBN-13_check_digit_calculation>
38+
39+
Generate a random [ISBN-13][ISBN-13] compliant `string`.
40+
41+
```php
42+
echo $faker->isbn13();
43+
44+
// '9786881116078', '9785625528412'
45+
```

docs/formatters/biased.md

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
# Biased
2+
3+
## `biasedNumberBetween`
4+
5+
Generate a random `integer`, with a bias using a given function.
6+
7+
```php
8+
function biasedNumberBetween(int $min = 0, int $max = 100, string $function = 'sqrt'): int;
9+
```
10+
11+
Examples:
12+
13+
```php
14+
echo $faker->biasedNumberBetween(0, 20);
15+
16+
// 14, 18, 12
17+
18+
echo $faker->biasedNumberBetween(0, 20, 'log');
19+
20+
// 9, 4, 12
21+
```

docs/formatters/color.md

Lines changed: 101 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,101 @@
1+
# Color
2+
3+
## `hexColor`
4+
5+
Generate a random hex color.
6+
7+
```php
8+
$faker->hexColor();
9+
10+
// '#ccd578', '#fafa11', '#ea3781'
11+
```
12+
13+
## `safeHexColor`
14+
15+
Generate a random hex color, containing only 16 values per R, G and B.
16+
17+
```php
18+
$faker->safeHexColor();
19+
20+
// '#00eecc', '#00ff88', '#00aaee'
21+
```
22+
23+
## `rgbColorAsArray`
24+
25+
Generate a random RGB color, as an `array`.
26+
27+
```php
28+
$faker->rgbColorAsArray();
29+
30+
// [0 => 30, 1 => 22, 2 => 177], [0 => 150, 1 => 55, 2 => 34], [0 => 219, 1 => 253, 2 => 248]
31+
```
32+
33+
## `rgbColor`
34+
35+
Generate a comma-separated RGB color `string`.
36+
37+
```php
38+
$faker->rgbColor();
39+
40+
// '105,224,78', '97,249,98', '24,250,221'
41+
```
42+
43+
## `rgbCssColor`
44+
45+
Generate a CSS-friendly RGB color `string`.
46+
47+
```php
48+
$faker->rgbCssColor();
49+
50+
// 'rgb(9,110,101)', 'rgb(242,133,147)', 'rgb(124,64,0)'
51+
```
52+
53+
## `rgbaCssColor`
54+
55+
Generate a CSS-friendly RGBA (alpha channel) color `string`.
56+
57+
```php
58+
$faker->rgbaCssColor();
59+
60+
// 'rgba(179,65,209,1)', 'rgba(121,53,231,0.4)', 'rgba(161,239,152,0.9)'
61+
```
62+
63+
## `safeColorName`
64+
65+
Generate a CSS-friendly color name.
66+
67+
```php
68+
$faker->safeColorName();
69+
70+
// 'white', 'fuchsia', 'purple'
71+
```
72+
73+
## `colorName`
74+
75+
Generate a CSS-friendly color name.
76+
77+
```php
78+
$faker->colorName();
79+
80+
// 'SeaGreen', 'Crimson', 'DarkOliveGreen'
81+
```
82+
83+
## `hslColor`
84+
85+
Generate a random HSL color `string`.
86+
87+
```php
88+
$faker->hslColor();
89+
90+
// '87,10,25', '94,24,27', '207,68,84'
91+
```
92+
93+
## `hslColorAsArray`
94+
95+
Generate a random HSL color, as an `array`.
96+
97+
```php
98+
$faker->hslColorAsArray();
99+
100+
// [0 => 311, 1 => 84, 2 => 31], [0 => 283, 1 => 85, 2 => 49], [0 => 57, 1 => 48, 2 => 36]
101+
```

0 commit comments

Comments
 (0)