Problem/Motivation
Commerce 3.x supports Drupal ^10.3 || ^11. A new major, 4.x, is needed to support Drupal 12, drop Drupal 10, and remove code deprecated for removal in 4.0.0.
3.x remains supported for Drupal 10/11 sites. 4.x supports Drupal ^11.5 || ^12, so sites can upgrade Commerce on Drupal 11 first and move to Drupal 12 afterwards.
The minimum was raised from 11.1 to 11.5 in #3638820, since fixing Drupal 12 deprecations requires APIs introduced in 11.5.
Proposed resolution
Do the work in small, independently committable child issues listed below. This issue only tracks them.
Annotations vs attributes
- Every Commerce plugin type already provides an attribute class (since 3.x). This satisfies the Drupal 12 requirement that plugin types support attributes (change record).
- Annotated plugins (payment gateways, checkout panes, promotion offers, conditions, etc.) remain supported in 4.x, since Drupal core keeps annotation discovery until Drupal 13. Contrib modules should convert their plugins to attributes; this works on Commerce 3.x and 4.x alike.
- The Commerce plugin annotation classes will be deprecated in 4.x, and support for annotated Commerce plugins will be removed in 5.x.
- Commerce's own entity types will be converted to attributes. Entity type attributes require Drupal 11.1, which the 4.x minimum covers.
Remaining tasks
Must have
- #3638817: Require Drupal ^11.1 and PHP ^8.3 on 4.x, test against Drupal 12 in CI
- #3638818: Convert entity types to attributes
- #3638819: Remove code deprecated for removal in commerce:4.0.0
- #3638820: Fix Drupal 12 deprecations
- #3638856: Use text_long for the product body field on new installs
- #3639233: Drop the Inline Entity Form dependency
- #3639232: Add context services to build the pricing Context
- #3639234: Add checkout and update_cart order operations
- #3639235: Pass an optional Context to the address book
- #3639236: Add OrganizationInterface and an optional organization on the Context
- #3639243: Return a result object from conditions, promotions and coupons so failures can be explained (needs refinement; decide the BC strategy before 4.0.0)
- #3586548: Drupal 12 compatibility (lands last)
Nice to have
- #3638821: Deprecate Commerce plugin annotation classes in favor of attributes
- #3639772: Collect resolvers, checkers and processors with tagged iterators
4.x minor: B2B organization
Additive organization plumbing for B2B modules (commerce_b2b) to build on, using the 4.0 seams and organization API above. Child issues to be created; details are not final.
- Organization on orders and carts:
organization_idorder field (present once an organization entity type exists), one cart per user per organization, organization set on order assignment - Order ownership by uid only for orders without an organization
- Carts:
CartProviderscopes every lookup (getCart(),getCartId(),getCarts(),getCartIds()) to the organization resolved for the account and store it already receives, so the organization switcher changes which carts are returned and thecartcache context follows.CartProviderInterfacekeeps its signatures (no organization parameter: NULL would mean both "resolve it" and "personal cart"); code needing another organization's cart creates the order and callssetOrganization(). - The
organization_idfield on organization-owned entities (OrganizationOwnedInterface/OrganizationOwnedTraitship in 4.0.0, #3639236: Add OrganizationInterface and an optional organization on the Context):commerceadds anorganization_idbase field to every entity type implementing the interface (orders first; payment methods, invoices and subscriptions when their modules support organizations), targeting the site's organization entity type. Includes an install routine for when that type appears after install, and a guard that skips entity types already defining anorganization_id.OrganizationEntityTypeRepositorylives incommerce. - Order organization condition (is one of / is not one of)
The default organization entity type (commerce_organization) ships as an optional Commerce submodule: a minimal reference entity, so the plumbing is tested in core. Group sites use a bridge instead and do not install it.
No release containing the organization plumbing is tagged until commerce_b2b exercises it (memberships, resolver, access grants).
User interface changes
None expected.
API changes
Removal of deprecated code; see child issues. Annotated plugins keep working.
Code checking $cart->access('update') for customers moves to the new update_cart operation. Classes that built a Context with new Context() get the context services injected. AddressBookInterface implementations take the optional Context argument. Sites relying on Commerce to pull in Inline Entity Form must require it themselves. Context gains an optional organization, with OrganizationInterface and resolver interfaces for B2B modules to implement. OrderInterface extends the new OrganizationOwnedInterface (getOrganization(), getOrganizationId(), setOrganization()), so a custom class implementing OrderInterface without extending Order must add them (OrganizationOwnedTrait provides them).
Data model changes
None expected in 4.0. The organization plumbing (4.x minor) adds an organization_id field to entity types implementing OrganizationOwnedInterface (orders first), present once an organization entity type exists.
Comments
Comment #2
jsacksick commentedComment #3
jsacksick commentedComment #4
jsacksick commentedComment #5
jsacksick commentedComment #6
jsacksick commentedUpdated the summary: 4.x requires Drupal ^11.5 since #3638820 was merged.
Comment #7
jsacksick commentedActually... Realized now might be the time to drop the Inline entity form dependency since Commerce no longer depends on IEF anymore... And we couldn't really remove the dependency on Commerce 3.
Comment #8
jsacksick commentedComment #9
jsacksick commentedComment #10
jsacksick commentedComment #11
jsacksick commentedComment #12
rszrama commentedNoted today that we need to pick one of...
organization_idfields on all entity types that should be owned by an organization.commerce_organization_idorcommerce_org_id.CommerceOrganizationContentorCommerceOrganizationRelationship, and risk reimplementing half of Group in Commerce Core. 🫠Comment #13
rszrama commentedComment #14
jsacksick commentedWe're going with option 1, done generically. An entity owned by an organization carries
organization_id, likeuidfor user ownership, behind a newOrganizationOwnedInterface/OrganizationOwnedTraitincommerce(next toOrganizationInterface).commerce'shook_entity_base_field_info()adds the field to every entity type whose class implements the interface, targeting the site's organization entity type, and only when there is one. Orders come first; payment methods, invoices and subscriptions follow when their modules support organizations. Entity types Commerce doesn't own get the field from the module that needs it (commerce_b2b adds it to profiles for the organization address book), with no class swap.No prefix on Commerce's own entity types: it would break the
store_id/order_idconvention. Field UI fields can't collide (they'refield_…), and for custom base fields the hook and install routine skip any entity type that already has anorganization_idand report it in the status report. Entity types Commerce doesn't own (user, node) get acommerce_prefix, likecommerce_remote_idon users.Option 3 would mean rebuilding Group, and every access check and listing would pay for a join. The one many-to-many relationship, user ↔ organization with roles, is commerce_b2b's membership entity.
This stays a 4.x minor rather than 4.0.0. The parts that need a major are already 4.0.0 must-haves (#3639236: Add OrganizationInterface and an optional organization on the Context, #3639232: Add context services to build the pricing Context, #3639234: Add checkout and update_cart order operations, #3639235: Pass an optional Context to the address book). What's left is additive: without an organization entity type there's no field, and with one, existing orders have an empty value, so uid ownership, carts and checkout don't change until an organization module sets it. Keeping it out of 4.0.0 means Drupal 12 support doesn't wait on commerce_b2b.
Issue summary updated accordingly.
Comment #15
jsacksick commentedOrganizationOwnedInterface/OrganizationOwnedTraitmove to 4.0.0 in #3639236: Add OrganizationInterface and an optional organization on the Context:OrderInterfacegains their methods, which is cleaner in a major. Until the 4.x minor adds theorganization_idfield,getOrganization()returns NULL. Summary updated.Comment #16
jsacksick commentedSummary: documented how carts get scoped by organization in the 4.x minor.
CartProviderInterfacekeeps its signatures, which is what lets this stay out of 4.0.0.Comment #17
jsacksick commented