README

Wonderwords PHP

Generate random words, phrases, and grammatically correct english sentences in PHP. Perfect for seeding databases with realistic test data, generating memorable usernames, providing default names or URL slugs for new entities (projects, workspaces, groups), or building randomized bots.

Quick Start
Installation
Usage
Contributing
Credits
License

Installation

To install the package, run the following command:

composer require navisborealis/wonderwords-php

Quick Start

use NavisBorealis\WonderwordsPhp\WonderWordsGenerator;
use NavisBorealis\WonderwordsPhp\WonderWordsSentence;

// 1. Generate memorable usernames (e.g., AzureCheetah)
$username = ucfirst(WonderWordsGenerator::color()) . ucfirst(WonderWordsGenerator::animal());

// 2. Provide default names for new entities like projects or workspaces (e.g., "Blushing Inspection Project")
$projectName = WonderWordsGenerator::phrase() . ' Project';

// 3. Generate grammatically correct sentences (e.g., "A fluffy cake quickly plays golf.")
$sentence = WonderWordsSentence::simpleSentence();

// 4. Create random URL slugs (e.g., "blushing-inspection")
$slug = WonderWordsGenerator::phrase('-', 1, 1, 'strtolower');

Usage

Generate:

words - adjectives, nouns, verbs, adverbs, animals, colors, names, and tech terms
phrases - 1+ adjective and 1+ noun, like Blushing Inspection
sentences - grammatically correct simple and bare-bone sentences

Phrases

The phrase structure is adjective noun. You can change:

string separator, default ,
number of adjectives and nouns, default 1,
function used to modify the letters case, default ucwords().

To use custom words, see Changing default word list.

public static function phrase(
    string $separator = ' ',
    int $numAdjectives = 1,
    int $numNouns = 1,
    ?callable $stringCaseFunction = null
): string

Two-word phrase

use NavisBorealis\WonderwordsPhp\WonderWordsGenerator;

echo WonderWordsGenerator::phrase(); // Output: Blushing Inspection

Custom separator

use NavisBorealis\WonderwordsPhp\WonderWordsGenerator;

echo WonderWordsGenerator::phrase('-'); // Output: Blushing-Inspection

Change adjective and noun count

use NavisBorealis\WonderwordsPhp\WonderWordsGenerator;

echo WonderWordsGenerator::phrase(' ', 2, 3); // Output: Receptive Weary Disease Motive Vegetarian

Custom casing function

use NavisBorealis\WonderwordsPhp\WonderWordsGenerator;

echo WonderWordsGenerator::phrase(' ', 1, 1, 'strtoupper'); // Output: BLUSHING INSPECTION

use NavisBorealis\WonderwordsPhp\WonderWordsGenerator;

echo WonderWordsGenerator::phrase(' ', 1, 1, function ($phrase) {
    return ucfirst($phrase);
}); // Output: Blushing inspection

Words

Generating words

Generate random words using the WonderWordsGenerator helper methods, or by interacting with the specific dictionary classes directly:

use NavisBorealis\WonderwordsPhp\WonderWordsGenerator;

echo WonderWordsGenerator::animal(); // Output: cheetah
echo WonderWordsGenerator::color(); // Output: azure
echo WonderWordsGenerator::firstName(); // Output: Alice
echo WonderWordsGenerator::techTerm(); // Output: algorithm

Username Generation

Combining specific categories like Colors and Animals is perfect for generating memorable, anonymous usernames or default avatars:

use NavisBorealis\WonderwordsPhp\WonderWordsGenerator;

$username = ucfirst(WonderWordsGenerator::color()) . ucfirst(WonderWordsGenerator::animal());
echo $username; // Output: CrimsonPanther

Generating multiple words

To generate an array of multiple words, use the underlying dictionary classes:

use NavisBorealis\WonderwordsPhp\Words\Adjective;

$words = Adjective::randomWords(5); // ["innate", "noiseless", "screeching", "sloppy", "squeamish"]

Changing default word list

Change the default word list per category:

use NavisBorealis\WonderwordsPhp\WonderWordsGenerator;
use NavisBorealis\WonderwordsPhp\Words\Adjective;

Adjective::setWordList(['customadjective1', 'customadjective2']);

echo WonderWordsGenerator::phrase(); // Output: Customadjective2 Inspection

Reset the word list:

