feat: introduce transformRelated() for smart and isolated relationship transformations

[datamweb]

Description
This PR introduces a new method transformRelated(), to the BaseTransformer class to solve the Global State Leakage issue when transforming nested/related resources, and to simplify the developer experience.

Previously, the documentation instructed developers to manually instantiate transformers for included resources:

return (new PostTransformer())->transformMany($posts);

This approach caused a significant issue: if a request contained query parameters like ?include= or ?fields=, those global states could unintentionally leak into the child transformers, leading to incorrect field filtering, infinite loops, or ApiExceptions.

Checklist:

• Securely signed commits
• Component(s) with PHPDoc blocks, only if necessary or adds value (without duplication)
• Unit testing, with >80% coverage
• User guide updated
• Conforms to style guide

[michalsn]

This approach caused a significant issue: if a request contained query parameters like ?include= or ?fields=, those global states could unintentionally leak into the child transformers, leading to incorrect field filtering, infinite loops, or ApiExceptions.

Shouldn't the behavior of transformMany() be treated as a bug and fixed?

[datamweb]

Shouldn't the behavior of transformMany() be treated as a bug and fixed?

@michalsn The issue actually isn't inside transformMany(). The leakage happens the moment we instantiate the new transformer.

If the URL is /users?include=comments:

// The leak happens right here, before transformMany() is even called!
$transformer = new CommentTransformer(); 

Because we don’t pass a custom $request to the constructor, it automatically grabs the global Services::request(). This global request still contains include=comments, which infects the child transformer.
If we change how BaseTransformer or transformMany() handles the global request, we might break existing applications that accidentally or intentionally rely on this behavior.
And transformRelated() doesn’t just fix the leak. It also saves developers from checks to decide whether to call transform() (for single items) or transformMany() (for collections).

[datamweb]

On a related note, one of the main reasons I was so keen on introducing transformRelated() to isolate the state is that it lays the perfect architectural groundwork for an advanced feature I'd love to see in the future, Scoped Field Filtering.

Right now, if we want to support advanced API queries like:

/users?include=comments,posts&fields[posts]=id,slug

Handling this with the old architecture would have been a nightmare because the global state leakage made child transformers unpredictable. However, now that transformRelated() provides a clean, isolated boundary for child instantiation, extending this method in the future to parse and pass targeted scopes/fields directly to the child transformer will be incredibly straightforward and safe.

[michalsn]

Okay, I looked into the actual code. While this new method can be really handy as API sugar, which we can promote as the default method to use, this doesn't really fix the underlying problem.

I will try to prepare something as a bugfix targeting the develop branch.