README

生成适用于您的PHP应用程序需求的定制假数据。

目录

• 入门
  • 需求
  • 亮点
• 文档
  • 创建种子
  • 添加种子器
  • 种子
  • 本地化
  • 随机种子
  • 种子器
    • 资源种子器
    • DateTime种子器
    • 用户种子器
    • 创建自定义种子器
  • 资源
    • 创建资源
    • 添加资源
    • 筛选资源
    • 文件资源
    • 获取资源和项目
  • 文件资源
    • 创建文件资源
    • 目录结构
    • 支持的文件
    • 支持其他文件
  • 静态种子器
    • Str种子器
    • Lorem种子器
    • Num种子器
    • Json种子器
    • Arr种子器
• 致谢

入门

使用以下命令添加运行Seeder服务项目的最新版本。

composer require tobento/service-seeder

需求

• PHP 8.0或更高版本

亮点

• 框架无关，适用于任何项目
• 解耦设计
• 灵活管理您的资源数据以适应您的应用程序
• 易于扩展

文档

仅用于种子。它不会生成具有密码学安全性的字符串和数字，因为它更注重速度。

创建种子

use Tobento\Service\Seeder\Seed;
use Tobento\Service\Seeder\Resources;
use Tobento\Service\Seeder\SeedInterface;

$seed = new Seed(
    resources: new Resources(),
    locale: 'en',
    localeFallbacks: ['de' => 'en'],
    localeMapping: ['de' => 'de-CH'],
);

var_dump($seed instanceof SeedInterface);
// bool(true)

添加种子器

use Tobento\Service\Seeder\UserSeeder;

$seed->addSeeder(
    name: 'user',
    seeder: new UserSeeder($seed)
);

添加可调用的种子器

use Tobento\Service\Seeder\SeedInterface;
use Tobento\Service\Seeder\Lorem;

$seed->addCallableSeeder(
    method: 'word',
    seeder: function(SeedInterface $seed, null|string|array $locale, array $params): string {
        return Lorem::word(...$params);
    }
);

$words = $seed->word(number: 2);

使用资源项添加可调用的种子器

use Tobento\Service\Seeder\Seed;
use Tobento\Service\Seeder\Resources;
use Tobento\Service\Seeder\Resource;
use Tobento\Service\Seeder\SeedInterface;
use Tobento\Service\Seeder\Arr;
use Tobento\Service\Seeder\Lorem;

$seed = new Seed(
    new Resources(
        new Resource('colors', 'en', [
            'blue', 'red', 'green', 'yellow', 'pink',
        ]),
        new Resource('colors', 'de', [
            'blau', 'rot', 'grün', 'gelb', 'pink',
        ]),        
    ),
);

$seed->addCallableSeeder(
    method: 'color',
    seeder: function(SeedInterface $seed, null|string|array $locale, array $params): string {
    
        $colors = $seed->getItems('colors', $locale);
        
        if (!empty($colors)) {
            return Arr::item($colors);
        }
        
        return ucfirst(Lorem::word(number: 1));
    }
);

// default locale used:
$color = $seed->color();

// specific locale:
$color = $seed->locale('de')->color();

// specific locales:
$color = $seed->locale(['en', 'de'])->color();

// all locales:
$color = $seed->locale([])->color();

种子

种子

Seed::class会动态调用种子方法来种子数据。如果没有找到支持调用方法的种子器，则抛出SeedMethodCallException。

use Tobento\Service\Seeder\Seed;
use Tobento\Service\Seeder\Resources;
use Tobento\Service\Seeder\Resource;
use Tobento\Service\Seeder\ResourceSeeder;
use Tobento\Service\Seeder\SeedMethodCallException;

$seed = new Seed(
    new Resources(
        new Resource('countries', 'en', [
            'Usa', 'Switzerland', 'Germany',
        ]),
    ),
);

$seed->addSeeder('resource', new ResourceSeeder($seed));

try {
    $value = $seed->itemFrom(resource: 'countries');    
    var_dump($value);
    // string(11) "Switzerland"
} catch (SeedMethodCallException $e) {
    // handle
}

种子器

您可以使用 seeder 方法返回添加的种子器。

