README

Shopware 提供了一个 Store API，可以以无头方式访问通过店面通常提供的内容。文档可以在这里找到：[https://shopware.stoplight.io/docs/store-api/branches/v6.5/38777d33d92dc-quick-start-guide](https://shopware.stoplight.io/docs/store-api/branches/v6.5/38777d33d92dc-quick-start-guide)（适用于 Shopware 6.5）。

Shopware 提供了一个用于使用 Store API 的 JS 库：[https://shopware.stoplight.io/docs/store-api/branches/v6.5/90222a7851d2a-javascript-sd-ks](https://shopware.stoplight.io/docs/store-api/branches/v6.5/90222a7851d2a-javascript-sd-ks)

目前，Shopware 没有提供 PHP 库。其他库部分或全部由 Store API 文档生成，文档可以在这里找到：[https://github.com/shopware/store-api-reference](https://github.com/shopware/store-api-reference)。然而，文档中存在许多错误：错误的响应代码、错误的数据结构文档以及缺少可空性声明。尽管 Store API 客户端的明显用途是与 Store API 一起使用，但它也提供了数据结构和响应代码的类型安全（但不一定完整和正确）的文档。

安装

可以通过 composer 安装客户端。

composer require it-bens/shopware-store-api-client

用法

此包为 Store API 的不同部分提供了多个客户端。它们在初始化期间共享相同的依赖项，使用相同的处理流程，并在出错时抛出相同的异常。稍后显示的功能。

初始化

以 CartClient 为例展示客户端初始化。

use ITB\ShopwareStoreApiClient\RequestBuilder;
use ITB\ShopwareStoreApiClient\Auth\AccessTokenProvider\WithStaticAccessToken as AccessTokenProviderWithStaticAccessToken;
use ITB\ShopwareStoreApiClient\Tests\E2E\Helper\Psr18Client;
use Symfony\Component\Serializer\Serializer;
use ITB\ShopwareStoreApiClient\CartClient;

$shopwareStoreUrl = 'https://example.shopware.com';
$requestBuilder = new RequestBuilder();
$accessTokenProvider = new AccessTokenProviderWithStaticAccessToken('WYFFSAEAFGWEG');
$httpClient = new Psr18Client();
$serializer = new Serializer(...); // The symfony serializer initialization is a lot more complex. It will be shown later.
$responseProcessor = new ResponseProcessor($serializer);

$cartsClient = new CartClient(
    $shopwareStoreUrl,
    $requestBuilder,
    $accessTokenProvider,
    $httpClient,
    $serializer,
    $responseProcessor
);

访问令牌提供者

Shopware 销售渠道需要在请求头中包含访问令牌。 AccessTokenProvider 是一个旨在在运行时提供 AccessToken 对象的接口。 WithStaticAccessToken 类是这个接口最简单的实现。访问令牌只是存储在对象内部。其他实现可能从其他来源获取访问令牌。

销售渠道的访问令牌不会自行更改，因此通常“静态”用法就足够了。

HTTP 客户端

此包使用 PSR-18 标准的 HTTP 客户端。在 E2E 测试中使用的是 symfony 版本的此客户端。然而，任何 PSR-18 兼容的实现都可以使用。请随意使用您喜欢的。

序列化器

symfony 序列化器用于将 Store API 的响应反序列化为严格类型（尽可能）的数据结构。在使用 symfony 框架扩展的项目中，序列化器已经可用。只需从本包中添加一些自定义正常化程序即可。

但是，如果您不使用 symfony 框架，则必须自行初始化序列化器。

use Symfony\Component\Serializer\Encoder\JsonEncoder;
use Symfony\Component\PropertyInfo\Extractor\PhpDocExtractor;
use Symfony\Component\PropertyInfo\Extractor\ReflectionExtractor;
use Symfony\Component\PropertyInfo\PropertyInfoExtractor;
use Symfony\Component\Serializer\Mapping\Loader\AttributeLoader;
use Symfony\Component\Serializer\Mapping\Factory\ClassMetadataFactory;
use Symfony\Component\Serializer\Mapping\ClassDiscriminatorFromClassMetadata;
use ITB\ShopwareStoreApiClient\ModelNormalizer\CustomerAddressNormalizer;
use ITB\ShopwareStoreApiClient\ModelNormalizer\OrderStateNormalizer;
use ITB\ShopwareStoreApiClient\ModelNormalizer\DeliveryStateNormalizer;
use ITB\ShopwareStoreApiClient\ModelNormalizer\TransactionStateNormalizer;
use ITB\ShopwareStoreApiClient\ModelNormalizer\ContextSourceNormalizer;
use ITB\ShopwareStoreApiClient\ModelNormalizer\OrderCollectionNormalizer;
use Symfony\Component\Serializer\Normalizer\ObjectNormalizer;
use Symfony\Component\PropertyAccess\PropertyAccess;
use Symfony\Component\Serializer\Normalizer\BackedEnumNormalizer;
use Symfony\Component\Serializer\Normalizer\ArrayDenormalizer;
use Symfony\Component\Serializer\Serializer;

$encoders = [new JsonEncoder()];

$phpDocExtractor = new PhpDocExtractor(); // required to detect array types
$reflectionExtractor = new ReflectionExtractor(); // required to detect constructor arguments
$propertyInfoExtractor = new PropertyInfoExtractor(
    listExtractors: [$reflectionExtractor],
    typeExtractors: [$phpDocExtractor, $reflectionExtractor],
    descriptionExtractors: [$phpDocExtractor],
    accessExtractors: [$reflectionExtractor],
    initializableExtractors: [$reflectionExtractor]
);

$classMetadataFactory = new ClassMetadataFactory(new AttributeLoader()); // required to detect discriminator mappings
$discriminator = new ClassDiscriminatorFromClassMetadata($classMetadataFactory);

// custom normalizers / denormalizers (some of the require the serializer itself because they only prepare the data for the deserialization process)
$customerAddressNormalizer = new CustomerAddressNormalizer();
$orderStateNormalizer = new OrderStateNormalizer();
$deliveryStateNormalizer = new DeliveryStateNormalizer();
$transactionStateNormalizer = new TransactionStateNormalizer();
$contextSourceNormalizer = new ContextSourceNormalizer();
$orderCollectionNormalizer = new OrderCollectionNormalizer();

$objectNormalizer = new ObjectNormalizer(
    classMetadataFactory: $classMetadataFactory,
    propertyAccessor: PropertyAccess::createPropertyAccessor(),
    propertyTypeExtractor: $propertyInfoExtractor,
    classDiscriminatorResolver: $discriminator
);

$normalizers = [
    $customerAddressNormalizer,
    $orderStateNormalizer,
    $deliveryStateNormalizer,
    $transactionStateNormalizer,
    $contextSourceNormalizer,
    $orderCollectionNormalizer,
    new BackedEnumNormalizer(),
    new ArrayDenormalizer(),
    $objectNormalizer, // the object normalizer will try to denormalize everything without any specific logic, so it should be the last one in the list
];

$serializer = new Serializer($normalizers, $encoders);

$customerAddressNormalizer->setDenormalizer($serializer);
$customerAddressNormalizer->setNormalizer($serializer);
$orderStateNormalizer->setDenormalizer($serializer);
$deliveryStateNormalizer->setDenormalizer($serializer);
$transactionStateNormalizer->setDenormalizer($serializer);

API 函数

上下文令牌提供者

上下文令牌标识 Shopware 中的客户（会话）。它作为头信息传输，就像访问令牌一样。并非所有 API 函数都需要上下文令牌。《ContextTokenProvider》是一个旨在在运行时提供上下文令牌的接口。此包提供了两个实现：《WithAnonymousUser》和《WithAuthenticatedUser》。

匿名用户

《WithAnonymousUser》类使用《/store-api/context》路由来获取或创建上下文令牌，无需任何登录。提供者存储上下文令牌，直到调用《resetContextToken》方法。

认证用户

WithAuthenticatedUser 类在创建时接收客户凭据，并使用 /store-api/account/login 路由进行登录。上下文令牌由 Shopware 返回。直到调用 resetContextToken 方法，提供者会存储上下文令牌。

搜索条件

Shopware 通过 API 提供了非常强大的搜索功能（不是产品搜索）。有关选项的文档在此：https://shopware.stoplight.io/docs/store-api/branches/v6.5/cf710bf73d0cd-search-queries。这个包使用 SearchCriteria 类描述了搜索数据结构。

它还包括两个不一致记录的选项：fields 和 includes。虽然 fields 选项在 Store API 中有记录，但 includes 选项在 Admin API 中有记录。它们似乎具有相同的目的，但格式和内部处理方式不同。fields 选项限制 Shopware 从数据库查询的字段（关联被视为）。限制查询的字段可以大幅提高性能！此选项接受一个字符串数组。点用作字段分隔符。includes 选项限制响应中返回的字段（但它们仍然被查询）。此选项接受一个递归关联数组。键是 API/实体别名。值可以是字符串数组或另一个关联数组。联合使用 fields 和 includes 选项可以提供最大的性能提升。

地址客户端

购物车客户端

所有与行项目相关的函数都需要一个 LineItemCollection。它包含 LineItem 实现。目前存在三个 LineItem 实现：ProductLineItem、PromotionLineItem 和 LineItemReference。前两个应该是显而易见的。最后一个用于引用行项目，可以用于从购物车中删除行项目。《CustomLineItem》实现计划。Shopware 内部支持折扣行项目，但它们在 Store API 中不受支持，主要通过插件使用。

Cart 对象包含一个 Error 对象数组。名称具有误导性，因为 Shopware 使用它们来表示错误、警告和通知。目前，此包仅支持少数类型。随着测试或在此包中使用，将添加更多类型。欢迎贡献和问题。

上下文客户端

上下文包含有关当前客户（会话）的许多信息。更新上下文是更改结账过程中使用的地址、支付方式和运输方式指定的方式。

订单客户端

如果 Shopware 对购物车数据有投诉，createOrderFromCart 方法将抛出异常。抛出的 RequestExceptionWithHttpStatusCode 提供一个 getErrors 方法，该方法应提供 Shopware 返回的所有错误。

贡献

我非常高兴软件开发社区喜欢开源，就像我一样！♥

因此，我感谢每个打开的问题（最好是建设性的）和每个提供其他甚至更好代码的拉取请求。

你们都是令人惊叹的！