PHPackages                             navisborealis/wonderwords-php - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Utility & Helpers](/categories/utility)
4. /
5. navisborealis/wonderwords-php

ActiveLibrary[Utility & Helpers](/categories/utility)

navisborealis/wonderwords-php
=============================

Generate random words and sentences with ease in PHP.

v1.0.0(2y ago)11.1kMITPHPPHP ^7.1 || ^8.0CI passing

Since Nov 7Pushed 1w ago1 watchersCompare

[ Source](https://github.com/navisborealis/wonderwords-php)[ Packagist](https://packagist.org/packages/navisborealis/wonderwords-php)[ Docs](https://github.com/navisborealis/wonderwords-php)[ RSS](/packages/navisborealis-wonderwords-php/feed)WikiDiscussions main Synced 2w ago

READMEChangelog (8)Dependencies (4)Versions (2)Used By (0)

[![Github Tests Action Status](https://github.com/navisborealis/wonderwords-php/actions/workflows/unit-tests.yml/badge.svg)](https://github.com/navisborealis/wonderwords-php/actions/workflows/unit-tests.yml)[![Latest Version on Packagist](https://camo.githubusercontent.com/513c4183ca24b4919b44d9882b348b73cd2a7e214df133f329bd9b76c0683fe0/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f6e61766973626f7265616c69732f776f6e646572776f7264732d7068702e737667)](https://packagist.org/packages/navisborealis/wonderwords-php)[![Total Downloads](https://camo.githubusercontent.com/bc6bf411a38ba1dd5e820fa56435860b4fd26669fb60445bfd42e111f5bc11a5/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f6e61766973626f7265616c69732f776f6e646572776f7264732d7068702e737667)](https://packagist.org/packages/navisborealis/wonderwords-php)[![PHP Version Require](https://camo.githubusercontent.com/af76a7b170fc9ca561989d223a053aafe6630dfaf7eb1d1ea1f59622eb61d0cc/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f7068702d762f6e61766973626f7265616c69732f776f6e646572776f7264732d7068702e737667)](https://packagist.org/packages/navisborealis/wonderwords-php)[![License](https://camo.githubusercontent.com/b052ec3579cf891272e3f9e3b2385b4b7cfaee6d9c5895cce786942b84c15827/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f6c2f6e61766973626f7265616c69732f776f6e646572776f7264732d7068702e737667)](https://packagist.org/packages/navisborealis/wonderwords-php)

Wonderwords PHP
===============

[](#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.

Table of Contents
-----------------

[](#table-of-contents)

- [Quick Start](#quick-start)
- [Installation](#installation)
- [Usage](#usage)
    - [Phrases](#phrases)
    - [Words](#words)
    - [Sentences](#sentences)
    - [Profanity Filtering](#profanity-filtering)
    - [FakerPHP Integration](#fakerphp-integration)
- [Contributing](#contributing)
- [Credits](#credits)
- [License](#license)

Installation
------------

[](#installation)

To install the package, run the following command:

```
composer require navisborealis/wonderwords-php
```

Quick Start
-----------

[](#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
-----

[](#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

[](#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](#changing-default-word-list).

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

#### Two-word phrase

[](#two-word-phrase)

```
use NavisBorealis\WonderwordsPhp\WonderWordsGenerator;

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

#### Custom separator

[](#custom-separator)

```
use NavisBorealis\WonderwordsPhp\WonderWordsGenerator;

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

#### Change adjective and noun count

[](#change-adjective-and-noun-count)

```
use NavisBorealis\WonderwordsPhp\WonderWordsGenerator;

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

#### Custom casing function

[](#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

[](#words)

#### Generating 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

[](#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

[](#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

[](#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

[](#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

[](#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

[](#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

[](#fakerphp-integration)

If you use [FakerPHP](https://github.com/FakerPHP/Faker), 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
-------

[](#credits)

Wonderwords PHP ports the Python `wonderwordsmodule` and uses these projects:

- [`wonderwordsmodule` for python](https://github.com/mrmaxguns/wonderwordsmodule) under the [MIT License](https://github.com/mrmaxguns/wonderwordsmodule/blob/master/LICENSE)
- `profanitylist.txt` from [RobertJGabriel/Google-profanity-words](https://github.com/RobertJGabriel/Google-profanity-words)under the [Apache-2.0 license](https://github.com/RobertJGabriel/Google-profanity-words/blob/master/LICENSE)
- [PhraseGenerator](https://github.com/samuelwilliams/PhraseGenerator) under the [MIT License](https://github.com/samuelwilliams/PhraseGenerator/blob/master/LICENSE)
- [word-generator](https://github.com/claudiodekker/word-generator/) under the [MIT license](https://github.com/claudiodekker/word-generator/blob/master/LICENSE.md)

Contributing
------------

[](#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](CONTRIBUTING.md) for details on running the test suite and code style fixer.

License
-------

[](#license)

[MIT](https://choosealicense.com/licenses/mit/)

###  Health Score

37

—

LowBetter than 81% of packages

Maintenance64

Regular maintenance activity

Popularity20

Limited adoption so far

Community7

Small or concentrated contributor base

Maturity48

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Unknown

Total

1

Last Release

1014d ago

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/1607439?v=4)[Piotr Grabski-Gradziński](/maintainers/piotrgradzinski)[@piotrgradzinski](https://github.com/piotrgradzinski)

---

Top Contributors

[![piotrgradzinski](https://avatars.githubusercontent.com/u/1607439?v=4)](https://github.com/piotrgradzinski "piotrgradzinski (35 commits)")

---

Tags

generatorwordnounadjectivephrase

###  Code Quality

TestsPHPUnit

Static AnalysisPHPStan

Code StylePHP CS Fixer

Type Coverage Yes

### Embed Badge

![Health badge](/badges/navisborealis-wonderwords-php/health.svg)

```
[![Health](https://phpackages.com/badges/navisborealis-wonderwords-php/health.svg)](https://phpackages.com/packages/navisborealis-wonderwords-php)
```

###  Alternatives

[symfony/maker-bundle

Symfony Maker helps you create empty commands, controllers, form classes, tests and more so you can forget about writing boilerplate code.

3.4k121.2M796](/packages/symfony-maker-bundle)[simplesoftwareio/simple-qrcode

Simple QrCode is a QR code generator made for Laravel.

2.9k31.6M124](/packages/simplesoftwareio-simple-qrcode)[claudiodekker/word-generator

Generates random words by combining adjectives and nouns

4065.8k2](/packages/claudiodekker-word-generator)[riimu/kit-phpencoder

Highly customizable alternative to var\_export for PHP code generation

718.4M38](/packages/riimu-kit-phpencoder)[butschster/cron-expression-generator

Cron expression generator

511.9M3](/packages/butschster-cron-expression-generator)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)