use Tobento\Service\Seeder\Seed;
use Tobento\Service\Seeder\Resources;
use Tobento\Service\Seeder\Resource;
use Tobento\Service\Seeder\ResourceSeeder;
use Tobento\Service\Seeder\SeederInterface;
use Tobento\Service\Seeder\SeederNotFoundException;

$seed = new Seed(new Resources());

$seed->addSeeder('resource', new ResourceSeeder($seed));

try {
    var_dump($seed->seeder('resource') instanceof SeederInterface);
    // bool(true)
} catch (SeederNotFoundException $e) {
    // handle
}

资源

您可以使用 resources 方法返回资源。

use Tobento\Service\Seeder\Seed;
use Tobento\Service\Seeder\Resources;
use Tobento\Service\Seeder\ResourcesInterface;

$seed = new Seed(new Resources());

var_dump($seed->resources() instanceof ResourcesInterface);
// bool(true)

getItems

您可以使用 getItems 方法返回指定资源的项目。如果指定了多个区域，它将合并项目。

use Tobento\Service\Seeder\Seed;
use Tobento\Service\Seeder\Resources;
use Tobento\Service\Seeder\Resource;

$seed = new Seed(
    new Resources(
        new Resource('countries', 'en', [
            'Usa', 'Switzerland', 'Germany',
        ]),
    ),
);

$items = $seed->getItems(
    name: 'countries',
    locale: 'en', // null|string|array
);

var_dump($items);
// array(3) { [0]=> string(3) "Usa" [1]=> string(11) "Switzerland" [2]=> string(7) "Germany" }

// default locale used:
$items = $seed->getItems('countries');

// specific locale:
$items = $seed->getItems('countries', 'en');

// specific locales:
$items = $seed->getItems('countries', ['en']);

// all locales:
$items = $seed->getItems('countries', []);

本地化

use Tobento\Service\Seeder\Seed;
use Tobento\Service\Seeder\Resources;

$seed = new Seed(
    resources: new Resources(),
    locale: 'en',
    localeFallbacks: ['de' => 'en'],
    localeMapping: ['de' => 'de-CH'],
);

// set the default locale:
$seed->setLocale('de');

// get the default locale:
var_dump($seed->getLocale());
// string(2) "de"

// set the locale fallbacks:
$seed->setLocaleFallbacks(['de' => 'en']);

// get the locale fallbacks:
var_dump($seed->getLocaleFallbacks());
// array(1) { ["de"]=> string(2) "en" }

// set the locale mapping:
$seed->setLocaleMapping(['de' => 'de-CH']);

// get the locale mapping:
var_dump($seed->getLocaleMapping());
// array(1) { ["de"]=> string(5) "de-CH" }

种子

在调用种子器方法之前，使用 locale 方法以从特定区域（s）的资源中种子数据。

use Tobento\Service\Seeder\Seed;
use Tobento\Service\Seeder\Resources;
use Tobento\Service\Seeder\Resource;
use Tobento\Service\Seeder\ResourceSeeder;

$seed = new Seed(
    new Resources(
        new Resource('countries', 'en', [
            'Usa', 'Switzerland', 'Germany',
        ]),
        new Resource('countries', 'de', [
            'Usa', 'Schweiz', 'Deutschland',
        ]),
    ),
);

$seed->addSeeder('resource', new ResourceSeeder($seed));

// default locale used:
var_dump($seed->itemFrom(resource: 'countries'));
// string(7) "Germany"

// specific locale:
var_dump($seed->locale('de')->itemFrom('countries'));
// string(7) "Schweiz"

// specific locales:
var_dump($seed->locale(['en', 'de'])->itemFrom('countries'));
// string(11) "Deutschland"

// all locales:
var_dump($seed->locale([])->itemFrom('countries'));
// string(3) "Usa"

随机种子

在调用种子器方法之前，使用 random 方法以按其概率百分比随机种子指定值。

use Tobento\Service\Seeder\Seed;
use Tobento\Service\Seeder\Resources;
use Tobento\Service\Seeder\Resource;
use Tobento\Service\Seeder\ResourceSeeder;

