API - State Providers Structure

• Status: Accepted
• Date: 2024-07-15

In effect from version: 2.0

Related PRs: #16567

Context and Problem Stratement

Until version 2.0, we supported API Platform version 2, which utilized DataProviders to deliver data to the API. These DataProviders were all located within the Sylius\Bundle\ApiBundle\DataProvider directory. This structure lacked differentiation between the admin and shop sections and did not provide clear organization for individual resources. As a result, it became challenging to manage and maintain the codebase as the number of providers grew.

With Sylius 2.0, the API Platform has been upgraded to version 3. One of the significant changes in API Platform 3 is the shift from DataProviders to StateProviders. This change necessitates a reconsideration of how we organize and structure our data-providing classes to ensure clarity, maintainability, and scalability.

Decision Drivers

• Moving from DataProviders to StateProviders
• Clear separation between admin and shop providers
• Clear separation between resources

Considered Options

Leave all StateProviders in one directory

• Good, because:
  • Less to refactor
• Bad, because:
  • Hard to see which provider is for admin and which for shop

Separate StateProviders by resource

• Good, because:
  • Clear separation between resources
• Bad, because:
  • Need to refactor all providers
  • Hard to see which provider is for admin and which for shop

Separate StateProviders by sections

• Good, because:
  • Clear separation between admin and shop providers
• Bad, because:
  • Need to refactor all providers
  • A lot of providers in one directory

Separate StateProviders by sections and resources

• Good, because:
  • Clear separation between admin and shop providers
  • Clear separation between resources
• Bad, because:
  • Need to refactor all providers

Decision Outcome

Chosen option: Separate StateProviders by sections and resources, because it provides a clear and manageable way to organize state providers.

New Structure:

/StateProvider
    /Admin
        /Order
            ItemProvider.php
        /Product
            ItemProvider.php
            CollectionProvider.php
    /Shop
        /Order
            ItemProvider.php
            CollectionProvider.php
        /Product
            CollectionProvider.php
    /Common
        /Adjustment
            CollectionProvider.php

Providers for Command classes should be placed in the relevant resource directory and named with a Provider suffix, e.g., /StateProvider/Shop/ShopUser/ResetPasswordProvider.php for the ResetPassword command.