Revamp ApiSubresource

[vincentchalamon]

Q	A
Bug fix?	no
New feature?	yes
BC breaks?	yes
Deprecations?	yes
Tickets	fixes #2706, #1628, #3177
License	MIT
Doc PR	TODO

• ADR document
• Add support for the new path attribute on ApiResource
• Allow setting ApiResource several times (annotation, xml and yaml formats)
• Patch the ApiLoader to use it
• Patch the IRI Converter to use it
• Patch the DataProviders to use it
• Patch the GraphQL subsystem to use it
• Patch the DataPersisters to use it
• Patch the DocumentationNormalizers to use it
• Add doc PR
• Deprecate the old ApiSubresource subsystem

Examples:

/**
 * @ApiResource(path="/users")
 * @ApiResource(path="/companies/{companyId}/users", identifiers={"companyId": {Company::class, "id"})
 * @ApiResource(path="/companies/{companyId}/users")
 * @ApiResource(path="/countries/{countryId}/companies/{companyId}/users", identifiers={"companyId": {Company::class, "id"}, "countryId": {Country::class, "id"}})
 *
 * @ApiResource(path="/companies/{companyId}/administrators", identifiers={"companyId": {Company::class, "id"}, "??": {CompanyClass, "administrators"}})
 * @ApiResource(path="/companies/{companyId}/employees", identifiers={"companyId": {Company::class, "id"}, "??": {CompanyClass, "employees"}})
 */

[soyuka]

I think we should base this branch over the #3664 now.

The next thing to do is to "merge" the behavior of both identifiedBy and identifiers on the subresource's metadata.
At the end, the following parts should be removed:

core/src/DataProvider/OperationDataProviderTrait.php

Lines 79 to 88 in c187f36

	$subresourceIdentifiers = [];
	foreach ($attributes['subresource_context']['identifiers'] as list($identifier, , $isItem, $identifiedBy)) {
	if ($isItem) {
	$subresourceIdentifiers[$identifier] = [$identifiedBy[0] => current($identifiers)];
	next($identifiers);
	continue;
	}
	$subresourceIdentifiers[$identifier] = [];
	}

core/src/DataProvider/OperationDataProviderTrait.php

Lines 103 to 112 in c187f36

	if (isset($attributes['subresource_context'])) {
	$subresourceIdentifiersKeys = [];
	$i = 0;
	foreach ($attributes['subresource_context']['identifiers'] as list($identifier, , $isItem)) {
	if ($isItem) {
	$subresourceIdentifiersKeys[] = $identifiersKeys[$i++] ?? $identifier;
	}
	}
	$identifiersKeys = $subresourceIdentifiersKeys;
	}

.

[jamesisaac]

Would this address #3177 ? Haven't seen it mentioned specifically in the linked issues, but that's quite a big downside currently to Subresources vs normal ApiResources.

[vincentchalamon]

@jamesisaac I think it'll fix this issue too, cause the subresources will be deprecated in favor of multiple ApiResources. So in final, the security option of ApiResource will be used.