<commit_before># Httplug HTTP client abstraction

Httplug is an abstraction for HTTP clients. There are two main use cases:

1. Usage in a project
2. Usage in a reusable package

In both cases, the client provides a `sendRequest` method to send a PSR-7 `RequestInterface` and returns a PSR-7 `ResponseInterface` or throws an exception that implements `Http\Client\Exception`.

See the [tutorial](tutorial.md) for a concrete example.


## Httplug implementations

Httplug implementations typically are either HTTP clients of their own, or they are adapters wrapping existing clients like Guzzle 6. In the latter case, they will depend on the required client implementation, so you only need to require the adapter and not the actual client.

See [packagist](https://packagist.org/providers/php-http/client-implementation) for the full list of implementations.

Note: Until Httplug 1.0 becomes stable, we will focus on the Guzzle6 adapter.

## Usage in a project

When writing an application, you should require a concrete client implementation. The client will in turn depend on `php-http/httplug`.

A few things should be taken into consideration before choosing an adapter:

- It is possible that some other dependency already has an HTTP Client requirement like Guzzle 6. It can be confusing to have more than one HTTP Client installed, so always check your other requirements and choose an adapter based on that.


## Installation in a reusable package

In many cases, packages are designed to be reused from the very beginning. For example, API clients are usually used in other packages/applications, not on their own.

In these cases, they should **not rely on a concrete implementation** (like Guzzle 6), but only require any implementation of Httplug. Httplug uses the concept of virtual packages. Instead of depending on only the interfaces, which would be missing an implementation, or depending on one concrete implementation, you should depend on the virtual package `php-http/client-implementation`. There is no package with that name, but all clients and adapters implementing Httplug declare that they provide this virtual package.

You need to edit the `composer.json` of your package to add the virtual package. For development (installing the package standalone, running tests), add a concrete implementation in the `require-dev` section to make the project installable:

``` json
...
"require": { 
    "php-http/client-implementation": "^1.0" 
}, 
"require-dev": { <commit_msg>clarify that you do not need to require the interfaces explicitly when requiring an implementation<commit_after># Httplug HTTP client abstraction

Httplug is an abstraction for HTTP clients. There are two main use cases:

1. Usage in a project
2. Usage in a reusable package

In both cases, the client provides a `sendRequest` method to send a PSR-7 `RequestInterface` and returns a PSR-7 `ResponseInterface` or throws an exception that implements `Http\Client\Exception`.

See the [tutorial](tutorial.md) for a concrete example.


## Httplug implementations

Httplug implementations typically are either HTTP clients of their own, or they are adapters wrapping existing clients like Guzzle 6. In the latter case, they will depend on the required client implementation, so you only need to require the adapter and not the actual client.

See [packagist](https://packagist.org/providers/php-http/client-implementation) for the full list of implementations.

Note: Until Httplug 1.0 becomes stable, we will focus on the Guzzle6 adapter.

## Usage in a project

When writing an application, you need to require a concrete [client implementation](https://packagist.org/providers/php-http/client-implementation). The client will in turn depend on `php-http/httplug`, thus you do not need to duplicate the dependency on `php-http/httplug` in your composer.json file. However, if your code depends on a minimal version of Httplug, specify it to have composer report problems rather than the application failing at some point.

Choose the client based on your personal preferences or dependencies of your project. If your preferred client has no Httplug adapter, submit one.


## Installation in a reusable package

In many cases, packages are designed to be reused from the very beginning. For example, API clients are usually used in other packages/applications, not on their own.

In these cases, they should **not rely on a concrete implementation** (like Guzzle 6), but only require any implementation of Httplug. Httplug uses the concept of virtual packages. Instead of depending on only the interfaces, which would be missing an implementation, or depending on one concrete implementation, you should depend on the virtual package `php-http/client-implementation`. There is no package with that name, but all clients and adapters implementing Httplug declare that they provide this virtual package.

You need to edit the `composer.json` of your package to add the virtual package. For development (installing the package standalone, running tests), add a concrete implementation in the `require-dev` section to make the project installable:

``` json
...
"require": { 
    "php-http/client-implementation": "^1.0" 
}, 
"require-dev": { 
{'fraction_non_alphanumeric': 0.05543873064423628, 'fraction_numerical': 0.00439686484419805, 'mean_word_length': 4.711790393013101, 'pattern_counts': {'":': 6, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 3, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '6150912', 'n_tokens_mistral': 1303, 'n_tokens_neox': 1231, 'n_words': 734}