Evaluate replacing the fbp/fbc handling with facebook/capi-param-builder-php

[loevgaard]

Raised from review feedback on #39.

Meta ships facebook/capi-param-builder-php, which implements the _fbp and _fbc semantics this bundle currently reimplements. It already arrives transitively through facebook/php-business-sdk (1.3.1 at the time of writing).

What it gives us

Run against the vendored copy:

$b = new FacebookAds\ParamBuilder();
$cookies = $b->processRequest('www.example.com', ['fbclid' => 'IwAR1a-b_c'], ['_fbp' => 'fb.1.1657051589577.1088522659']);

// fbc: 'fb.1.1788781160733.IwAR1a-b_c.AQECAQMB'
// fbp: 'fb.1.1657051589577.1088522659.AQEAAQMB'
// cookie _fbc domain=example.com

• Canonical appendix handling, and the rules for when a cookie should be rewritten.
• eTLD+1 cookie domain resolution, which is exactly what Allow configuring the cookie domain for _fbp/_fbc #29 asks for.
• getClientIpAddress() and getEventSourceUrl() on top.
• processRequest($host, $queries, $cookies, $referer, $xForwardedFor, $remoteAddress) takes explicit arguments, so nothing reads $_GET or $_SERVER. It autoloads cleanly.

Adopting it would supersede most of #20, #28 and #29.

What it costs

• It becomes a direct require instead of a transitive one, so we own its version constraint.
• It targets PHP 7.4 and declares no parameter or return types. At PHPStan level max every call site needs narrowing.
• It is a whole-request abstraction: one call computes fbc, fbp, ip and source url together and returns the cookies to set. The bundle's Context classes are small decorators that a user can replace one at a time, which is a documented extension point.
• It deals in strings, not the SDK's Fbc/Fbp value objects. User::$fbc accepts string|Fbc|null so that works, but FbcContextInterface::getFbc(): ?Fbc and FbpContextInterface::getFbp(): Fbp would have to change.

Suggested approach

1. Decide whether the decorator based Context extension point is worth keeping. If it is, wrap the builder in a single ParamBuilderFbcContext / ParamBuilderFbpContext pair and leave the interfaces alone, converting the strings back into Fbc/Fbp.
2. If it is not, collapse Context/Fbc, Context/Fbp, StoreFbcSubscriber and StoreFbpSubscriber into one subscriber driving the builder, and change the interfaces to return strings.
3. Either way, add the direct require and confirm PHPStan stays clean at level max.

Worth checking against a live browser session first: whether fbevents.js writes the same five segment shape the builder does, so that a cookie written by one is read correctly by the other.