use NavisBorealis\WonderwordsPhp\WonderWordsGenerator;
use NavisBorealis\WonderwordsPhp\Words\Adjective;

Adjective::setWordList(['customadjective1', 'customadjective2']);

echo WonderWordsGenerator::phrase(); // Output: Customadjective2 Inspection

Adjective::reset();

echo WonderWordsGenerator::phrase(); // Output: Scientific Inspection

Advanced Filtering

Filter words by length, starting/ending letters, or regex. Pass an options array to randomWord() or randomWords():

use NavisBorealis\WonderwordsPhp\Words\Noun;

// Generate a 5-letter noun starting with 'a' and ending with 'e'
echo Noun::randomWord([
    'starts_with' => 'a',
    'ends_with' => 'e',
    'word_min_length' => 5,
    'word_max_length' => 5
]); // Output: apple

// Generate 3 words matching a custom regex
$words = Noun::randomWords(3, [
    'regex' => '/^b.*y$/'
]); // Output: ["blueberry", "butterfly", "balcony"]

Sentences

Use WonderWordsSentence to generate grammatically sound sentences containing randomly generated adjectives, nouns, adverbs, and verbs.

use NavisBorealis\WonderwordsPhp\WonderWordsSentence;

// Example: "A fluffy cake quickly plays golf."
echo WonderWordsSentence::simpleSentence(); 

// Example: "A fluffy cat quickly runs."
echo WonderWordsSentence::bareBoneSentence();

You can also pass filtering options (just like randomWord) directly into sentence generators:

// Generate a sentence where the nouns start with 'a' and the verb is exactly 3 letters long
echo WonderWordsSentence::simpleSentence(
    ['starts_with' => 'a'], 
    ['word_min_length' => 3, 'word_max_length' => 3]
);

Profanity Filtering

Check strings for profanity or filter out profane words from arrays:

use NavisBorealis\WonderwordsPhp\Words\Profanity;

// Check a specific string
$isBad = Profanity::isProfanity("piss"); // true

// Filter an array of words
$cleanArray = Profanity::filterProfanity(['apple', 'orange', 'piss']);
// Output: ['apple', 'orange']

FakerPHP Integration

If you use FakerPHP, you can register WonderWords as a custom provider to generate words, phrases, and sentences directly from your $faker instance.

use Faker\Factory;
use NavisBorealis\WonderwordsPhp\Faker\WonderWordsProvider;

$faker = Factory::create();
$faker->addProvider(new WonderWordsProvider($faker));

// Generate words
echo $faker->wonderWordsAdjective(); // e.g., "blushing"
echo $faker->wonderWordsNoun();      // e.g., "inspection"
echo $faker->wonderWordsColor();     // e.g., "azure"

// Generate phrases and sentences
echo $faker->wonderWordsPhrase();           // e.g., "Blushing Inspection"
echo $faker->wonderWordsSimpleSentence();   // e.g., "A fluffy cake quickly plays golf."

Available methods:

wonderWordsAdjective(array $options = [])
wonderWordsAdverb(array $options = [])
wonderWordsAnimal(array $options = [])
wonderWordsColor(array $options = [])
wonderWordsName(array $options = [])
wonderWordsFirstName(array $options = [])
wonderWordsLastName(array $options = [])
wonderWordsNoun(array $options = [])
wonderWordsProfanity(array $options = [])
wonderWordsTechTerm(array $options = [])
wonderWordsVerb(array $options = [])
wonderWordsPhrase(string $separator = ' ', int $numAdjectives = 1, int $numNouns = 1, ?callable $stringCaseFunction = null)
wonderWordsBareBoneSentence(array $nounOptions = [], array $verbOptions = [], array $adjectiveOptions = [], array $adverbOptions = [])
wonderWordsSimpleSentence(array $nounOptions = [], array $verbOptions = [], array $adjectiveOptions = [], array $adverbOptions = [])

Credits

Wonderwords PHP ports the Python wonderwordsmodule and uses these projects:

wonderwordsmodule for python under the MIT License
profanitylist.txt from RobertJGabriel/Google-profanity-words under the Apache-2.0 license
PhraseGenerator under the MIT License
word-generator under the MIT license

Contributing

Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change. Please make sure to update tests as appropriate.

See CONTRIBUTING.md for details on running the test suite and code style fixer.

License

MIT

navisborealis / wonderwords-php

Maintainers

Package info

Statistics

Security