$seed = new Seed(
    new Resources(
        new Resource('countries', 'en', [
            'Usa', 'Switzerland', 'Germany',
        ]),
    ),
);

$seed->addSeeder('resource', new ResourceSeeder($seed));

$value = $seed->random(
    value: null,
    probability: 50 // between 0 (always get false) and 100 (always get true)
)->itemFrom(resource: 'countries');

var_dump($value);
// NULL

种子器

资源种子器

资源种子器提供了使用资源项种子数据的便捷方法。如果没有为方法提供资源，则根据方法回退到Lorem Seeder单词。

use Tobento\Service\Seeder\Seed;
use Tobento\Service\Seeder\Resources;
use Tobento\Service\Seeder\Resource;
use Tobento\Service\Seeder\ResourceSeeder;

$seed = new Seed(
    new Resources(
        new Resource('countries', 'en', [
            'Usa', 'Switzerland', 'Germany',
        ]),
        new Resource('countries', 'de', [
            'Usa', 'Schweiz', 'Deutschland',
        ]),
    ),
);

$seed->addSeeder('resource', new ResourceSeeder($seed));

// default locale used:
var_dump($seed->itemFrom(resource: 'countries'));
// string(7) "Germany"

// specific locale:
var_dump($seed->locale('de')->itemFrom('countries'));
// string(7) "Schweiz"

// specific locales:
var_dump($seed->locale(['en', 'de'])->itemFrom('countries'));
// string(11) "Deutschland"

// all locales:
var_dump($seed->locale([])->itemFrom('countries'));
// string(3) "Usa"

可用方法

DateTime种子器

DateTime种子器提供了种子DateTime数据的便捷方法。有关DateFormatter::class的更多信息，请访问Dater Service。

use Tobento\Service\Seeder\Seed;
use Tobento\Service\Seeder\Resources;
use Tobento\Service\Seeder\DateTimeSeeder;
use Tobento\Service\Dater\DateFormatter;

$seed = new Seed(new Resources());

$df = new DateFormatter(
    locale: $seed->getLocale()
);

$seed->addSeeder('dateTime', new DateTimeSeeder($df));

$dateTime = $seed->dateTime(from: '-30 years', to: 'now');

var_dump($dateTime);
// object(DateTimeImmutable)#8 (3) { ["date"]=> string(26) "2015-11-29 14:55:24.000000" ["timezone_type"]=> int(3) ["timezone"]=> string(13) "Europe/Berlin" }

var_dump($seed->locale('de')->month(3, 6, 'MMM'));
// string(5) "März"

var_dump($seed->locale(['de', 'fr'])->weekday(1, 7, 'EEEE'));
// string(7) "Sonntag"

可用方法

用户种子器

用户种子器提供了种子用户数据的便捷方法。如果没有为方法提供资源，则根据方法回退到Lorem Seeder单词。

use Tobento\Service\Seeder\Seed;
use Tobento\Service\Seeder\Resources;
use Tobento\Service\Seeder\Resource;
use Tobento\Service\Seeder\UserSeeder;

$seed = new Seed(
    new Resources(
        new Resource('countries', 'en', [
            'Usa', 'Switzerland', 'Germany',
        ]),
        new Resource('countries', 'de', [
            'Usa', 'Schweiz', 'Deutschland',
        ]),
    ),
);

$seed->addSeeder('user', new UserSeeder($seed));

// default locale used:
var_dump($seed->country());
// string(7) "Germany"

// specific locale:
var_dump($seed->locale('de')->country());
// string(7) "Schweiz"

// specific locales:
var_dump($seed->locale(['en', 'de'])->country());
// string(11) "Deutschland"

// all locales:
var_dump($seed->locale([])->country());
// string(3) "Usa"

可用方法

创建自定义种子器

您可以为您的应用程序创建自定义种子器。

use Tobento\Service\Seeder\Seeder;
use Tobento\Service\Seeder\Seed;
use Tobento\Service\Seeder\SeedInterface;
use Tobento\Service\Seeder\Resources;
use Tobento\Service\Seeder\Arr;
use Tobento\Service\Seeder\Lorem;

class CustomSeeder extends Seeder
{
    /**
     * Create a new CustomSeeder.
     *
     * @param SeedInterface $seed
     */    
    public function __construct(
        protected SeedInterface $seed,
    ) {}
    
