PHPackages dnadesign/silverstripe-populate - 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. [Testing & Quality](/categories/testing) 4. / 5. dnadesign/silverstripe-populate ActiveSilverstripe-vendormodule[Testing & Quality](/categories/testing) dnadesign/silverstripe-populate =============================== Populate your database through YAML files 4.0.0(10mo ago)25102.3k↑10.9%25[8 issues](https://github.com/silverstripe/silverstripe-populate/issues)[3 PRs](https://github.com/silverstripe/silverstripe-populate/pulls)2BSD-3-ClausePHPPHP ^8.3CI passing Since Jul 12Pushed 10mo ago12 watchersCompare [ Source](https://github.com/silverstripe/silverstripe-populate)[ Packagist](https://packagist.org/packages/dnadesign/silverstripe-populate)[ RSS](/packages/dnadesign-silverstripe-populate/feed)WikiDiscussions master Synced 1mo ago READMEChangelog (7)Dependencies (4)Versions (14)Used By (2) Populate Module =============== [](#populate-module) [![Build Status](https://github.com/silverstripe/silverstripe-populate/actions/workflows/main.yml/badge.svg)](https://github.com/silverstripe/silverstripe-populate/actions/workflows/main.yml/badge.svg) This module provides a way to populate a database from YAML fixtures and custom classes. For instance, when a building a web application the pages and default objects can be defined in YAML and shared around developers. This extends the `requireDefaultRecords` concept in SilverStripe's DataModel. - [Requirements](#requirements) - [Installation Instructions](#installation-instructions) - [Setup](#setup) - [Configuration options](#configuration-options) - [YAML Format](#yaml-format) - [Updating Records](#updating-records) - [`PopulateMergeWhen`](#populatemergewhen) - [`PopulateMergeMatch`](#populatemergematch) - [`PopulateMergeAny`](#populatemergeany) - [Default Assets](#default-assets) - [Extensions](#extensions) - [PopulateMySQLExport](#populatemysqlexport) - [Publish configuration](#publish-configuration) - [Allow Populate to run on "live" environments](#allow-populate-to-run-on-live-environments) Requirements ------------ [](#requirements) - PHP 8.3 - SilverStripe [Framework ^6](https://github.com/silverstripe/silverstripe-framework) - SilverStripe [Versioned ^3](https://github.com/silverstripe/silverstripe-versioned) Installation Instructions ------------------------- [](#installation-instructions) This module must only ever be used in your development environment, and should never be used on production. While there is code to prevent it from being run in production, it is not fool-proof and therefore you must **never run this module in production**. Install it as a dev dependency in composer like so: ``` composer require --dev dnadesign/silverstripe-populate ``` Setup ----- [](#setup) First create a new `yml` config file in your config directory `app/_config/populate.yml` (or add it to an existing `config.yml` file if you prefer). ``` DNADesign\Populate\Populate: include_yaml_fixtures: - 'app/fixtures/populate.yml' ``` *If you're sharing test setup with populate, you can specify any number of paths to load fixtures from.* An example `app/fixtures/populate.yml` might look like the following: ``` Page: home: Title: "Home" Content: "My Home Page" ParentID: 0 SilverStripe\Security\Member: admin: ID: 1 Email: "admin@example.com" PopulateMergeMatch: - 'ID' - 'Email' ``` Out of the box, the records will be created on when you run the `PopulateTask`through `/dev/tasks/PopulateTask/`. To make it completely transparent to developers during the application build, you can also include this to hook in on `requireDefaultRecords` as part of `dev/build` by including the following in one of your application models `requireDefaultRecords` methods: ``` use DNADesign\Populate\Populate; class Page extends SiteTree { public function requireDefaultRecords() { parent::requireDefaultRecords(); Populate::requireRecords(); } } ``` Configuration options --------------------- [](#configuration-options) *include\_yaml\_fixtures* An array of YAML files to parse. **mysite/\_config/app.yml** ``` DNADesign\Populate\Populate: include_yaml_fixtures: - 'app/fixtures/populate.yml' ``` *truncate\_objects* An array of ClassName's whose instances are to be removed from the database prior to importing. Useful to prevent multiple copies of populated content from being imported. It's recommended to truncate any objects you create, to ensure you can re-run `PopulateTask` as often as you want during development and get a consistent database state. This supports Versioned objects (like `SiteTree`) and [Fluent](https://addons.silverstripe.org/add-ons/tractorcow/silverstripe-fluent) (if the module is installed). ``` DNADesign\Populate\Populate: truncate_objects: - Page - SilverStripe\Assets\Image ``` *truncate\_tables* An array of tables to be truncated. Useful when there's no relation between your populated classes and the table you want truncated ``` DNADesign\Populate\Populate: truncate_tables: - Image_Special_Table ``` See *Updating Records* if you wish to merge new and old records rather than clearing all of them. YAML Format ----------- [](#yaml-format) Populate uses the same `FixtureFactory` setup as SilverStripe's unit testing framework. The basic structure of which is: ``` ClassName: somereference: FieldName: "Value" ``` Relations are handled by referring to them by their reference value: ``` SilverStripe\Security\Member: admin: Email: "admin@example.com" Page: homepage: AuthorID: =>SilverStripe\Security\Member.admin ``` See [SilverStripe's fixture documentation](https://docs.silverstripe.org/en/4/developer_guides/testing/fixtures/) for more advanced examples, including `$many_many` and `$many_many_extraFields`. Any object which implements the `Versioned` extension will be automatically published. Basic PHP operations can also be included in the YAML file. Any line that is wrapped in a ` character and ends with a semi colon will be evaled in the current scope of the importer. ``` Page: mythankyoupage: ThankYouText: "`Page::config()->thank_you_text`;" LinkedPage: "`sprintf(\"[Page](%s)\", App\\Page\\HelpPage::get()->first()->Link())`;" ``` ### Updating Records [](#updating-records) If you do not truncate the entire table, the module will attempt to first look up an existing record and update that existing record. For this to happen the YAML must declare the fields to match in the look up. You can use several options for this. #### `PopulateMergeWhen` [](#populatemergewhen) Contains a WHERE clause to match e.g `"URLSegment = 'home' AND ParentID = 0"`. ``` Mysite\PageTypes\HomePage: home: Title: "My awesome homepage" PopulateMergeWhen: "URLSegment = 'home' AND ParentID = 0" ``` ### `PopulateMergeMatch` [](#populatemergematch) Takes a list of fields defined in the YAML and matches them based on the database to avoid repeating content ``` Mysite\PageTypes\HomePage: home: Title: "My awesome homepage" URLSegment: 'home' ParentID: 0 PopulateMergeMatch: - URLSegment - ParentID ``` ### `PopulateMergeAny` [](#populatemergeany) Takes the first record in the database and merges with that. This option is suitable for things like `SiteConfig` where you normally only contain a single record. ``` SilverStripe\SiteConfig\SiteConfig: mysiteconfig: Tagline: "SilverStripe is awesome" PopulateMergeAny: true ``` If the criteria meets more than 1 instance, all instances bar the first are removed from the database so ensure you criteria is specific enough to get the unique field value. ### Default Assets [](#default-assets) The script also handles creating default File and image records through the `PopulateFileFrom` flag. This copies the file from another path (say mysite) and puts the file inside your assets folder. ``` SilverStripe\Assets\Image: lgoptimusl3ii: Filename: assets/shop/lgoptimusl3ii.png PopulateFileFrom: app/images/demo/large.png Mysite\PageTypes\Product: lgoptimus: ProductImage: =>SilverStripe\Assets\Image.lgoptimusl3ii ``` Extensions ---------- [](#extensions) The module also provides extensions that can be opted into depending on your project needs ### PopulateMySQLExport [](#populatemysqlexport) This extension outputs the result of the Populate::requireDefaultRecords() as a SQL Dump on your local machine. This speeds up the process if using Populate as part of a test suite or some other CI service as instead of manually calling the task (which will use the ORM) your test case can be fed raw MySQL to import and hopefully speed up execution times. To apply the extension add it to Populate, configure the path, flush, then run `dev/tasks/PopulateTask` ``` DNADesign\Populate\PopulateMySQLExportExtension: export_db_path: ~/path.sql DNADesign\Populate\Populate: extensions - DNADesign\Populate\PopulateMySQLExportExtension ``` Publish configuration --------------------- [](#publish-configuration) By default the module uses `publishSingle()` to publish records. If, for whatever reason, you would prefer to that the module uses `publishRecursive()`, you can enable this by settings the following configuration: ``` DNADesign\Populate\Populate: enable_publish_recursive: true ``` Allow Populate to run on "live" environments -------------------------------------------- [](#allow-populate-to-run-on-live-environments) **DANGER ZONE:** Please understand that you are about to provide admins with the ability to run Populate on your production environment. Before setting this configuration you should understand and accept the risks related to the loss of production data. ``` DNADesign\Populate\Populate: allow_build_on_live: true ``` Credits ------- [](#credits) silverstripe-populate was originally created by [wilr](https://github.com/wilr) and [DNA Design](https://www.dna.co.nz/). ### Health Score 55 — FairBetter than 98% of packages Maintenance46 Moderate activity, may be stable Popularity44 Moderate usage in the ecosystem Community32 Small or concentrated contributor base Maturity85 Battle-tested with a long release history Bus Factor2 2 contributors hold 50%+ of commits 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 Every ~242 days Recently: every ~182 days Total 13 Last Release 323d ago Major Versions 1.x-dev → 2.0.02018-07-11 2.x-dev → 3.0.02023-07-02 3.x-dev → 4.0.02025-06-29 PHP version history (4 changes)2.0.1PHP >=7.1 2.2.0PHP ^7.4 || ^8.0 3.0.0PHP ^8.1 4.0.0PHP ^8.3 ### Community Maintainers ![](https://www.gravatar.com/avatar/efd88fa106982bcf2e3cd689e6a37d352c54308d14dedeac4ac477a47a432363?d=identicon)[DNADesign](/maintainers/DNADesign) ![](https://www.gravatar.com/avatar/a496a763166447513522eeff7b822da348a006ce474e5224b1fddbd839c736dc?d=identicon)[madmatt](/maintainers/madmatt) ![](https://avatars.githubusercontent.com/u/101629?v=4)[Will Rossiter](/maintainers/wilr)[@wilr](https://github.com/wilr) --- Top Contributors [![wilr](https://avatars.githubusercontent.com/u/101629?v=4)](https://github.com/wilr "wilr (31 commits)")[![madmatt](https://avatars.githubusercontent.com/u/893117?v=4)](https://github.com/madmatt "madmatt (10 commits)")[![chrispenny](https://avatars.githubusercontent.com/u/505788?v=4)](https://github.com/chrispenny "chrispenny (7 commits)")[![wernerkrauss](https://avatars.githubusercontent.com/u/1043925?v=4)](https://github.com/wernerkrauss "wernerkrauss (3 commits)")[![Zauberfisch](https://avatars.githubusercontent.com/u/186158?v=4)](https://github.com/Zauberfisch "Zauberfisch (2 commits)")[![cebravo94](https://avatars.githubusercontent.com/u/22768739?v=4)](https://github.com/cebravo94 "cebravo94 (2 commits)")[![michalkleiner](https://avatars.githubusercontent.com/u/233342?v=4)](https://github.com/michalkleiner "michalkleiner (2 commits)")[![satrun77](https://avatars.githubusercontent.com/u/166450?v=4)](https://github.com/satrun77 "satrun77 (2 commits)")[![anselmdk](https://avatars.githubusercontent.com/u/1316533?v=4)](https://github.com/anselmdk "anselmdk (2 commits)")[![catharsisjelly](https://avatars.githubusercontent.com/u/510747?v=4)](https://github.com/catharsisjelly "catharsisjelly (1 commits)")[![scott1702](https://avatars.githubusercontent.com/u/10215604?v=4)](https://github.com/scott1702 "scott1702 (1 commits)")[![silverstripe-elliot](https://avatars.githubusercontent.com/u/5863816?v=4)](https://github.com/silverstripe-elliot "silverstripe-elliot (1 commits)")[![emteknetnz](https://avatars.githubusercontent.com/u/4809037?v=4)](https://github.com/emteknetnz "emteknetnz (1 commits)")[![dhensby](https://avatars.githubusercontent.com/u/563596?v=4)](https://github.com/dhensby "dhensby (1 commits)")[![n8-dev](https://avatars.githubusercontent.com/u/11827838?v=4)](https://github.com/n8-dev "n8-dev (1 commits)") --- Tags silverstripesilverstripe-moduleFixturefakermockyamlsilverstripepopulate ### Code Quality Code StylePHP\_CodeSniffer ### Embed Badge ![Health badge](/badges/dnadesign-silverstripe-populate/health.svg) ``` [![Health](https://phpackages.com/badges/dnadesign-silverstripe-populate/health.svg)](https://phpackages.com/packages/dnadesign-silverstripe-populate) ``` ### Alternatives [nelmio/alice Expressive fixtures generator 2.5k43.4M133](/packages/nelmio-alice)[zenstruck/foundry A model factory library for creating expressive, auto-completable, on-demand dev/test fixtures with Symfony and Doctrine. 78311.9M97](/packages/zenstruck-foundry)[silverstripe/cms The SilverStripe Content Management System 5163.4M1.3k](/packages/silverstripe-cms)[silverstripe/admin SilverStripe admin interface 262.6M325](/packages/silverstripe-admin)[silverleague/ideannotator Generate PHP DocBlock annotations for DataObject and DataExtension databasefields and relation methods 4768.0k43](/packages/silverleague-ideannotator)[lastzero/test-tools Increases testing productivity by adding a service container and self-initializing fakes to PHPUnit 2244.3k13](/packages/lastzero-test-tools) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)