Skip to content

Improve documentation #13

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Feb 20, 2019
Merged

Improve documentation #13

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
56 changes: 43 additions & 13 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -63,8 +63,26 @@ $browser = new Clue\React\Buzz\Browser($loop);
$client = new Client($browser);
```

If you need custom DNS, SSL/TLS or proxy settings, you can explicitly pass a
custom [`Browser`](https://github.com/clue/reactphp-buzz#browser) instance.
If you need custom connector settings (DNS resolution, TLS parameters, timeouts,
proxy servers etc.), you can explicitly pass a custom instance of the
[`ConnectorInterface`](https://github.com/reactphp/socket#connectorinterface)
to the [`Browser`](https://github.com/clue/reactphp-buzz#browser) instance:

```php
$connector = new \React\Socket\Connector($loop, array(
'dns' => '127.0.0.1',
'tcp' => array(
'bindto' => '192.168.10.1:0'
),
'tls' => array(
'verify_peer' => false,
'verify_peer_name' => false
)
));

$browser = new Browser($loop, $connector);
$client = new Client($browser);
```

#### Promises

Expand All @@ -76,21 +94,27 @@ Sending requests uses a [Promise](https://github.com/reactphp/promise)-based int

#### search()

The `search($query, $filters = array())` method can be used to search packages matching the given query string and optionally matching the given filter parameter.
It resolves with an array containing zero or more `Package` objects.
The `search(string $query, array $filters = array()): PromiseInterface<Package[],Exception>` method can be used to
search packages matching the given query string and optionally matching the given filter parameter.

It resolves with an array containing zero or more [`Package`](#package) objects
on success or rejects with an `Exception` on error.

```php
$client->search('packagist')->then(function ($results) {
foreach ($results as $result) {
$client->search('packagist')->then(function (array $packages) {
foreach ($packages as $package) {
echo $package->getName() . PHP_EOL;
}
});
```

#### get()

The `get($name)` method can be used to get package details for the given package name.
It resolves with a single `Package` object.
The `get(string $name): PromiseInterface<Package,Exception>` method can be used to
get package details for the given package name.

It resolves with a single [`Package`](#package) object
on success or rejects with an `Exception` on error.

```php
$client->get('clue/packagist-api-react')->then(function (Package $package) {
Expand All @@ -100,11 +124,14 @@ $client->get('clue/packagist-api-react')->then(function (Package $package) {

#### all()

The `all($filters = array())` method an be used to list all package names, optionally matching the given filter parameter.
It resolves with an array of package names.
The `all(array $filters = array()): PromiseInterface<string[],Exception>` method an be used to
list all package names, optionally matching the given filter parameter.

It resolves with an array of package names
on success or rejects with an `Exception` on error.

```php
$client->all(array('vendor' => 'clue'))->then(function ($list) {
$client->all(array('vendor' => 'clue'))->then(function (array $names) {
// array containing (among others) "clue/packagist-api-react"
});
```
Expand All @@ -130,7 +157,7 @@ The `getDescription()` method can be used to the package description.
The recommended way to install this library is [through Composer](https://getcomposer.org).
[New to Composer?](https://getcomposer.org/doc/00-intro.md)

This project follows [SemVer](http://semver.org/).
This project follows [SemVer](https://semver.org/).
This will install the latest supported version:

```bash
Expand Down Expand Up @@ -161,4 +188,7 @@ $ php vendor/bin/phpunit

## License

MIT
This project is released under the permissive [MIT license](LICENSE).

> Did you know that I offer custom development services and issuing invoices for
sponsorships of releases and for contributions? Contact me (@clue) for details.
2 changes: 1 addition & 1 deletion composer.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
"name": "clue/packagist-api-react",
"description": "Simple async access to packagist.org's API, like listing project details, number of downloads etc., built on top of ReactPHP.",
"keywords": ["packagist", "composer packages", "ReactPHP", "async"],
"homepage": "https://github.com/clue/php-packagist-api-react",
"homepage": "https://github.com/clue/reactphp-packagist-api",
"license": "MIT",
"authors": [
{
Expand Down
52 changes: 51 additions & 1 deletion src/Client.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,9 +2,11 @@

namespace Clue\React\Packagist\Api;

use Packagist\Api\Result\Factory;
use Clue\React\Buzz\Browser;
use Packagist\Api\Result\Factory;
use Packagist\Api\Result\Package;
use Psr\Http\Message\ResponseInterface;
use React\Promise\PromiseInterface;
use Rize\UriTemplate;

class Client
Expand All @@ -29,6 +31,24 @@ public function __construct(Browser $http, Factory $resultFactory = null, UriTem
$this->uri = $uri;
}

/**
* Search packages matching the given query string and optionally matching the given filter parameter.
*
* It resolves with an array containing zero or more [`Package`](#package) objects
* on success or rejects with an `Exception` on error.
*
* ```php
* $client->search('packagist')->then(function (array $packages) {
* foreach ($packages as $package) {
* echo $package->getName() . PHP_EOL;
* }
* });
* ```
*
* @param string $query
* @param array $filters
* @return PromiseInterface<Package[],\Exception>
*/
public function search($query, array $filters = array())
{
$filters['q'] = $query;
Expand Down Expand Up @@ -59,6 +79,21 @@ public function search($query, array $filters = array())
return $fetch($url);
}

/**
* Get package details for the given package name.
*
* It resolves with a single [`Package`](#package) object
* on success or rejects with an `Exception` on error.
*
* ```php
* $client->get('clue/packagist-api-react')->then(function (Package $package) {
* echo $package->getDescription();
* });
* ```
*
* @param string $package
* @return PromiseInterface<Package,\Exception>
*/
public function get($package)
{
return $this->respond(
Expand All @@ -71,6 +106,21 @@ public function get($package)
);
}

/**
* List all package names, optionally matching the given filter parameter.
*
* It resolves with an array of package names
* on success or rejects with an `Exception` on error.
*
* ```php
* $client->all(array('vendor' => 'clue'))->then(function (array $names) {
* // array containing (among others) "clue/packagist-api-react"
* });
* ```
*
* @param array $filters
* @return PromiseInterface<string[],\Exception>
*/
public function all(array $filters = array())
{
return $this->respond(
Expand Down