wp-cli-fixtures

Inspired by 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 and fzaninotto/Faker. Please refer to these packages docs for advanced usage.

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 | Usage | Contribute

Install

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):

#
# USERS
#
Hellonico\Fixtures\Entity\User:
  user{1..10}:
    user_login (unique): <username()> # '(unique)' is required
    user_pass: 123456
    user_email: <safeEmail()>
    user_url: <url()>
    user_registered: <dateTimeThisDecade()>
    first_name: <firstName()>
    last_name: <lastName()>
    description: <sentence()>
    role: <randomElement(['subscriber', 'editor'])>
    meta:
      phone_number: <phoneNumber()>
      address: <streetAddress()>
      zip: <postcode()>
      city: <city()>
    acf:
      facebook_url: <url()>
      twitter_url: <url()>

#
# ATTACHMENTS
#
Hellonico\Fixtures\Entity\Attachment:
  default (template): # templates can be extended to keep things DRY
    post_title: <words(2, true)>
    post_date: <dateTimeThisDecade()>
    post_content: <paragraphs(5, true)>
  images{1..15} (extends default):
    file: <image(<uploadDir()>, 1200, 1200, 'cats')> # <uploadDir()> is required, image() is the default faker provider and gets images from lorempixel.
  pics{1..15} (extends default):
    file: <picsum(<uploadDir()>, 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: <fileIn('relative/path/to/pdfs')>
  custom_images{1..10} (extends default):
    file: <fileIn('relative/path/to/images')>

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

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

  # TEMPLATE
  default (template):
    post_title: <words(2, true)>
    post_date: <dateTimeThisDecade()>
    post_content: <paragraphs(5, true)>
    post_excerpt: <paragraphs(1, true)>
    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: <paragraphs(1, true)>
    post_category: '3x @category*->term_id' # post_category only accepts IDs
    tax_input:
      post_tag: '5x @tag*->term_id'
      # post_tag: '5x <words(2, true)> # Or tags can be dynamically created

  # PAGES
  page{contact, privacy}:
    post_title: <current()>
    post_type: page

  # CUSTOM POST TYPE
  product{1..15}:
    post_type: product
    acf:
      # number field
      price: <numberBetween(10, 200)>
      # 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: <words(2, true)>
        target: _blank
      # repeater field
      features:
        - label: <words(2, true)>
          value: <sentence()>
        - label: <words(2, true)>
          value: <sentence()>
        - label: <words(2, true)>
          value: <sentence()>
      # layout field
      blocks:
        - acf_fc_layout: text_image
          title: <words(4, true)>
          content: <sentences(8, true)>
          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: <dateTimeThisDecade()>
    comment_author: <username()>
    comment_author_email: <safeEmail()>
    comment_author_url: <url()>
    comment_content: <paragraphs(2, true)>
    comment_agent: <userAgent()>
    comment_author_IP: <ipv4()>
    comment_approved: 1
    comment_karma: <numberBetween(1, 100)>
    # '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: <sentence()>
    meta:
      another_key: <sentence()>

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

#
#  NAV MENUS ITEMS
#
Hellonico\Fixtures\Entity\NavMenuItem:
  custom_menu:
    menu_item_url: <url()>
    menu_item_title: <words(4, true)>
    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:

Hellonico\Fixtures\Entity\Post:
  my_post:
    __construct: [1] # Pass your post ID as the constructor argument
    post_title: '<sentence()>'
    post_content: '<paragraphs(5, true)>'
    post_excerpt: '<paragraphs(1, true)>'

Add/update data to 10 random existing posts:

Hellonico\Fixtures\Entity\Post:
  post{1..10}:
    __construct: [<postId()>] # Use a custom formatters to return a random post ID as the constructor argument
    post_title: '<sentence()>'
    post_content: '<paragraphs(5, true)>'
    post_excerpt: '<paragraphs(1, true)>'

Entities

Post

Hellonico\Fixtures\Entity\Post can take any parameters available in wp_insert_post + 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 + 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 + 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 + meta and acf custom keys.

Comment

Hellonico\Fixtures\Entity\Comment can take any parameters available in wp_insert_comment + 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.

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

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.

Hellonico\Fixtures\Entity\Post:
  post{1..30}:
    post_title: <words(3, true)>
    post_date: <dateTimeThisDecade()>
    acf:
      # number field
      number: <numberBetween(10, 200)>
      # repeater field
      features:
        - label: <words(2, true)>
          value: <sentence()>
        - label: <words(2, true)>
          value: <sentence()>
        - label: <words(2, true)>
          value: <sentence()>

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

Hellonico\Fixtures\Entity\Post:
  post{1..30}:
    post_title: <words(3, true)>
    post_date: <dateTimeThisDecade()>
    meta:
      # number field
      number: <numberBetween(10, 200)>
      meta_box_custom_field: <sentence()>

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

 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.

Hellonico\Fixtures\Entity\Post:
  post{1..30}:
    post_title: <words(3, true)>
    post_date: <dateTimeThisDecade()>
    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, 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

Example:

<postId(category=1,2,3)>

attachmentId($args)

Returns a random existing attachment ID. $args is optional and can take any arguments from get_posts

Example:

<attachmentId(year=2016)>

termId($args)

Returns a random existing term ID. $args is optional and can take any arguments from get_terms

Example:

<termId(taxonomy=post_tag)>

userId($args)

Returns a random existing user ID. $args is optional and can take any arguments from get_users

Example:

<userId(role=subscriber)>

fileContent($file)

Returns the content of a file.

Example:

<fileContent('path/to/file.html')>

fileIn($src, $target, false)

Wrapper around file provider because some Faker providers conflicts with PHP native . Returns file path or file name in a directory ($src relative to fixtures.yml).

Default target is the WordPress uploads.

Example:

<fileIn('my/set/of/images')>

Tips

While playing with fixtures, the 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.