README

blizzard-faker is a collection of providers for Faker related to Blizzard Entertainment and its games.

Requirements

blizzard-faker requires PHP 7.0 or greater, and fzaninotto/faker 1.6 or greater.

Installation

You can install via composer:

composer install chrgriffin/blizzard-faker

Usage

You can add a Blizzard provider to Faker the same way you would add any other:

use Faker\Factory;
use ChrGriffin\BlizzardFaker\Names as BlizzardNames;

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

Once added, you can immediately make use of the provider methods as you normally would:

$name = $faker->name();

However, blizzard-faker offers additional filtering functionality:

$orcName = $faker
    ->blizzardNames() // this line prevents conflict with other Blizzard providers
    ->orc()
    ->name();

These filters are additive and chainable, meaning if you want a human or terran name from Diablo, Starcraft, or Warcraft, you can write:

$name = $faker
    ->blizzardNames()
    ->diablo()
    ->starcraft()
    ->warcraft()
    ->human()
    ->terran()
    ->name();

Providers

ChrGriffin\BlizzardFaker\Names

Valid Franchises

The Names provider is valid across all Blizzard franchises.

Available Methods and Arguments

• blizzardNames() : ChrGriffin\BlizzardFaker\Names (prevents conflict with other providers)
• firstName($gender, $franchise) : string
  • $gender: 'male', 'female', or null (any)
  • $franchise: a camelcased string of a valid franchise, or null (any)
• lastName($gender, $franchise) : string
  • $gender: 'male', 'female', or null (any)
  • $franchise: a camelcased string of a valid franchise, or null (any)
• fullName($gender, $franchise) : string
  • $gender: 'male', 'female', or null (any)
  • $franchise: a camelcased string of a valid franchise, or null (any)
• name($type, $gender, $franchise) : string
  • $type: 'first', 'last', 'full', or null ('full')
  • $gender: 'male', 'female', or null (any)
  • $franchise: a camelcased string of a valid franchise, or null (any)

ChrGriffin\BlizzardFaker\Monsters

Valid Franchises

The Monsters provider is only valid with the Diablo franchise.

Available Methods and Arguments

• blizzardMonsters() : ChrGriffin\BlizzardFaker\Monsters (prevents conflict with other providers)
• monster($franchise) : string
  • $franchise: a camelcased string of a valid franchise, or null (any)

Filters

After directly calling a provider, you can apply various filters to it before retrieving your data.

Note that not all filters are compatible with all providers, or with each other. Simply apply common sense and you should be fine.

If a filter is applied to an incompatible provider or pre-existing set of filters, it will throw a ChrGriffin\BlizzardFaker\Invalid{Filter}Exception. For example, the following code:

$faker
    ->blizzardNames()
    ->starcraft()
    ->orc();

will throw a ChrGriffin\BlizzardFaker\InvalidRaceException.

Franchise Filter

You can filter by the following franchises:

• ->diablo()
• ->hearthstone()
• ->heroesOfTheStorm()
• ->starcraft()
• ->warcraft()

Race Filter

You can filter by the following races:

• ->angel()
• ->bloodElf()
• ->demon()
• ->draenei()
• ->dragon()
• ->dwarf()
• ->elemental()
• ->forsaken() (has a lot of, though not 100%, overlap with undead)
• ->gnome()
• ->goblin()
• ->human()
• ->human()
• ->murloc()
• ->nephalem()
• ->nightElf()
• ->orc()
• ->pandaren()
• ->primalZerg()
• ->protoss()
• ->tauren()
• ->terran()
• ->troll()
• ->undead() (has a lot of, though not 100%, overlap with forsaken)
• ->worgen()
• ->xelNaga()
• ->zerg()

Roadmap

• include Overwatch franchise
• Class (ie Paladin, Warlock, etc.) provider for Diablo, Hearthstone, Warcraft
• Ability provider for all franchises
• Investigate feasibility of icon/image provider

Under the Hood

A cursory investigation of the src directory will reveal a distinctly different structure than Faker itself.

In most cases, rather than an individual provider containing a few arrays and selecting an element at random, instead it calls upon multiple - sometimes nested - DataProvider classes to provide an array of random data. This is to facilitate the enormous amount of filtering that is possible without overly impacting performance; rather than filtering a single enormous array containing data spanning Blizzard's entire product line, instead we can select only a single DataProvider and then apply our filtering to that.

In addition to the various ways data can be filtered, there are also built-in 'rules' for returning data for some of the providers:

• ChrGriffin\BlizzardFaker\Names:

  • Lore Character Names: Significant lore characters will not have their names broken up to be randomly assigned, instead, if returned, it will always be their full, unaltered name. For example, 'Garrosh' can never be assigned a random orcish surname - when retrieving full names, it will always be 'Garrosh Hellscream' (or simply 'Garrosh' if requesting only first names).
  • Lore Character Last Names: If a significant lore character has a last name also carried by other characters - for example, a family name, such as 'Cain', or tribe name, such as 'Bloodhoof' - then the last name can be randomly assigned like any other. If they are the only instance of such a name, then the above rule is observed.
  • Races Without Surnames: There are some examples of races without surnames, such as Draenei or Protoss. In these cases, their individual name is considered a valid value for either full names or first names: so you may see 'Tassadar' when requesting either first or full names. In the case of significant lore characters with a relevant title, the character plus their title can be returned as the full name (for example, 'Hierarch Artanis', or 'Tyrael, Archangel of Justice'.)

• ChrGriffin\BlizzardFaker\Monsters:

  • Monster Name Generation: This provider follows the format of Diablo 2's random named monsters: a random prefix, suffix, and apellation will be combined to create a monster name.