{"id":13650554,"url":"https://github.com/silverstripe/silverstripe-populate","last_synced_at":"2026-05-06T04:05:28.774Z","repository":{"id":13471033,"uuid":"16161034","full_name":"silverstripe/silverstripe-populate","owner":"silverstripe","description":"Populate your database through YAML files","archived":false,"fork":false,"pushed_at":"2023-07-02T19:52:01.000Z","size":98,"stargazers_count":26,"open_issues_count":12,"forks_count":24,"subscribers_count":14,"default_branch":"master","last_synced_at":"2024-10-31T02:03:33.589Z","etag":null,"topics":["silverstripe","silverstripe-module"],"latest_commit_sha":null,"homepage":"","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/silverstripe.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2014-01-23T03:23:54.000Z","updated_at":"2024-02-01T00:26:51.000Z","dependencies_parsed_at":"2024-04-14T16:58:49.459Z","dependency_job_id":"a0992755-1bd7-4c35-a03b-05c6a4a95eca","html_url":"https://github.com/silverstripe/silverstripe-populate","commit_stats":{"total_commits":57,"total_committers":17,"mean_commits":"3.3529411764705883","dds":0.7192982456140351,"last_synced_commit":"7797c697e0cd5e502e92e619a0c106dc0a60ddfe"},"previous_names":[],"tags_count":7,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/silverstripe%2Fsilverstripe-populate","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/silverstripe%2Fsilverstripe-populate/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/silverstripe%2Fsilverstripe-populate/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/silverstripe%2Fsilverstripe-populate/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/silverstripe","download_url":"https://codeload.github.com/silverstripe/silverstripe-populate/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":230408171,"owners_count":18220974,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["silverstripe","silverstripe-module"],"created_at":"2024-08-02T02:00:37.764Z","updated_at":"2024-12-19T09:08:18.710Z","avatar_url":"https://github.com/silverstripe.png","language":"PHP","funding_links":[],"categories":["Very Useful Modules"],"sub_categories":["Development Helpers"],"readme":"# Populate Module\n\n![Build Status](https://github.com/silverstripe/silverstripe-populate/actions/workflows/main.yml/badge.svg)\n\nThis module provides a way to populate a database from YAML fixtures and custom\nclasses. For instance, when a building a web application the pages and default\nobjects can be defined in YAML and shared around developers. This extends the\n`requireDefaultRecords` concept in SilverStripe's DataModel.\n\n* [Requirements](#requirements)\n* [Installation Instructions](#installation-instructions)\n* [Setup](#setup)\n* [Configuration options](#configuration-options)\n* [YAML Format](#yaml-format)\n    * [Updating Records](#updating-records)\n    * [`PopulateMergeWhen`](#populatemergewhen)\n    * [`PopulateMergeMatch`](#populatemergematch)\n    * [`PopulateMergeAny`](#populatemergeany)\n    * [Default Assets](#default-assets)\n* [Extensions](#extensions)\n    * [PopulateMySQLExport](#populatemysqlexport)\n* [Publish configuration](#publish-configuration)\n* [Allow Populate to run on \"live\" environments](#allow-populate-to-run-on-live-environments)\n\n## Requirements\n\n* PHP 8.1\n* SilverStripe [Framework ^5](https://github.com/silverstripe/silverstripe-framework)\n* SilverStripe [Versioned ^2](https://github.com/silverstripe/silverstripe-versioned)\n\n## Installation Instructions\n\nThis 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:\n```\ncomposer require --dev dnadesign/silverstripe-populate\n```\n\n## Setup\n\nFirst 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).\n\n```yaml\nDNADesign\\Populate\\Populate:\n  include_yaml_fixtures:\n    - 'app/fixtures/populate.yml'\n```\n\n*If you're sharing test setup with populate, you can specify any number of paths to load fixtures from.*\n\nAn example `app/fixtures/populate.yml` might look like the following:\n\n```yaml\nPage:\n  home:\n    Title: \"Home\"\n    Content: \"My Home Page\"\n    ParentID: 0\nSilverStripe\\Security\\Member:\n  admin:\n    ID: 1\n    Email: \"admin@example.com\"\n    PopulateMergeMatch:\n      - 'ID'\n      - 'Email'\n```\n\nOut of the box, the records will be created on when you run the `PopulateTask`\nthrough `/dev/tasks/PopulateTask/`. To make it completely transparent to\ndevelopers during the application build, you can also include this to hook in on\n`requireDefaultRecords` as part of `dev/build` by including the following in\none of your application models `requireDefaultRecords` methods:\n\n```php\nuse DNADesign\\Populate\\Populate;\n\nclass Page extends SiteTree\n{\n    public function requireDefaultRecords()\n    {\n        parent::requireDefaultRecords();\n        Populate::requireRecords();\n    }\n}\n```\n\n## Configuration options\n\n*include_yaml_fixtures*\n\nAn array of YAML files to parse.\n\n**mysite/_config/app.yml**\n\n```yaml\nDNADesign\\Populate\\Populate:\n  include_yaml_fixtures:\n    - 'app/fixtures/populate.yml'\n```\n\n*truncate_objects*\n\nAn 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).\n\n```yaml\nDNADesign\\Populate\\Populate:\n  truncate_objects:\n    - Page\n    - SilverStripe\\Assets\\Image\n```\n\n*truncate_tables*\n\nAn array of tables to be truncated. Useful when there's no relation between your populated classes and the table you want truncated\n\n```yaml\nDNADesign\\Populate\\Populate:\n  truncate_tables:\n    - Image_Special_Table\n```\n\nSee *Updating Records* if you wish to merge new and old records rather than\nclearing all of them.\n\n## YAML Format\n\nPopulate uses the same `FixtureFactory` setup as SilverStripe's unit testing\nframework. The basic structure of which is:\n\n```yaml\nClassName:\n  somereference:\n    FieldName: \"Value\"\n```\n\nRelations are handled by referring to them by their reference value:\n```yaml\nSilverStripe\\Security\\Member:\n    admin:\n      Email: \"admin@example.com\"\n\nPage:\n  homepage:\n    AuthorID: =\u003eSilverStripe\\Security\\Member.admin\n```\n\nSee [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`.\n\nAny object which implements the `Versioned` extension will be automatically\npublished.\n\nBasic PHP operations can also be included in the YAML file. Any line that is\nwrapped in a ` character and ends with a semi colon will be evaled in the\ncurrent scope of the importer.\n\n```yaml\nPage:\n  mythankyoupage:\n    ThankYouText: \"`Page::config()-\u003ethank_you_text`;\"\n    LinkedPage: \"`sprintf(\\\"[Page](%s)\\\", App\\\\Page\\\\HelpPage::get()-\u003efirst()-\u003eLink())`;\"\n```\n\n### Updating Records\n\nIf you do not truncate the entire table, the module will attempt to first look\nup an existing record and update that existing record. For this to happen the\nYAML must declare the fields to match in the look up. You can use several\noptions for this.\n\n#### `PopulateMergeWhen`\n\nContains a WHERE clause to match e.g `\"URLSegment = 'home' AND ParentID = 0\"`.\n\n```yaml\nMysite\\PageTypes\\HomePage:\n  home:\n    Title: \"My awesome homepage\"\n    PopulateMergeWhen: \"URLSegment = 'home' AND ParentID = 0\"\n```\n\n### `PopulateMergeMatch`\n\nTakes a list of fields defined in the YAML and matches them based on the\ndatabase to avoid repeating content\n\n```yaml\nMysite\\PageTypes\\HomePage:\n  home:\n    Title: \"My awesome homepage\"\n    URLSegment: 'home'\n    ParentID: 0\n    PopulateMergeMatch:\n      - URLSegment\n      - ParentID\n```\n\n### `PopulateMergeAny`\n\nTakes the first record in the database and merges with that. This option is\nsuitable for things like `SiteConfig` where you normally only contain a single\nrecord.\n\n```yaml\nSilverStripe\\SiteConfig\\SiteConfig:\n  mysiteconfig:\n    Tagline: \"SilverStripe is awesome\"\n    PopulateMergeAny: true\n```\n\nIf the criteria meets more than 1 instance, all instances bar the first are\nremoved from the database so ensure you criteria is specific enough to get the\nunique field value.\n\n### Default Assets\n\nThe script also handles creating default File and image records through the\n`PopulateFileFrom` flag. This copies the file from another path (say mysite) and\nputs the file inside your assets folder.\n\n```yaml\nSilverStripe\\Assets\\Image:\n  lgoptimusl3ii:\n    Filename: assets/shop/lgoptimusl3ii.png\n    PopulateFileFrom: app/images/demo/large.png\n\nMysite\\PageTypes\\Product:\n  lgoptimus:\n    ProductImage: =\u003eSilverStripe\\Assets\\Image.lgoptimusl3ii\n```\n\n## Extensions\n\nThe module also provides extensions that can be opted into depending on your\nproject needs\n\n### PopulateMySQLExport\n\nThis extension outputs the result of the Populate::requireDefaultRecords() as a\nSQL Dump on your local machine. This speeds up the process if using Populate as\npart of a test suite or some other CI service as instead of manually calling\nthe task (which will use the ORM) your test case can be fed raw MySQL to import\nand hopefully speed up execution times.\n\nTo apply the extension add it to Populate, configure the path, flush, then run\n`dev/tasks/PopulateTask`\n\n```yaml\nDNADesign\\Populate\\PopulateMySQLExportExtension:\n  export_db_path: ~/path.sql\n\nDNADesign\\Populate\\Populate:\n  extensions\n    - DNADesign\\Populate\\PopulateMySQLExportExtension\n```\n\n## Publish configuration\n\nBy default the module uses `publishSingle()` to publish records. If, for whatever reason, you would prefer to that the\nmodule uses `publishRecursive()`, you can enable this by settings the following configuration:\n\n```yaml\nDNADesign\\Populate\\Populate:\n  enable_publish_recursive: true\n```\n\n## Allow Populate to run on \"live\" environments\n\n**DANGER ZONE:** Please understand that you are about to provide admins with the ability to run Populate on your\nproduction environment. Before setting this configuration you should understand and accept the risks related to the\nloss of production data.\n\n```yaml\nDNADesign\\Populate\\Populate:\n  allow_build_on_live: true\n```\n\n## Credits\n\nsilverstripe-populate was originally created by [wilr](https://github.com/wilr) and [DNA Design](https://www.dna.co.nz/).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsilverstripe%2Fsilverstripe-populate","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsilverstripe%2Fsilverstripe-populate","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsilverstripe%2Fsilverstripe-populate/lists"}