Add SearchProductsForFreeGift Admin API endpoint

[PrestaEdit]

Questions	Answers
Branch?	dev
Description?	Adds GET /products/free-gift-candidates?phrase=[&limit=] using CQRSGetCollection with SearchProductsForFreeGift. Uses [_context][langId] and [_context][shopId] mappings to auto-fill the two required scoping args from the API client context. Response items: productId, name, reference, imagePath, productType, disabled, disabledReason.
Type?	new feature
Category?	CO
BC breaks?	no
Deprecations?	no
Fixed ticket?	Related to PrestaShop/PrestaShop#39630
How to test?	Run composer phpunit-integration; FreeGiftCandidateEndpointTest searches for hum against the demo catalog (Hummingbird products).

⚠️ Depends on PR #220 — SearchProductsForFreeGift was introduced in PS 9.1+/develop and does not exist at the 9.0.3 tag. The 9.0.3 CI matrix legs will fail here until #220 (drop 9.0.3 from CI) lands.

[mattgoud]

A couple of real defects here beyond the CI-matrix dependency:

1. disabledReason must be nullable. The core DTO getter is ProductForFreeGift::getDisabledReason(): ?string and the handler returns null for eligible products (return [false, null];). The resource declares public string $disabledReason; (non-nullable), so denormalizing an eligible product throws The type of the "disabledReason" attribute must be "string", "NULL" given. → HTTP 500. This is why the develop/9.2.x integration legs are red. Fix: public ?string $disabledReason;.

2. imagePath doesn't map to the DTO. The DTO exposes getImageUrl() (key imageUrl), not imagePath, and there's no ApiResourceMapping, so imagePath is never populated (currently masked by defect #1). Rename the property to imageUrl, or add ApiResourceMapping ['[imagePath]' => '[imageUrl]'].

3. Dependency is under-stated. SearchProductsForFreeGift was introduced in 9.2.x/develop only (commit 7212d79) — it does not exist in 9.1.x. #220 drops only 9.0.3, so PHPStan(9.1.x) and the 9.1.x integration legs stay red after it merges. Either also drop 9.1.x from the matrix, or gate the resource on class_exists.

Nit: the happy-path test doesn't assert a non-empty result set and doesn't cover imagePath/reference/disabledReason, so it wouldn't have caught #1 or #2. Worth asserting at least one row with all declared fields.

[jolelievre]

Closing in favor of #410, which centralizes all the pending Product-domain endpoints into a single PR: mutualizing the changes makes the review simpler, and it allowed rebuilding the integration tests so that every fixture is created through the API alone (with whole-structure assertions). @PrestaEdit your work is kept and you are co-authored on the commits of #410 — thanks!

Note: #410 also fixes the nullable disabledReason (it caused a 500 for eligible products), exposes imageUrl and reference, and gates the operation with minVersion 9.2.0 since SearchProductsForFreeGift only exists since PrestaShop 9.2.