Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/nlemoine/wp-cli-fixtures

Easily generate custom fake data for WordPress
https://github.com/nlemoine/wp-cli-fixtures

fake fake-content fixtures wordpress wp-cli wp-cli-package

Last synced: 3 days ago
JSON representation

Easily generate custom fake data for WordPress

Host: GitHub
URL: https://github.com/nlemoine/wp-cli-fixtures
Owner: nlemoine
License: gpl-3.0
Created: 2016-11-24T11:28:14.000Z (about 8 years ago)
Default Branch: main
Last Pushed: 2024-11-14T21:21:20.000Z (2 months ago)
Last Synced: 2025-01-12T08:06:52.648Z (10 days ago)
Topics: fake, fake-content, fixtures, wordpress, wp-cli, wp-cli-package
Language: PHP
Homepage:
Size: 153 KB
Stars: 102
Watchers: 6
Forks: 18
Open Issues: 4
Metadata Files:
- Readme: README.md
- License: LICENSE

Awesome Lists containing this project

README

wp-cli-fixtures
=========================

[![GitHub Workflow Status](https://img.shields.io/github/workflow/status/nlemoine/wp-cli-fixtures/Testing?style=flat-square)](https://github.com/nlemoine/wp-cli-fixtures/actions/workflows/testing.yml?query=branch%3Amaster+workflow%3ATesting)
![Packagist Downloads](https://img.shields.io/packagist/dt/hellonico/wp-cli-fixtures?style=flat-square)
![Packagist PHP Version Support](https://img.shields.io/packagist/php-v/hellonico/wp-cli-fixtures?style=flat-square)

Inspired by [Faker](https://github.com/trendwerk/faker), this package provides an easy way to create massive and custom fake data for your WordPress installation.
This package is based on [nelmio/alice](https://github.com/nelmio/alice) and [fzaninotto/Faker](https://github.com/fzaninotto/Faker). Please refer to these packages docs for advanced usage.

![wp-cli-fixtures demo](https://hellonico.s3.eu-west-1.amazonaws.com/dev/wp-cli-fixtures.gif)

**WARNING:** This package is mostly intented to be used for development purposes. Use it at your own risk, don't run it on a production database or make sure to back it up first.

Quick links: [Install](#install) | [Usage](#usage) | [Contribute](#contribute)

## Install

```bash
wp package install [email protected]:nlemoine/wp-cli-fixtures.git
```

Requires PHP `^7.3`.

## Usage

### Create fixtures

At the root of your project, create a `fixtures.yml` file (you can download it [here](https://raw.githubusercontent.com/nlemoine/wp-cli-fixtures/master/examples/fixtures.yml)):

```yaml
#
# USERS
#
Hellonico\Fixtures\Entity\User:
user{1..10}:
user_login (unique): # '(unique)' is required
user_pass: 123456
user_email:
user_url:
user_registered:
first_name:
last_name:
description:
role:
meta:
phone_number:
address:
zip:
city:
acf:
facebook_url:
twitter_url:

#
# ATTACHMENTS
#
Hellonico\Fixtures\Entity\Attachment:
default (template): # templates can be extended to keep things DRY
post_title:
post_date:
post_content:
images{1..15} (extends default):
file: , 1200, 1200, 'cats')> # is required, image() is the default faker provider and gets images from lorempixel.
pics{1..15} (extends default):
file: , 1200, 1200)> # Alternatively we provide a picsum() provider which uses picsum for images. It's quicker but doesn't support image categories.
documents{1..2} (extends default):
file:
custom_images{1..10} (extends default):
file:

#
# TERMS
#
Hellonico\Fixtures\Entity\Term:
category{1..10}:
name (unique): # '(unique)' is required
description:
parent: '50%? ' # 50% of created categories will have a top level parent category
taxonomy: 'category' # could be skipped, default to 'category'
tag{1..40}:
name (unique): # '(unique)' is required
description:
taxonomy: post_tag
places{1..4}: # custom taxonomy
name (unique): # '(unique)' is required
description:
taxonomy: place
acf:
address:
zip:
city:
image: '@custom_images*->ID'

#
# POSTS
#
Hellonico\Fixtures\Entity\Post:

# TEMPLATE
default (template):
post_title:
post_date:
post_content:
post_excerpt:
meta:
_thumbnail_id: '@attachment*->ID'

# POSTS
post{1..30} (extends default):
# 'meta' and 'meta_input' are basically the same, you can use one or both,
# they will be merged, just don't provide the same keys in each definition
meta:
_thumbnail_id: '@attachment*->ID'
meta_input:
_extra_field:
post_category: '3x @category*->term_id' # post_category only accepts IDs
tax_input:
post_tag: '5x @tag*->term_id'
# post_tag: '5x # Or tags can be dynamically created

# PAGES
page{contact, privacy}:
post_title:
post_type: page

# CUSTOM POST TYPE
product{1..15}:
post_type: product
acf:
# number field
price:
# gallery field
gallery: '3x @attachment*->ID'
# oembed field
video: https://www.youtube.com/watch?v=E90_aL870ao
# link field
link:
url: https://www.youtube.com/watch?v=E90_aL870ao
title:
target: _blank
# repeater field
features:
- label:
value:
- label:
value:
- label:
value:
# layout field
blocks:
- acf_fc_layout: text_image
title:
content:
image: '@attachment*->ID'
- acf_fc_layout: image_image
image_left: '@attachment*->ID'
image_right: '@attachment*->ID'

#
# COMMENTS
#
Hellonico\Fixtures\Entity\Comment:
comment{1..50}:
comment_post_ID: '@post*->ID'
user_id: '@user*->ID'
comment_date:
comment_author:
comment_author_email:
comment_author_url:
comment_content:
comment_agent:
comment_author_IP:
comment_approved: 1
comment_karma:
# 'meta' and 'comment_meta' are basically the same, you can use one or both,
# they will be merged, just don't provide the same keys in each definition
comment_meta:
some_key:
meta:
another_key:

#
# NAV MENUS
#
Hellonico\Fixtures\Entity\NavMenu:
header:
name: header
locations:
- header
- footer

#
# NAV MENUS ITEMS
#
Hellonico\Fixtures\Entity\NavMenuItem:
custom_menu:
menu_item_url:
menu_item_title:
menu_id: '@header->term_id'
categories{1..3}:
menu_item_object: '@category*'
menu_id: '@header->term_id'
posts{1..3}:
menu_item_object: '@post*'
menu_id: '@header->term_id'
page:
menu_item_object: '@page*'
menu_id: '@header->term_id'
```

The example above will generate:

- 10 users
- 15 attachments
- 10 categories
- 40 tags
- 30 posts with a thumbnail, 3 categories and 5 tags
- 10 pages
- 15 custom post types named 'product'
- 50 comments associated with post and user
- 1 nav menu
- 6 nav menu items

**IMPORTANT:** Make sure referenced IDs are placed **BEFORE** they are used.

Example: `Term` or `Attachment` objects **must** be placed before `Post` if you're referencing them in your fixtures.

### Load fixtures

```
wp fixtures load
```

You can also specify a custom file by using the `--file` argument:

```
wp fixtures load --file=data.yml
```

### Delete fixtures

```
wp fixtures delete
```

You also can delete a single fixture type:

```
wp fixtures delete post
```

Valid types are `post`, `attachment`, `comment`, `term`, `user`.

### Add fake data to existing content

`wp-cli-fixtures` allows you to add/update content to existing entities by passing the ID as a constructor argument.

Add/update data to post ID 1:

```yaml
Hellonico\Fixtures\Entity\Post:
my_post:
__construct: [1] # Pass your post ID as the constructor argument
post_title: ''
post_content: ''
post_excerpt: ''
```

Add/update data to 10 random existing posts:

```yaml
Hellonico\Fixtures\Entity\Post:
post{1..10}:
__construct: [] # Use a custom formatters to return a random post ID as the constructor argument
post_title: ''
post_content: ''
post_excerpt: ''
```

### Entities

#### Post

`Hellonico\Fixtures\Entity\Post` can take any parameters available in [`wp_insert_post`](https://developer.wordpress.org/reference/functions/wp_insert_post/#parameters) + `meta` and `acf` key.

*Note: `post_date_gmt` and `post_modified_gmt` have been disabled, there are set from `post_date` and `post_modified`.*

#### Attachment

`Hellonico\Fixtures\Entity\Attachment` can take any parameters available in [`wp_insert_attachment`](https://developer.wordpress.org/reference/functions/wp_insert_attachment/#parameters) + `meta`, `file` and `acf` custom keys.

*Note: `parent` must be passed with `post_parent` key.*

#### Term

`Hellonico\Fixtures\Entity\Term` can take any parameters available in [`wp_insert_term`](https://developer.wordpress.org/reference/functions/wp_insert_term/#parameters) + `meta` and `acf` custom keys.

*Note: `term` and `taxonomy` must be respectively passed with `name` and `taxonomy` key.*

#### User

`Hellonico\Fixtures\Entity\User` can take any parameters available in [`wp_insert_user`](https://developer.wordpress.org/reference/functions/wp_insert_user/#parameters) + `meta` and `acf` custom keys.

#### Comment

`Hellonico\Fixtures\Entity\Comment` can take any parameters available in [`wp_insert_comment`](https://developer.wordpress.org/reference/functions/wp_insert_comment/#parameters) + `meta` custom key.

`comment_date_gmt` has been disabled, it is set from `comment_date`.

#### Nav menu

`Hellonico\Fixtures\Entity\NavMenu` is a term just like `Hellonico\Fixtures\Entity\Term`. It takes an addiotional `locations` parameter to set the menu location.

```yaml
Hellonico\Fixtures\Entity\NavMenu:
header:
name: header
locations:
- header
```

#### Nav menu item

`Hellonico\Fixtures\Entity\NavMenuItem` takes the same parameters as `$menu_item_data` in [`wp_update_nav_menu_item`](https://developer.wordpress.org/reference/functions/wp_update_nav_menu_item/#parameters)

*Note 1: replace dashes with underscore in keys (e.g. `menu-item-object` becomes `menu_item_object`).*

*Note 2: `menu-item-object` can also accept an entity object, if so, `menu-item-type` and `menu-item-object-id` will be filled automatically with appropriate values*

### ACF Support

Each ACF supported entity (post, term, user) can have an `acf` key, which works just like `meta`.

```yaml
Hellonico\Fixtures\Entity\Post:
post{1..30}:
post_title:
post_date:
acf:
# number field
number:
# repeater field
features:
- label:
value:
- label:
value:
- label:
value:
```
Be careful with duplicate field keys, if you have multiple field with the same key, prefer using ACF field key (`field_948d1qj5mn4d3`).

### MetaBox Support

#### MetaBox Custom Fields
MetaBox fields can be adressed using the `meta` key
```yaml
Hellonico\Fixtures\Entity\Post:
post{1..30}:
post_title:
post_date:
meta:
# number field
number:
meta_box_custom_field:
```

#### MetaBox Relationships (https://docs.metabox.io/extensions/mb-relationships/#using-code)
When using the MB Relationships extension, the relationships can be set/defined using the key `mb_relations`. For each relationship you want to create a fixture for, you use the relationship-ID which is used to register the MB-relation
```php
MB_Relationships_API::register( [
'id' => 'post_to_term',
'from' => 'post',
'to' => [
'object_type' => 'term',
'taxonomy'=> 'custom_term'
],

] );
```
and the post/term ID of the object you want it to have a relationship with.
```yaml
Hellonico\Fixtures\Entity\Post:
post{1..30}:
post_title:
post_date:
mb_relations:
post_to_term: '1x @custom_term*->term_id'
post_to_post: '1x @custom_post*->ID'
```

### Custom formatters

In addition to formatters provided by [fzaninotto/Faker](https://github.com/fzaninotto/Faker#formatters), you can use custom formatters below.

#### `postId($args)`

Returns a random existing post ID.
`$args` is optional and can take any arguments from [`get_posts`](https://developer.wordpress.org/reference/functions/get_posts/#parameters)

Example:

```

#### `attachmentId($args)`

Returns a random existing attachment ID.
`$args` is optional and can take any arguments from [`get_posts`](https://developer.wordpress.org/reference/functions/get_posts/#parameters)

Example:

```

#### `termId($args)`

Returns a random existing term ID.
`$args` is optional and can take any arguments from [`get_terms`](https://developer.wordpress.org/reference/functions/get_terms/#parameters)

Example:

```

#### `userId($args)`

Returns a random existing user ID.
`$args` is optional and can take any arguments from [`get_users`](https://developer.wordpress.org/reference/functions/get_users/#parameters)

Example:

```

#### `fileContent($file)`

Returns the content of a file.

Example:

```

#### `fileIn($src, $target, false)`

Wrapper around [file provider](https://github.com/fzaninotto/Faker#fakerproviderfile) because some Faker providers [conflicts with PHP native ](https://github.com/nelmio/alice/blob/master/doc/getting-started.md#symfony). Returns file path or file name in a directory (`$src` relative to `fixtures.yml`).

Default target is the WordPress `uploads`.

Example:

```

#### Tips

While playing with fixtures, the [database command](https://github.com/ernilambar/database-command) package can be useful to reset database faster than `wp fixtures delete` and start over.

## Contribute

This package follows PSR2 coding standards and is tested with Behat. Execute `composer run test` to ensure your PR passes.

> You will need to run `composer run prepare-tests` before your first run.