Skip to content

Migrate package enums to native PHP backed enums - #483

Open
JonPurvis wants to merge 2 commits into
Kyon147:masterfrom
JonPurvis:update/use-native-enums
Open

Migrate package enums to native PHP backed enums#483
JonPurvis wants to merge 2 commits into
Kyon147:masterfrom
JonPurvis:update/use-native-enums

Conversation

@JonPurvis

@JonPurvis JonPurvis commented May 10, 2026

Copy link
Copy Markdown
Collaborator

This PR replaces EnumTrait classes, from the funeralzone/valueobjects package, with native PHP backed enums that were introduced in PHP 8.1, now that the package requires that version as a minimum. We still require funeralzone/valueobjects for Value objects (ShopId, AccessToken, ShopDomain, etc.). There's multiple reasons we should do this:

  • Less dependency surface
  • Better tooling
  • Clearer semantics
  • Aligned with Laravel
  • Future-proof

This change will most likely have to be a major version bump. If apps reference enums directly, then they will break (update instructions at the bottom of this comment)!

Changes

  • All 11 enum classes are now native backed enums (string or int backing as appropriate)
  • References updated throughout the package:
    • ChargeStatus::ACTIVE() is now ChargeStatus::ACTIVE
    • $enum->toNative() is now $enum->value
    • $a->isSame($b) is now $a === $b
  • UPPERCASE case names preserved (e.g. ChargeStatus::ACTIVE, not Active) to minimise breaking changes. Whilst the general consensus is that enums should be CamelCase, I didn't think it was worth changing this.
  • fromNative() kept but marked @deprecated on all enums. Folks should use Enum::from() / Enum::tryFrom() going forward. fromNative() could be removed in a later version.
  • ChargeStatus::fromShopifyApiStatus() retained as a domain helper

Backing values

Enum ->value matches legacy toNative() output (constant name strings), not the old internal int constants.

Enum Backing Example ->value
ChargeStatus, PlanType, AuthMode, etc. string "ACTIVE", "RECURRING"
ThemeSupportLevel, SessionTokenSource int 0, 1, 2

Breaking changes

Apps that reference package enums directly will need to update:

Before After
ChargeStatus::ACTIVE() ChargeStatus::ACTIVE
$status->toNative() $status->value
$a->isSame($b) $a === $b
ChargeStatus::fromNative('ACTIVE') ChargeStatus::from('ACTIVE') (deprecated shim still works for now)

@JonPurvis JonPurvis changed the title Use Native PHP Enums Migrate package enums to native PHP backed enums Jun 13, 2026
@JonPurvis
JonPurvis marked this pull request as ready for review June 13, 2026 15:48
@JonPurvis
JonPurvis requested a review from Kyon147 June 13, 2026 15:48
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant