How to Generate a UUID in Shopware 6 (PHP Examples & Best Practices)

What is a UUID in Shopware 6?

A UUID (Universally Unique Identifier) is a 128-bit identifier used to uniquely identify records. In Shopware 6, UUIDs are used as primary keys for most entities (products, customers, orders, custom entities, and more).

One important Shopware detail: UUIDs are stored efficiently in the database as binary(16), but in PHP and most Shopware APIs you commonly work with the hex representation (32 characters).

How to generate a UUID in Shopware 6

This is the standard and recommended way. It generates a valid Shopware-compatible UUID in hex format.

use Shopware\Core\Framework\Uuid\Uuid;

$uuid = Uuid::randomHex();

Example output (hex UUIDs look like this):

b2797f53b1b84a82a70494270f2e9b1d
ceb13f897cb342588270a0eaec046254
ff83a318808f412c9f657e9182f6ed78

Using the UUID in the Shopware DAL (repository create)

In most DAL writes, you can pass IDs as hex strings. You don’t always need to provide an id manually because Shopware can generate it, but it’s very useful for imports, mappings, fixtures, and reproducible data.

use Shopware\Core\Framework\Uuid\Uuid;

/** @var \Shopware\Core\Framework\DataAbstractionLayer\EntityRepository $repository */
/** @var \Shopware\Core\Framework\Context $context */

$id = Uuid::randomHex();

$repository->create([[
    'id' => $id,
    // add the rest of your entity payload here
]], $context);

If you are referencing existing entities (like currency, tax, language, sales channel), do not generate new UUIDs. Fetch and reuse the real IDs from the system.

Hex vs bytes: when you need to convert

You can stay in hex for most plugin development. Conversions matter mainly when you run raw SQL against binary UUID columns or handle byte arrays directly.

Convert hex UUID to bytes

use Shopware\Core\Framework\Uuid\Uuid;

$hexId = Uuid::randomHex();
$bytes = Uuid::fromHexToBytes($hexId);

Convert bytes back to hex

use Shopware\Core\Framework\Uuid\Uuid;

$hexAgain = Uuid::fromBytesToHex($bytes);

Common mistakes to avoid

• Generating random strings: Always use Shopware’s Uuid helper methods.
• Mixing hex and bytes: If a DB column is binary and you compare it with hex in SQL, your query will fail unless you convert.
• Generating IDs for existing entities: For relations, fetch and reuse existing IDs instead of creating new ones.
• Using UUIDs as business keys: UUIDs are identifiers, not meaningful business values. Use proper fields for business logic.