Working with Custom Fields Sets and Configuration in Shopware 6.7

Shopware 6.7 introduces significant enhancements to the custom fields system, providing developers with more flexibility and control over extending product, category, and other entity configurations. This blog post explores the technical implementation details of custom fields sets and configuration management in the latest Shopware version.

Understanding Custom Fields in Shopware 6.7

Custom fields in Shopware 6.7 represent a powerful extension mechanism that allows developers to add additional attributes to existing entities without modifying core database structures. The system now supports custom field sets, which provide a structured approach to organizing and managing custom fields across different contexts.

Custom Field Sets Architecture

In Shopware 6.7, custom field sets are implemented as dedicated entities that can be associated with multiple entities simultaneously. This architectural change simplifies the management of custom fields by providing a centralized configuration approach.

// Example of creating a custom field set
use Shopware\Core\Framework\DataAbstractionLayer\Write\Command\CreateCommand;
use Shopware\Core\Framework\DataAbstractionLayer\Write\Validation\UniqueConstraintViolationException;

$customFieldSet = [
    'name' => 'ProductConfiguration',
    'config' => [
        'customFields' => [
            [
                'name' => 'product_weight',
                'type' => 'float',
                'label' => ['de-DE' => 'Gewicht', 'en-GB' => 'Weight'],
                'helpText' => ['de-DE' => 'Produktgewicht in kg', 'en-GB' => 'Product weight in kg'],
                'required' => false,
            ],
            [
                'name' => 'product_material',
                'type' => 'text',
                'label' => ['de-DE' => 'Material', 'en-GB' => 'Material'],
                'required' => true,
            ]
        ]
    ],
    'entities' => ['product', 'category']
];

Technical Implementation Details

Database Structure Changes

Shopware 6.7 introduces enhanced database schema support for custom fields. The custom_field_set table now includes additional metadata columns that provide better context management and performance optimization.

