Feature | Improve working with queries

[aerni]

This PR provides a couple of improvements around working with queries:

• It adds the ability to define custom query builders
• It adds the ability to work with queries fluently

Custom Query Builder

Defining a custom query builder works similar to defining a custom response. Providing your own query builder allows you to add methods that mirror the supported parameters of the API you're working with. It's also super helpful for autocompletion in your code editor.

Custom query builders are simply extending the Saloon\Repositories\ArrayStore that is already being used for queries. This ensures a non-breaking change.

A simple example of a custom query builder:

use Saloon\Repositories\ArrayStore;

class CloudflareStreamQueryBuilder extends ArrayStore
{
    public function limit(int $limit): self
    {
        $this->add('limit', $limit);

        return $this;
    }
}

How you'd register the query builder on a connector or request:

class CloudflareStreamRequest extends Request
{
    protected string $queryBuilder = CloudflareStreamQueryBuilder::class;
}

How you'd use the query builder:

$request->query()->limit(5)->add('foo', 'bar');

Fluent Query Builder

A new fluentQuery() method makes working with queries a little smoother.

From this:

$connector = new CloudflareConnector();

$connector->query()->limit(5)->add('foo', 'bar');
  
$connector->send($request);

To this:

new CloudflareConnector()
    ->fluentQuery(fn ($query) => $query->limit(5)->add('foo', 'bar'))
    ->send($request);

I'd prefer to simplify things and merge the logic of the fluentQuery() method with the query() method. But that would require a method signature change and be a breaking change. I'll leave this decision up to you.

Feature Request: Queries on resources

I'd love to make queries even more powerful by adding support for resources. This would be super powerful for building SDKs. Consider the following scenario, where you've got different resources that each need their own query builder class. Currently, you can only set the query builder on the connector, which sets the query builder for all resources. Or on each request directly, which can be a little tedious.

This is what I'd love to see:

class CloudflareConnector extends Connector
{
    public function video(): VideoResource
    {
        return new VideoResource($this);
    }

    public function audio(): AudioResource
    {
        return new AudioResource($this);
    }
}

class VideoResource extends BaseResource
{
    protected string $queryBuilder = VideoQueryBuilder::class;
}

class AudioResource extends BaseResource
{
    protected string $queryBuilder = AudioQueryBuilder::class;
}

Then you can use it like this:

new CloudflareConnector()
    ->video()
    ->fluentQuery(fn (VideoQueryBuilder $query) => $query->limit(5)->add('foo', 'bar'))
    ->all()

I hope this all makes sense. Thanks for your work on Saloon!