    /**
     * Returns the seed method names the seeder provides.
     *
     * @return array<int, string>
     */    
    public function seeds(): array
    {
        return [
            'paymentMethod',
        ];
    }

    /**
     * Returns a randomly selected item from the specified resource items.
     *
     * @return mixed
     */
    public function paymentMethod(): mixed
    {
        // get items from resource.
        $items = $this->seed->getItems('payment_methods', $this->locale);

        if (empty($items)) {
            // if no payment_methods resource is defined fallback to:
            $items = ['invoice', 'creditcard', 'paypal'];
        }
        
        return Arr::item($items);
    }
}

$seed = new Seed(new Resources());
$seed->addSeeder('custom', new CustomSeeder($seed));

var_dump($seed->paymentMethod());
// string(6) "paypal"

资源

创建资源

use Tobento\Service\Seeder\Resources;
use Tobento\Service\Seeder\ResourcesInterface;
use Tobento\Service\Seeder\Resource;

$resources = new Resources(
    new Resource(
        name: 'colors', 
        locale: 'en', 
        items: ['blue', 'red']
    ),
);

var_dump($resources instanceof ResourcesInterface);
// bool(true)

添加资源

您可以通过使用 add 方法添加资源

添加资源

use Tobento\Service\Seeder\Resources;
use Tobento\Service\Seeder\Resource;

$resources = new Resources();

$resources->add(new Resource('colors', 'en', [
    'red', 'blue',
]));

添加资源

use Tobento\Service\Seeder\Resources;
use Tobento\Service\Seeder\Resource;

$resources = new Resources();

$resources->add(new Resources(
    new Resource('colors', 'en', [
        'red', 'blue',
    ]),
));

筛选资源

您可以使用返回新实例的筛选方法。

筛选

use Tobento\Service\Seeder\Resources;
use Tobento\Service\Seeder\Resource;
use Tobento\Service\Seeder\ResourceInterface;

$resources = new Resources(
    new Resource(
        name: 'colors', 
        locale: 'en', 
        items: ['blue', 'red']
    ),
    new Resource(
        name: 'colors', 
        locale: 'de', 
        items: ['blau', 'rot']
    ),
);

// filter by locale:
$resources = $resources->filter(
    fn(ResourceInterface $r): bool => $r->locale() === 'de'
);

区域

use Tobento\Service\Seeder\Resources;
use Tobento\Service\Seeder\Resource;

$resources = new Resources(
    new Resource(
        name: 'colors', 
        locale: 'en', 
        items: ['blue', 'red']
    ),
    new Resource(
        name: 'colors', 
        locale: 'de', 
        items: ['blau', 'rot']
    ),
);

// filter by locale:
$resources = $resources->locale('en');

区域

use Tobento\Service\Seeder\Resources;
use Tobento\Service\Seeder\Resource;

$resources = new Resources(
    new Resource(
        name: 'colors', 
        locale: 'en', 
        items: ['blue', 'red']
    ),
    new Resource(
        name: 'colors', 
        locale: 'de', 
        items: ['blau', 'rot']
    ),
);

// filter by locales:
$resources = $resources->locales(['en', 'de']);

名称

use Tobento\Service\Seeder\Resources;
use Tobento\Service\Seeder\Resource;

$resources = new Resources(
    new Resource(
        name: 'colors', 
        locale: 'en', 
        items: ['blue', 'red']
    ),
    new Resource(
        name: 'colors', 
        locale: 'de', 
        items: ['blau', 'rot']
    ),
);

// filter by name:
$resources = $resources->name('colors');

文件资源

您可以使用文件资源从json或php文件加载数据。

use Tobento\Service\Seeder\ResourceFile;
use Tobento\Service\Seeder\ResourceInterface;

$resource = new ResourceFile(
    file: __DIR__.'/seeder/countries.json', 
    locale: 'en', 
    resourceName: 'countries'
);

var_dump($resource instanceof ResourceInterface);
bool(true)

支持的文件是json和php

json

["Switzerland", "Germany"]

php

return ['Switzerland', 'Germany'];

