<commit_before># InterFAX PHP Library

[![PHP version](https://badge.fury.io/ph/interfax%2Finterfax.svg)](https://badge.fury.io/ph/interfax%2Finterfax)[![Build status](https://travis-ci.org/interfax/interfax-php.svg?branch=master)](https://travis-ci.org/interfax/interfax-php)

[Installation](#installation) | [Getting Started](#getting-started) | [Contributing](#contributing) | [Usage](#usage) | [License](#license)

Send and receive faxes in Ruby with the [InterFAX](https://www.interfax.net/en/dev) REST API.

## Installation

This library requires PHP 5.5 and above.

The preferred method of installation is via [Packagist](http://www.packagist.org) and [Composer](http://www.composer.org). Run the following command to install the package and add it as a requirement to your project's `composer.json`:

```bash
composer require interfax/interfax
```

## Getting started

To send a fax for a pdf file:

```php
use Interfax\Client;

$interfax = new Client(['username' => 'username', 'password' => 'password']);
$fax = $interfax->deliver(['faxNumber' => '+11111111112', 'file' => 'folder/file.pdf']);

// getStatus will refresh the status of the fax from the server, if it's less than 0, then the fax is still pending.
while ($fax->getStatus() < 0) {
    sleep(5); // wait 5 seconds
}

// false prevents another request for status
echo $fax->getStatus(false) === 0 ? 'SUCCESS' : 'FAILURE';
```

# Usage

[Client](#client) | [Account](#account) | [Outbound](#outbound) | [Inbound](#inbound) | [Documents](#documents) | [Helper Classes](#helper-classes) | [Query Parameters](#query-parameters) | [Exceptions](#exceptions)

## Client

The client follows the [12-factor](http://12factor.net/config) apps principle and can be either set directly or via environment variables.

```php
$client = new Interfax\Client(['username' => '...', 'password' => '...']);

// Alternative: will utilise environment variables:
// * INTERFAX_USERNAME
// * INTERFAX_PASSWORD

$client = new Interfax\Client();
```
### Send a Fax

To send a fax, call the deliver method on the client with the appropriate array of parameters. 

```php
$client = new Interfax\Client(['username' => '...', 'password' => '...']);
$fax = $client->deliver([
    'faxNumber' => '+442086090368',
    'file' => __DIR__ . '/../tests/Interfax/test.pdf'
]);
```

The ```deliver``` method will take either a ```file``` or ```files``` argument. The ```files``` is an array of file values.

Each ```file``` entry can be:

* local path - if the file is larger than the allowed limit, it will be automatically uploaded as an ```Interfax\Document```
* uri (from an ```Interfax\Document```)
* ```Interfax\File``` 
* ```Interfax\Document``` 

[Documentation](https://www.interfax.net/en/dev/rest/reference/2918)

## Account

### Balance

Determine the remaining faxing credits in your account.

```php
echo $client->getBalance();
// (string) 9.86
```

**More:** [documentation](https://www.interfax.net/en/dev/rest/reference/3001)

## Outbound<commit_msg>added documentation to README regarding support for streams<commit_after># InterFAX PHP Library

[![PHP version](https://badge.fury.io/ph/interfax%2Finterfax.svg)](https://badge.fury.io/ph/interfax%2Finterfax)[![Build status](https://travis-ci.org/interfax/interfax-php.svg?branch=master)](https://travis-ci.org/interfax/interfax-php)

[Installation](#installation) | [Getting Started](#getting-started) | [Contributing](#contributing) | [Usage](#usage) | [License](#license)

Send and receive faxes in Ruby with the [InterFAX](https://www.interfax.net/en/dev) REST API.

## Installation

This library requires PHP 5.5 and above.

The preferred method of installation is via [Packagist](http://www.packagist.org) and [Composer](http://www.composer.org). Run the following command to install the package and add it as a requirement to your project's `composer.json`:

```bash
composer require interfax/interfax
```

## Getting started

To send a fax for a pdf file:

```php
use Interfax\Client;

$interfax = new Client(['username' => 'username', 'password' => 'password']);
$fax = $interfax->deliver(['faxNumber' => '+11111111112', 'file' => 'folder/file.pdf']);

// getStatus will refresh the status of the fax from the server, if it's less than 0, then the fax is still pending.
while ($fax->getStatus() < 0) {
    sleep(5); // wait 5 seconds
}

// false prevents another request for status
echo $fax->getStatus(false) === 0 ? 'SUCCESS' : 'FAILURE';
```

# Usage

[Client](#client) | [Account](#account) | [Outbound](#outbound) | [Inbound](#inbound) | [Documents](#documents) | [Helper Classes](#helper-classes) | [Query Parameters](#query-parameters) | [Exceptions](#exceptions)

## Client

The client follows the [12-factor](http://12factor.net/config) apps principle and can be either set directly or via environment variables.

```php
$client = new Interfax\Client(['username' => '...', 'password' => '...']);

// Alternative: will utilise environment variables:
// * INTERFAX_USERNAME
// * INTERFAX_PASSWORD

$client = new Interfax\Client();
```
### Send a Fax

To send a fax, call the deliver method on the client with the appropriate array of parameters. 

```php
$client = new Interfax\Client(['username' => '...', 'password' => '...']);
$fax = $client->deliver([
    'faxNumber' => '+442086090368',
    'file' => __DIR__ . '/../tests/Interfax/test.pdf'
]);
```

The ```deliver``` method will take either a ```file``` or ```files``` argument. The ```files``` is an array of file values.

Each ```file``` entry can be:

* local path - if the file is larger than the allowed limit, it will be automatically uploaded as an ```Interfax\Document```
* uri (from an ```Interfax\Document```)
* an array defining a streamed resource (see below)
* ```Interfax\File``` 
* ```Interfax\Document``` 

#### Sending a stream

Because of the high degree of flexibility that PHP stream resources offer, it's not practical to retrieve information automatically from a stream to send as a fax. As such, there are certain required parameters that must be provided:

```php
$stream = fopen('/tmp/fax.pdf', 'rb');
$fax = $client->deliver([
    'faxNumber' => '+442086090368',
    'file' => [$stream, ['name' => 'fax.pdf', 'mime_type' => 'application/pdf']]
```

Note that it is assumed that the stream will not exceed the file size limitation for an inline file to be sent. However, if a size parameter is provided for the stream, and this exceeds the limit, it will be automatically uploaded as a ```Interfax\Document``` 

[Documentation](https://www.interfax.net/en/dev/rest/reference/2918)

## Account

### Balance

Determine the remaining faxing credits in your account.

```php
echo $client->getBalance();
// (string) 9.86
```

**More:** [documentation](https://www.interfax.net/en/dev/rest/reference/3001)

## Outbound
{'fraction_non_alphanumeric': 0.17038777908343125, 'fraction_numerical': 0.015569917743830788, 'mean_word_length': 4.785046728971962, 'pattern_counts': {'":': 0, '<': 5, '<?xml version=': 0, '>': 38, 'https://': 14, 'lorem ipsum': 0, 'www.': 10, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 2, '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': '6377473', 'n_tokens_mistral': 2299, 'n_tokens_neox': 2064, 'n_words': 658}