CREATE TABLE `custom_field_set` (
    `id` BINARY(16) NOT NULL,
    `name` VARCHAR(255) NOT NULL,
    `config` JSON NOT NULL,
    `created_at` DATETIME(3) NOT NULL,
    `updated_at` DATETIME(3) DEFAULT NULL,
    `entities` JSON NOT NULL,
    PRIMARY KEY (`id`),
    KEY `custom_field_set_name` (`name`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;

Custom Field Set Registration

To register custom field sets, developers must implement the appropriate service definitions and configuration files. The new system supports both manual registration and automatic discovery mechanisms.

// services.xml - Custom field set registration
<service id="Shopware\Core\Content\Product\SalesChannel\CustomFieldSetLoader">
    <argument type="service" id="custom_field_set.repository"/>
    <call method="addCustomFieldSet">
        <argument>product_configuration</argument>
        <argument>%kernel.project_dir%/config/custom_fields/product_config.xml</argument>
    </call>
</service>

Configuration File Format

Shopware 6.7 supports XML configuration files for defining custom field sets with enhanced validation and type support.

<?xml version="1.0" encoding="UTF-8"?>
<custom-field-set xmlns="http://shopware.com/schema/custom-field-set">
    <name>ProductConfiguration</name>
    <entities>
        <entity>product</entity>
        <entity>category</entity>
    </entities>
    <fields>
        <field name="product_weight" type="float">
            <label lang="de-DE">Gewicht</label>
            <label lang="en-GB">Weight</label>
            <helpText lang="de-DE">Produktgewicht in kg</helpText>
            <helpText lang="en-GB">Product weight in kg</helpText>
            <required>false</required>
            <position>1</position>
        </field>
        <field name="product_material" type="text">
            <label lang="de-DE">Material</label>
            <label lang="en-GB">Material</label>
            <required>true</required>
            <position>2</position>
        </field>
    </fields>
</custom-field-set>

Advanced Configuration Patterns

Multi-Language Support

Shopware 6.7 enhances multi-language support for custom fields, providing better integration with the existing translation system.

// Custom field configuration with translations
$customFieldConfig = [
    'name' => 'product_dimensions',
    'type' => 'text',
    'label' => [
        'de-DE' => 'Abmessungen',
        'en-GB' => 'Dimensions',
        'fr-FR' => 'Dimensions'
    ],
    'helpText' => [
        'de-DE' => 'Länge x Breite x Höhe',
        'en-GB' => 'Length x Width x Height',
        'fr-FR' => 'Longueur x Largeur x Hauteur'
    ],
    'required' => false,
    'customFieldSetId' => 'b5a8d4c3-e7f2-4c8a-9b6e-1a2b3c4d5e6f'
];

Conditional Field Display

The new version introduces conditional logic for custom field display, allowing fields to appear or disappear based on other field values.

// Conditional custom field configuration
$conditionalField = [
    'name' => 'shipping_method',
    'type' => 'select',
    'label' => ['de-DE' => 'Versandmethode', 'en-GB' => 'Shipping Method'],
    'options' => [
        ['id' => 'standard', 'label' => ['de-DE' => 'Standard', 'en-GB' => 'Standard']],
        ['id' => 'express', 'label' => ['de-DE' => 'Express', 'en-GB' => 'Express']]
    ],
    'dependsOn' => [
        'field' => 'product_category',
        'values' => ['electronics', 'books']
    ]
];

Performance Optimization

Caching Mechanisms

Shopware 6.7 implements enhanced caching strategies for custom field configurations, reducing database queries and improving response times.

// Custom field set cache configuration
class CustomFieldSetCache
{
    public function getCustomFieldSet(string $setId): array
    {
        $cacheKey = 'custom_field_set_' . $setId;
        
        if ($this->cache->has($cacheKey)) {
            return $this->cache->get($cacheKey);
        }
        
        $result = $this->repository->search(
            new Criteria([$setId]),
            $this->context
        )->first();
        
        $this->cache->set($cacheKey, $result, 3600); // 1 hour cache
        
        return $result;
    }
}

Indexing Strategy

The system now supports advanced indexing for custom field values, improving query performance on large datasets.

-- Custom field value indexing
CREATE INDEX `custom_field_value_product_id` ON `custom_field_value` (`product_id`);
CREATE INDEX `custom_field_value_set_id` ON `custom_field_value` (`custom_field_set_id`);
CREATE FULLTEXT INDEX `custom_field_value_search` ON `custom_field_value` (`value`);

Integration with API Endpoints

REST API Enhancements

Shopware 6.7 extends the REST API to provide better support for custom fields in both read and write operations.

// Custom field handling in API controllers
class ProductCustomFieldController extends AbstractController
{
    #[Route('/api/v{version}/product/{id}', methods: ['GET'])]
    public function getProductWithCustomFields(string $id, Request $request): Response
    {
        $criteria = new Criteria([$id]);
        $criteria->addAssociation('customFields');
        
        $product = $this->productRepository->search($criteria, $this->context)->first();
        
        return new JsonResponse([
            'data' => $product->toArray(),
            'customFields' => $this->getCustomFieldValues($product)
        ]);
    }
}

GraphQL Support

The GraphQL schema now includes enhanced support for custom fields with proper type definitions and filtering capabilities.

# Custom field schema extension
type Product {
    id: ID!
    name: String!
    customFields: CustomFieldSet
}

input CustomFieldSetInput {
    product_weight: Float
    product_material: String
    product_dimensions: String
}

Migration Considerations

Backward Compatibility

Shopware 6.7 maintains backward compatibility with existing custom field implementations while providing new features through enhanced APIs.

// Migration script for legacy custom fields
class CustomFieldMigration extends MigrationStep
{
    public function update(Connection $connection): void
    {
        // Migrate old custom field structures to new set-based approach
        $connection->executeStatement(
            'UPDATE custom_field SET custom_field_set_id = :setId WHERE custom_field_set_id IS NULL',
            ['setId' => $this->generateNewSetId()]
        );
    }
}

Data Migration

The migration process includes automated conversion of existing custom fields into the new set-based structure.

// Data migration example
class CustomFieldDataMigration
{
    public function migrateCustomFields(): void
    {
        $oldFields = $this->getOldCustomFields();
        
        foreach ($oldFields as $field) {
            $newSet = $this->createCustomFieldSet($field);
            $this->assignFieldToSet($field, $newSet);
        }
    }
}

Best Practices and Recommendations

Performance Optimization

Use appropriate data types to minimize storage requirements
Implement proper caching strategies for frequently accessed custom field sets
Design efficient queries that leverage database indexing
Consider lazy loading for complex custom field configurations

Security Considerations

Validate all input data before storing custom field values
Implement proper access controls for custom field management
Sanitize output data when displaying custom fields in templates
Monitor field usage patterns to identify potential security issues

Conclusion

Shopware 6.7's enhanced custom fields system provides developers with sophisticated tools for extending entity configurations while maintaining performance and scalability. The introduction of custom field sets, improved multi-language support, and advanced configuration options create a more robust foundation for custom development.

By understanding the technical implementation details and following best practices, developers can leverage these new features to build more flexible and maintainable e-commerce solutions. The enhanced caching mechanisms, API integrations, and migration support ensure that upgrading to Shopware 6.7 provides both immediate benefits and long-term architectural advantages.

The system's extensibility through configuration files, database schema enhancements, and comprehensive API support makes it easier than ever to customize Shopware installations while maintaining data integrity and performance standards. As the e-commerce landscape continues to evolve, these custom fields improvements position Shopware 6.7 as a robust platform for complex business requirements.

Working with Custom Fields Sets and Configuration in Shopware 6.7

Understanding Custom Fields in Shopware 6.7#

Custom Field Sets Architecture#

Technical Implementation Details#

Database Structure Changes#

Custom Field Set Registration#

Configuration File Format#

Advanced Configuration Patterns#

Multi-Language Support#

Conditional Field Display#

Performance Optimization#

Caching Mechanisms#

Indexing Strategy#

Integration with API Endpoints#

REST API Enhancements#

GraphQL Support#

Migration Considerations#

Backward Compatibility#

Data Migration#

Best Practices and Recommendations#

Performance Optimization#

Security Considerations#

Conclusion#

Related reading

How to Add a Custom Entity in Under 10 Minutes

Extending the Search Index with Custom Fields in Shopware 6.7

How to Add a Custom Field to the Product Entity in Shopware 6.7

Shopware 6.7 Deep Dive: Mastering Data Abstraction Layer Performance Pitfalls

A Guide to Custom Entity Relationships (OneToMany, ManyToMany) in Shopware 6.7

How to Extend an Existing Entity Definition in Shopware 6.7

Understanding Custom Fields in Shopware 6.7

Custom Field Sets Architecture

Technical Implementation Details

Database Structure Changes

Custom Field Set Registration

Configuration File Format

Advanced Configuration Patterns

Multi-Language Support

Conditional Field Display

Performance Optimization

Caching Mechanisms

Indexing Strategy

Integration with API Endpoints

REST API Enhancements

GraphQL Support

Migration Considerations

Backward Compatibility

Data Migration

Best Practices and Recommendations

Performance Optimization

Security Considerations

Conclusion