PHPackages                             aliasgar/module-customer-uuid - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Authentication & Authorization](/categories/authentication)
4. /
5. aliasgar/module-customer-uuid

ActiveMagento2-module[Authentication & Authorization](/categories/authentication)

aliasgar/module-customer-uuid
=============================

Adds an immutable, unique UUID attribute to Magento customers, exposed via GraphQL and the admin customer grid.

v1.0.0(1mo ago)001MITPHPPHP ~8.2.0||~8.3.0||~8.4.0||~8.5.0

Since Jun 11Pushed 1mo agoCompare

[ Source](https://github.com/bharmalaliasgar/module-customer-uuid)[ Packagist](https://packagist.org/packages/aliasgar/module-customer-uuid)[ RSS](/packages/aliasgar-module-customer-uuid/feed)WikiDiscussions main Synced 1w ago

READMEChangelogDependencies (5)Versions (2)Used By (0)

Aliasgar\_CustomerUuid
======================

[](#aliasgar_customeruuid)

Magento 2 extension that adds an **immutable, unique `uuid` attribute** to customers:

- Every customer (existing and new) is automatically assigned a UUID v4.
- Uniqueness is enforced by a **database-level unique index** — not just application validation.
- Exposed via **GraphQL** on the `Customer` object for authenticated customers.
- Shown as a column in the **admin customer grid** (sortable, filterable, searchable).
- **Read-only everywhere**: rendered as a disabled field on the admin customer edit form, and a server-side guard reverts any attempted change through any channel (admin, REST, GraphQL, legacy model saves).

Design rationale and trade-offs are documented in [DECISIONS.md](DECISIONS.md).

Requirements
------------

[](#requirements)

- Magento 2.4.x (developed and tested on 2.4.9 CE, PHP 8.5)
- `ramsey/uuid` ^4.7 (already a Magento core dependency)

Installation
------------

[](#installation)

### Option A — Packagist (recommended)

[](#option-a--packagist-recommended)

The package is published on [Packagist](https://packagist.org/packages/aliasgar/module-customer-uuid). No repository configuration is needed:

```
composer require aliasgar/module-customer-uuid:^1.0
```

### Option B — VCS (GitHub) without Packagist

[](#option-b--vcs-github-without-packagist)

```
composer config repositories.aliasgar-customer-uuid \
  vcs https://github.com/bharmalaliasgar/module-customer-uuid.git
composer require aliasgar/module-customer-uuid:^1.0
```

### Option C — Local path repository (for development in this docker-magento project)

[](#option-c--local-path-repository-for-development-in-this-docker-magento-project)

```
composer config repositories.aliasgar-customer-uuid \
  '{"type":"path","url":"packages/aliasgar/module-customer-uuid","options":{"symlink":true}}'
composer require aliasgar/module-customer-uuid:^1.0
```

Prefix all `composer` and `magento` commands with `bin/` when using the docker-magento wrappers.

### Enable and set up (all options)

[](#enable-and-set-up-all-options)

```
bin/magento module:enable Aliasgar_CustomerUuid
bin/magento setup:upgrade            # creates the column + attribute, backfills existing customers
bin/magento setup:di:compile
bin/magento cache:flush
bin/magento indexer:reindex customer_grid   # materializes the uuid column in the grid index
```

> The `customer_grid` reindex is required: the grid reads from the flat index table (`customer_grid_flat`) and Magento hides columns that are not physically present in it. The backfill patch invalidates the indexer; this command (or your cron) rebuilds it.

What `setup:upgrade` does
-------------------------

[](#what-setupupgrade-does)

1. **Declarative schema** adds a nullable `uuid` varchar(36) column to `customer_entity`with unique index `CUSTOMER_ENTITY_UUID`.
2. **`AddCustomerUuidAttribute` data patch** creates the `uuid` customer attribute (static backend, unique, grid-enabled, admin-form only).
3. **`BackfillCustomerUuid` data patch** assigns a UUID v4 to every existing customer in batches of 1000 using direct, memory-safe SQL.

API access
----------

[](#api-access)

### GraphQL

[](#graphql)

The `uuid` field is available on the `Customer` type. It requires a **customer token**(the core `customer` query rejects unauthenticated requests):

```
mutation {
  generateCustomerToken(email: "customer@example.com", password: "password123") {
    token
  }
}
```

```
curl -s http:///graphql \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer ' \
  -d '{"query":"{ customer { firstname email uuid } }"}'
```

```
{"data": {"customer": {"firstname": "Veronica", "email": "...", "uuid": "afdbadb4-b3e3-4780-80df-80f7f2307669"}}}
```

### REST

[](#rest)

Because the attribute is a regular (non-system) customer attribute, it also appears in REST responses under `custom_attributes`:

```
GET /rest/V1/customers/me            (customer token)
GET /rest/V1/customers/:id           (admin token)

```

Sending a different `uuid` value in a `PUT /V1/customers/:id` payload is silently reverted to the stored value — the attribute is immutable by design.

Read-only behavior
------------------

[](#read-only-behavior)

ChannelBehaviorAdmin customer gridVisible column (filter/search/sort)Admin customer edit formVisible, disabled (greyed out)Storefront account formsNot present at allRepository / REST / GraphQL writesStored value always wins; tampered values revertedLegacy `$customer->save()` model saves`customer_save_before` observer enforces the same ruleTesting
-------

[](#testing)

A detailed step-by-step guide (one-time setup, expected output, troubleshooting) is in [how-to.md](how-to.md). Quick reference:

### Unit tests

[](#unit-tests)

```
bin/cli vendor/bin/phpunit -c dev/tests/unit/phpunit.xml.dist \
  vendor/aliasgar/module-customer-uuid/Test/Unit
```

### Integration tests

[](#integration-tests)

One-time setup in this docker-magento project (creates the `magento_integration_tests`database and installs the test config):

```
make setup-integration-tests
```

Then:

```
bin/dev-test-run integration ../../../vendor/aliasgar/module-customer-uuid/Test/Integration
```

> Explicit paths are required in both cases: Magento's `phpunit.xml.dist` test suites only scan `app/code/*/*/Test/*`, so tests inside composer-installed (vendor) modules are not auto-discovered.

Coverage:

- **Unit**: UUID v4 format/randomness, repository plugin behavior (assign on create, revert on tamper), UuidManager resolution order (stored > candidate > generated).
- **Integration**: attribute configuration (static/unique/grid flags/non-system/forms), automatic assignment through the repository, immutability through the repository, backfill of pre-existing rows, the DB unique constraint itself, and NULL tolerance of the unique index.

GraphQL end-to-end coverage belongs in Magento's `dev/tests/api-functional` suite, which this environment does not wire up; the resolver is deliberately thin (one guarded array access) and is exercised manually with the query above.

Uninstall
---------

[](#uninstall)

```
bin/magento module:disable Aliasgar_CustomerUuid
composer remove aliasgar/module-customer-uuid
bin/magento setup:upgrade
```

Note: declarative schema will drop the `uuid` column (and its data) once the module's `db_schema.xml` is removed and `setup:upgrade` runs.

###  Health Score

39

—

LowBetter than 84% of packages

Maintenance90

Actively maintained with recent releases

Popularity1

Limited adoption so far

Community7

Small or concentrated contributor base

Maturity51

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Unknown

Total

1

Last Release

46d ago

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/33605994?v=4)[Ali](/maintainers/bharmalaliasgar)[@bharmalaliasgar](https://github.com/bharmalaliasgar)

---

Top Contributors

[![bharmalaliasgar](https://avatars.githubusercontent.com/u/33605994?v=4)](https://github.com/bharmalaliasgar "bharmalaliasgar (1 commits)")

### Embed Badge

![Health badge](/badges/aliasgar-module-customer-uuid/health.svg)

```
[![Health](https://phpackages.com/badges/aliasgar-module-customer-uuid/health.svg)](https://phpackages.com/packages/aliasgar-module-customer-uuid)
```

###  Alternatives

[mollie/magento2

Mollie Payment Module for Magento 2

1131.9M16](/packages/mollie-magento2)[directorytree/ldaprecord-laravel

LDAP Authentication & Management for Laravel.

5752.3M21](/packages/directorytree-ldaprecord-laravel)[buckaroo/magento2

Buckaroo Magento 2 extension

32420.3k8](/packages/buckaroo-magento2)[loki/magento2-components

Core module for defining Alpine.js components with advanced AJAX features

1011.8k26](/packages/loki-magento2-components)[imi/magento2-friendly-captcha

Friendly Captcha integration for Magento2

19131.4k](/packages/imi-magento2-friendly-captcha)[loki/magento2-admin-components

Admin Panel grids and forms created via Loki Components

175.2k7](/packages/loki-magento2-admin-components)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)