README

A Shopware 6 plugin that provides a console command to import custom field sets and custom fields programmatically from a JSON definition file.

Table of Contents

1. Installation
2. Console Command
3. JSON File Format
   • Custom Field Set Fields
   • Custom Field Fields
   • Field Configuration (config)
4. Available Custom Field Types
5. Available Entities for Relations
6. Example JSON File
7. Error Handling & Troubleshooting
8. Tips & Best Practices

Installation

Install the plugin using the Shopware CLI:

# Install the plugin
bin/console plugin:install FyrstCustomFieldConsole

# Activate the plugin
bin/console plugin:activate FyrstCustomFieldConsole

# Clear cache (recommended)
bin/console cache:clear

Console Command

Command Signature

fyrst:custom-field:import <file>

Arguments

Example Usage

bin/console fyrst:custom-field:import /var/www/shopware/custom_fields.json

Command Output

On success, the command prints a table summarizing the imported sets:

 [OK] Successfully imported 2 custom field set(s).

 ---------- -------------------------------------- -------- -----------
  Set Name   ID                                     Fields   Relations
 ---------- -------------------------------------- -------- -----------
  example_   018f3b4c5d6e7f8a9b0c1d2e3f4a5b6c   2        1
  product_
  set
  example_   018f3b4c5d6e7f8a9b0c1d2e3f4a5b6d   1        2
  customer_
  set
 ---------- -------------------------------------- -------- -----------

JSON File Format

The JSON file must contain a root array. Each element in the array is a JSON object representing a single custom field set.

[
  { /* custom field set 1 */ },
  { /* custom field set 2 */ }
]

Custom Field Set Fields

Custom Field Set config Object

The config object typically contains the display label for the custom field set tab:

{
  "label": {
    "en-GB": "English label",
    "de-DE": "German label"
  }
}

Custom Field Fields

Each object in the customFields array defines a single custom field.

Field Configuration (config)

The config object inside a custom field controls how the field is rendered in the administration and what options are available.

Available Custom Field Types

Shopware supports the following custom field types:

Available Entities for Relations

The following entities are commonly used for custom field set relations:

Example JSON File

[
    {
        "name": "example_product_set",
        "config": {
            "label": {
                "en-GB": "Example Product Set",
                "de-DE": "Beispiel Produkt Set"
            }
        },
        "active": true,
        "global": false,
        "position": 1,
        "relations": [
            "product"
        ],
        "customFields": [
            {
                "name": "example_text_field",
                "type": "text",
                "config": {
                    "label": {
                        "en-GB": "Example Text",
                        "de-DE": "Beispiel Text"
                    },
                    "customFieldPosition": 1,
                    "componentName": "sw-field",
                    "type": "text"
                },
                "active": true,
                "allowCustomerWrite": false,
                "allowCartExpose": false,
                "storeApiAware": true,
                "includeInSearch": false
            },
            {
                "name": "example_select_field",
                "type": "select",
                "config": {
                    "label": {
                        "en-GB": "Example Select",
                        "de-DE": "Beispiel Auswahl"
                    },
                    "customFieldPosition": 2,
                    "componentName": "sw-single-select",
                    "options": [
                        {
                            "label": {
                                "en-GB": "Option A",
                                "de-DE": "Option A"
                            },
                            "value": "a"
                        },
                        {
                            "label": {
                                "en-GB": "Option B",
                                "de-DE": "Option B"
                            },
                            "value": "b"
                        }
                    ]
                },
                "active": true,
                "allowCustomerWrite": false,
                "allowCartExpose": false,
                "storeApiAware": true,
                "includeInSearch": false
            }
        ]
    },
    {
        "name": "example_customer_set",
        "config": {
            "label": {
                "en-GB": "Example Customer Set",
                "de-DE": "Beispiel Kunden Set"
            }
        },
        "active": true,
        "global": true,
        "position": 2,
        "relations": [
            "customer",
            "order"
        ],
        "customFields": [
            {
                "name": "example_bool_field",
                "type": "bool",
                "config": {
                    "label": {
                        "en-GB": "Example Bool",
                        "de-DE": "Beispiel Bool"
                    },
                    "customFieldPosition": 1,
                    "componentName": "sw-field",
                    "type": "switch"
                },
                "active": true,
                "allowCustomerWrite": true,
                "allowCartExpose": false,
                "storeApiAware": true,
                "includeInSearch": false
            }
        ]
    }
]

Error Handling & Troubleshooting

Common Errors

General Tips

• Validate JSON first: Use a JSON linter before running the command to catch syntax errors.
• Check uniqueness: Ensure name values for both custom field sets and custom fields are unique across the system.
• Use correct entity names: Verify entity names in relations match Shopware's entity names exactly (case-sensitive).
• Test on staging: Always test your JSON definition on a staging environment before running it on production.
• Run as CLI context: The command runs with Context::createCLIContext(), so it uses the system language. Translations for labels are stored in the JSON itself.

Tips & Best Practices

Naming Conventions

• Use snake_case for technical names (e.g., my_custom_field_set, product_size).
• Prefix names with your project or vendor abbreviation to avoid collisions (e.g., fyrst_product_specs).
• Keep names descriptive but concise.

Positioning and Ordering

• Use position on the custom field set to control tab order in the administration.
• Use customFieldPosition inside each field's config to control the order of fields within the set.
• Start with position: 1 and increment by 1 for each set.

Translations

• Always provide labels in at least en-GB and de-DE for German shops.
• The label object supports any language code (e.g., fr-FR, es-ES).
• Use Defaults::LANGUAGE_SYSTEM (2fbb5fe2e29a4d8aae1a9b0e1c1f1f1f) as a fallback if needed.

Testing

• Create a small test JSON with one set and one field first.
• Run the command and verify the output in the Shopware administration.
• Once confirmed, expand the JSON with more sets and fields.

Re-running the Command

• The command uses upsert, so running it again will update existing sets and fields rather than creating duplicates.
• This makes it safe to re-run the same JSON file after making changes.

Storing JSON Files

• Store your JSON definition files in version control (e.g., Git) alongside your project.
• Keep a backup of the JSON files before making changes.

License

MIT License

Support

For issues or questions, please contact the plugin author or check the Shopware documentation for custom fields.