PHPackages                             guava/laravel-populator - 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. [Database & ORM](/categories/database)
4. /
5. guava/laravel-populator

ActiveLibrary[Database & ORM](/categories/database)

guava/laravel-populator
=======================

A laravel package for seeding testing and production data.

1.3.0(1y ago)221.4k2[5 issues](https://github.com/GuavaCZ/laravel-populator/issues)MITPHP

Since Jan 18Pushed 1y ago2 watchersCompare

[ Source](https://github.com/GuavaCZ/laravel-populator)[ Packagist](https://packagist.org/packages/guava/laravel-populator)[ RSS](/packages/guava-laravel-populator/feed)WikiDiscussions main Synced 3w ago

READMEChangelog (9)Dependencies (5)Versions (16)Used By (0)

Laravel Populator
=================

[](#laravel-populator)

[![Packagist Version](https://camo.githubusercontent.com/b213136e4836c4c077ad1864c88500e58a3998f33770434aeb63f7b844b7097a/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f67756176612f6c61726176656c2d706f70756c61746f723f7374796c653d666f722d7468652d6261646765)](https://camo.githubusercontent.com/b213136e4836c4c077ad1864c88500e58a3998f33770434aeb63f7b844b7097a/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f67756176612f6c61726176656c2d706f70756c61746f723f7374796c653d666f722d7468652d6261646765)

Laravel populator's goal is to provide an unified way to populate your database with predefined data, while keeping your migrations intact.

There's a lot of tutorials and opinions about how to do that. Some people manually insert data into the database inside migrations and some use seeders. In both cases, a lot of people tend to use `Model::create()`, which at first sight seems like the easiest way and it even works. However, if you change your Model's structure in the future, there's a chance your migrations stop working. For example when tinkering with the `fillable` property.

Laravel populator solves this problem while maintaining a great developer experience when dealing with your database data.

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

[](#installation)

You can install the package with composer:

```
  composer require guava/laravel-populator
```

You can optionally publish the database migrations if you plan to enable [tracking](#tracking-inserted-models)

```
php artisan vendor:publish --provider 'Guava\LaravelPopulator\PopulatorServiceProvider' --tag 'migrations'
php artisan migrate
```

or publish the config

```
php artisan vendor:publish --provider 'Guava\LaravelPopulator\PopulatorServiceProvider' --tag 'config'
```

which currently provides the following options

**config/populator.php**

```
return [
    'tracking' => false,
    'population_model' => '\Guava\LaravelPopulator\Models\Population',
];
```

How it works
------------

[](#how-it-works)

There are three major terms that Laravel Populator introduces:

**Populators**: These are basically named folders inside your `/database/populators` folder. They contain bundles.

**Bundles**: A bundle is collection of records of specific model. Bundles are part of the populator and are used to define the model of the records, default attributes or mutations.

**Records**: A record is the smallest unit and it represents a database record waiting to be populated. A record is a php file, which returns an array with `key => value` pairs describing your model / databse entry.

Example
-------

[](#example)

`2023_01_20_203807_populate_initial_data.php`:

```
return new class extends Migration {

    public function up() {
        Populator::make('initial') // // bundles are located in /database/populators/initial/
            ->environments(['local', 'testing'])
            ->bundles([
                Bundle::make(User::class)
                    ->mutate('password', fn($value) => Hash::make($value))
                    ->records([
                        'admin' => [
                            'name' => 'Administrator',
                            'email' => 'admin@example.tld',
                            'password' => 'my-strong-password',
                        ],
                    ]),

                Bundle::make(Tag::class, 'my-tags'), // records are located in /database/populators/initial/my-tags/

                Bundle::make(Post::class) // records are located in /database/populators/initial/post/
                    ->generate('slug', fn(array $attributes) => Str::slug($attributes['name'])),

                Bundle::make(Permission::class) // records are located in /database/populators/initial/permission/
                    ->default('guard_name', 'web'),

                Bundle::make(Role::class) // records are located in /database/populators/initial/role/
                    ->default('guard_name', 'web'),

            ]);
    }

}
```

example record `/database/populators/initial/post/example-post.php`:

```