获取资源和项目

全部

use Tobento\Service\Seeder\Resources;
use Tobento\Service\Seeder\Resource;
use Tobento\Service\Seeder\ResourceInterface;

$resources = new Resources(
    new Resource(
        name: 'colors', 
        locale: 'en', 
        items: ['blue', 'red']
    ),
);

foreach($resources->all() as $resource) {
    var_dump($resource instanceof ResourceInterface);
    // bool(true)
    
    var_dump($resource->name());
    // string(6) "colors"
    
    var_dump($resource->locale());
    // string(2) "en"
    
    var_dump($resource->items());
    // array(2) { [0]=> string(4) "blue" [1]=> string(3) "red" }
}

项目

use Tobento\Service\Seeder\Resources;
use Tobento\Service\Seeder\Resource;

$resources = new Resources(
    new Resource(
        name: 'colors', 
        locale: 'en', 
        items: ['blue', 'red']
    ),
);

$items = $resources->locale('en')->items();

var_dump($items);
// array(2) { [0]=> string(4) "blue" [1]=> string(3) "red" }

⚠️ 如果您已经添加了（子或延迟）资源，必须在调用 all() 或 items() 方法之前调用 locale() 或 locales()，否则它们将无法加载。

foreach($resources->locale('en')->all() as $resource) {
    var_dump($resource instanceof ResourceInterface);
    // bool(true)
}

文件资源

您可以使用文件资源从目录中加载资源数据。

创建文件资源

use Tobento\Service\Seeder\FilesResources;
use Tobento\Service\Dir\Dirs;
use Tobento\Service\Seeder\ResourcesInterface;

$resources = new FilesResources(
    (new Dirs())->dir(dir: 'private/seeder/')
);

var_dump($resources instanceof ResourcesInterface);
// bool(true)

目录结构

private/
    seeder/
        en/
            countries.json
            firstnamesFemale.json
            firstnamesMale.php
        de-CH/
            countries.json
            firstnamesFemale.json
            firstnamesMale.php

支持的文件

目前支持文件格式为 json 和 php。

json

["Switzerland", "Germany"]

php

return ['Switzerland', 'Germany'];

支持其他文件

您可以通过提供自己的资源工厂来支持其他文件格式。

use Tobento\Service\Seeder\FilesResources;
use Tobento\Service\Dir\Dirs;
use Tobento\Service\Seeder\ResourceFactory;
use Tobento\Service\Seeder\ResourceInterface;
use Tobento\Service\Filesystem\File;

class CustomResourceFactory extends ResourceFactory
{
    /**
     * Create a new Resource from file.
     *
     * @param string|File $file
     * @param string $locale
     * @return ResourceInterface
     */    
    public function createResourceFromFile(
        string|File $file,
        string $locale,
    ): ResourceInterface {
        
        // Create your custom resource for the specific file extension
        
        // Otherwise use parent
        return parent::createResourceFromFile($file, $locale);
    }
}

$resources = new FilesResources(
    (new Dirs())->dir(dir: 'private/seeder/'),
    new CustomResourceFactory()
);

静态种子器

Str种子器

use Tobento\Service\Seeder\Str;

$string = Str::string(length: 10);

可用方法

替换

use Tobento\Service\Seeder\Str;
use Tobento\Service\Seeder\Num;

$string = Str::replace(string: 'foo/bar', with: [
    'foo' => Num::int(1, 9),
    'bar' => Num::int(10, 20)
]);

Lorem种子器

use Tobento\Service\Seeder\Lorem;

$string = Lorem::word(number: 10);

可用方法

Num种子器

use Tobento\Service\Seeder\Num;

$float = Num::float(min: 1.5, max: 55.5);

可用方法

Json种子器

use Tobento\Service\Seeder\Json;
use Tobento\Service\Seeder\Num;

$string = Json::encode([
    'tax_id' => Num::int(min: 1, max: 10),
    'price_net' => Num::price(min: 1, max: 10),
]);

可用方法

Arr种子器

use Tobento\Service\Seeder\Arr;

$value = Arr::item(['green', 'red', 'blue']);

可用方法

致谢

• 托比亚斯·斯特鲁布
• 所有贡献者