{"id":23613711,"url":"https://github.com/interfax/interfax-php","last_synced_at":"2025-05-12T21:43:15.228Z","repository":{"id":12249533,"uuid":"66478711","full_name":"interfax/interfax-php","owner":"interfax","description":"Fax send and receive in PHP with the InterFAX REST API","archived":false,"fork":false,"pushed_at":"2024-05-03T18:59:45.000Z","size":238,"stargazers_count":13,"open_issues_count":1,"forks_count":4,"subscribers_count":7,"default_branch":"master","last_synced_at":"2025-05-12T18:59:16.716Z","etag":null,"topics":["fax","fax-api","hipaa","inbound","interfax","interfax-api","library","online-fax","outbound","php","receive","sdk","send"],"latest_commit_sha":null,"homepage":"https://www.interfax.net/en/dev/php","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/interfax.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2016-08-24T16:01:44.000Z","updated_at":"2024-12-17T15:02:54.000Z","dependencies_parsed_at":"2024-06-21T17:51:04.558Z","dependency_job_id":"c61604dc-f982-4b62-a119-1c2022ff3152","html_url":"https://github.com/interfax/interfax-php","commit_stats":{"total_commits":160,"total_committers":5,"mean_commits":32.0,"dds":"0.20625000000000004","last_synced_commit":"e7bda110f5dbb0e514dc8d985cca7d58508efa89"},"previous_names":[],"tags_count":13,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/interfax%2Finterfax-php","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/interfax%2Finterfax-php/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/interfax%2Finterfax-php/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/interfax%2Finterfax-php/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/interfax","download_url":"https://codeload.github.com/interfax/interfax-php/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253828420,"owners_count":21970699,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["fax","fax-api","hipaa","inbound","interfax","interfax-api","library","online-fax","outbound","php","receive","sdk","send"],"created_at":"2024-12-27T17:19:12.057Z","updated_at":"2025-05-12T21:43:15.183Z","avatar_url":"https://github.com/interfax.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"# InterFAX PHP Library\n\n[![PHP version](https://badge.fury.io/ph/interfax%2Finterfax.svg)](https://badge.fury.io/ph/interfax%2Finterfax)[![Build status](https://travis-ci.com/interfax/interfax-php.svg?branch=master)](https://travis-ci.com/interfax/interfax-php)\n\n[Installation](#installation) | [Getting Started](#getting-started) | [Contributing](#contributing) | [Usage](#usage) | [License](#license)\n\nSend and receive faxes in PHP with the [InterFAX](https://www.interfax.net/en/dev) REST API.\n\n## Installation\n\nTwo versions of this library exist, 1.x and 2.x. The 1.x version provides support for older versions of PHP, whilst the 2.x branch is designed to support the more recent releases of the language:\n\n| Package Version | Minimum PHP Version  | Maximum PHP Version |\n|-----------------|----------------------|---------------------|\n| 1.x             | 5.6                  | 7.2                 |\n| 2.x             | 7.3                  | 8.1                 |\n\n### Composer\n\nThe 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`:\n\n```bash\ncomposer require interfax/interfax\n```\n\nwith 1.x version constraint\n```bash\ncomposer require interfax/interfax:\"^1\"\n```\n\nor with 2.x version constraint\n\n```bash\ncomposer require interfax/interfax:\"^2\"\n```\n\n### Download the release\n\nYou can download the package in its entirety (from 1.0.2 onward). The [Releases](https://github.com/interfax/interfax-php/releases) page lists all stable versions. Download any file\nwith the name `interFAX-PHP-[RELEASE_NAME].zip` for a package including this library and its dependencies.\n\nUncompress the zip file you download, and include the autoloader in your project:\n\n```php\nrequire_once '/path/to/interFAX-PHP-[RELEASE_NAME]/vendor/autoload.php';\n```\n\nYou may wish to rename the release folder to not include the RELEASE_NAME, so that you can drop in future versions without changing the include.\n\n### Build it yourself\n\nThe [installation](INSTALLATION.md) docs explain how to create a standalone installation.\n\n## Getting started\n\nTo send a fax for a pdf file:\n\n```php\nuse Interfax\\Client;\n\n$interfax = new Client(['username' =\u003e 'username', 'password' =\u003e 'password']);\n$fax = $interfax-\u003edeliver(['faxNumber' =\u003e '+11111111112', 'file' =\u003e 'folder/file.pdf']);\n\n// get the latest status:\n$fax-\u003erefresh()-\u003estatus; // Pending if \u003c 0. Error if \u003e 0\n\n// Simple polling\nwhile ($fax-\u003erefresh()-\u003estatus \u003c 0) {\n    sleep(5);\n}\n```\n\n# Usage\n\n[Client](#client) | [Account](#account) | [Outbound](#outbound) | [Inbound](#inbound) | [Documents](#documents) | [Helper Classes](#helper-classes) | [Query Parameters](#query-parameters) | [Exceptions](#exceptions)\n\n## Client\n\nThe client follows the [12-factor](http://12factor.net/config) apps principle and can be either set directly or via environment variables.\n\n```php\n$client = new Interfax\\Client(['username' =\u003e '...', 'password' =\u003e '...']);\n\n// Alternative: will utilise environment variables:\n// * INTERFAX_USERNAME\n// * INTERFAX_PASSWORD\n\n$client = new Interfax\\Client();\n```\n### Send a Fax\n\nTo send a fax, call the deliver method on the client with the appropriate array of parameters. \n\n```php\n$client = new Interfax\\Client(['username' =\u003e '...', 'password' =\u003e '...']);\n$fax = $client-\u003edeliver([\n    'faxNumber' =\u003e '+442086090368',\n    'file' =\u003e __DIR__ . '/../tests/Interfax/test.pdf'\n]);\n```\n\nThe ```deliver``` method will take either a ```file``` or ```files``` argument. The ```files``` is an array of file values.\n\nEach ```file``` entry can be:\n\n* local path - if the file is larger than the allowed limit, it will be automatically uploaded as an ```Interfax\\Document```\n* uri (from an ```Interfax\\Document```)\n* an array defining a streamed resource (see below)\n* ```Interfax\\File``` \n* ```Interfax\\Document``` \n\n#### Sending a stream\n\nBecause 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:\n\n```php\n$stream = fopen('/tmp/fax.pdf', 'rb');\n$fax = $client-\u003edeliver([\n    'faxNumber' =\u003e '+442086090368',\n    'file' =\u003e [$stream, ['name' =\u003e 'fax.pdf', 'mime_type' =\u003e 'application/pdf']]\n```\n\nNote 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``` \n\n[Documentation](https://www.interfax.net/en/dev/rest/reference/2918)\n\n## Account\n\n### Balance\n\nDetermine the remaining faxing credits in your account.\n\n```php\necho $client-\u003egetBalance();\n// (string) 9.86\n```\n\n**More:** [documentation](https://www.interfax.net/en/dev/rest/reference/3001)\n\n## Outbound\n\n[Get list](#get-outbound-fax-list) | [Get completed list](#get-completed-fax-list) | [Get record](#get-outbound-fax-record) | [Get image](#get-outbound-fax-image) | [Cancel fax](#cancel-an-outbound-fax) | [Search](#search-fax-list) | [Resend fax](#resend-a-fax)\n\n```Interfax\\Client``` has an outbound property that can be accessed:\n\n```php\n$outbound = $client-\u003eoutbound;\n```\n\n### Get outbound fax list\n\n```php\n$faxes = $client-\u003eoutbound-\u003erecent();\n// Interfax\\Outbound\\Fax[]\n```\n\n**Options:** [`limit`, `lastId`, `sortOrder`, `userId`](https://www.interfax.net/en/dev/rest/reference/2920)\n\n----\n\n### Get completed fax list\n\n```php\n$fax_ids = [ ... ]; // array of fax ids\n$client-\u003eoutbound-\u003ecompleted($fax_ids);\n// Interfax\\Outbound\\Fax[]\n```\n\n### Get outbound fax record\n\n`$client-\u003eoutbound-\u003efind(fax_id)`\n\nRetrieves information regarding a previously-submitted fax, including its current status.\n\n```php\n$fax = $client-\u003eoutbound-\u003efind(123456);\n//Interfax\\Outbound\\Fax || null\n```\n\n[Documentation](https://www.interfax.net/en/dev/rest/reference/2921)\n\n### Get outbound fax image\n\n`$client-\u003eoutbound-\u003efind(fax_id)-\u003eimage()`\n\nThe image is retrieved via a method on the outbound fax image object.\n\n```php\n$fax = $client-\u003eoutbound-\u003efind(123456);\nif ($fax) {\n    $image = $fax-\u003eimage();\n    $image-\u003esave('path/to/save/file/to.tif');\n}\n```\n\n### Cancel an outbound fax\n\n`$client-\u003eoutbound-\u003efind(fax_id)-\u003ecancel();`\n\nA fax is cancelled via a method on the `Interfax\\Outbound\\Fax` model.\n\n```php\n$fax = $client-\u003eoutbound-\u003efind(123456);\nif ($fax) {\n    $fax-\u003ecancel();\n}\n```\n\n### Search fax list\n\n`$client-\u003eoutbound-\u003esearch($options)`\n\nSearch for outbound faxes with a hash array of options keyed by the accepted search parameters for the outbound search API endpoint.\n\n```php\n$faxes = $client-\u003eoutbound-\u003esearch(['faxNumber' =\u003e '+1230002305555']);\n// Interfax\\Outbound\\Fax[]\n```\n\n**Options:** [`ids`, `reference`, `dateFrom`, `dateTo`, `status`, `userId`, `faxNumber`, `limit`, `offset`](https://www.interfax.net/en/dev/rest/reference/2959)\n\n### Resend a Fax\n\n`$client-\u003eoutbound-\u003eresend($id[,$newNumber])`\n\nResend the fax identified by the given id (optionally to a new fax number).\n\n```php\n$fax = $client-\u003eoutbound-\u003eresend($id);\n// Interfax\\Outbound\\Fax sent to the original number\n$fax = $client-\u003eoutbound-\u003eresend($id, $new_number);\n// Interfax\\Outbound\\Fax sent to the $new_number\n```\n\nReturns a new `Interfax\\Outbound\\Fax` representing the newly created outbound fax.\n\n## Inbound\n\n[Get list](#get-inbound-fax-list) | [Get record](#get-inbound-fax-record) | [Get image](#get-inbound-fax-image) | [Get emails](#get-forwarding-emails) | [Mark as read](#mark-as-readunread) | [Resend to email](#resend-inbound-fax)\n\n```Interfax\\Client``` has an ```inbound``` property that supports the API endpoints for receiving faxes, as described in the [Documentation](https://www.interfax.net/en/dev/rest/reference/2913)\n\n```php\n$inbound = $client-\u003einbound;\n//Interfax\\Inbound\n```\n\n### Get inbound fax list\n\n`$inbound-\u003eincoming($options = []);`\n\nRetrieves a user's list of inbound faxes.\n\n```php\n$faxes = $inbound-\u003eincoming();\n//\\Interfax\\Inbound\\Fax[]\n$faxes = $inbound-\u003eincoming(['unreadOnly' =\u003e true ...]); // see docs for list of supported query params\n//\\Interfax\\Inbound\\Fax[]\n```\n\n[Documentation](https://www.interfax.net/en/dev/rest/reference/2935)\n\n--- \n\n### Get inbound fax record\n\n`$inbound-\u003efind($id);`\n\nRetrieves a single fax's metadata (receive time, sender number, etc.).\n\n```php\n$fax = $inbound-\u003efind(123456);\n//\\Interfax\\Inbound\\Fax || null\n```\n\nnull is returned if the resource is not found. Note that this could be because the user is not permissioned for the specific fax.\n\n[Documentation](https://www.interfax.net/en/dev/rest/reference/2938)\n\n---\n\n### Get inbound fax image\n\n`$inbound-\u003efind($id)-\u003eimage()`\n\nThe image is retrieved via a method on the inbound fax object.\n\n```php\n$fax = $client-\u003einbound-\u003efind(123456);\nif ($fax) {\n    $image = $fax-\u003eimage();\n    $image-\u003esave('path/to/save/file/to.pdf');\n}\n```\n\n[Documentation](https://www.interfax.net/en/dev/rest/reference/2937)\n\n---\n\n### Get forwarding emails\n\n`$inbound-\u003efind($id)-\u003eemails()`\n\nThe forwarding email details are retrieved via a method on the inbound fax object.\n\n```php\n$fax = $client-\u003einbound-\u003efind(123456);\nif ($fax) {\n    $emails = $fax-\u003eemails(); // array structure of forwarding emails.\n}\n```\n\nThe returned array is a reflection of the values returned from the emails endpoint of the REST API:\n\n```php\n[\n    [\n       'emailAddress' =\u003e 'username@interfax.net',\n       'messageStatus' =\u003e 0,\n       'completionTime' =\u003e '2012-0623T17 =\u003e 24 =\u003e 11'\n    ],\n    //...\n];\n```\n\n[Documentation](https://www.interfax.net/en/dev/rest/reference/2930)\n\n---\n\n### Mark as read/unread\n\n`$inbound-\u003efind($id)-\u003emarkRead();`\n`$inbound-\u003efind($id)-\u003emarkUnread();`\n\nThe inbound fax object provides methods to change the read status.\n\n```php\n$fax = $client-\u003einbound-\u003efind(123456);\nif ($fax) {\n    $fax-\u003emarkUnread(); // returns true\n    $fax-\u003emarkRead(); //returns true\n}\n```\n\n[Documentation](https://www.interfax.net/en/dev/rest/reference/2936)\n\n---\n\n### Resend inbound fax\n\n`$inbound-\u003efind($id)-\u003eresend();`\n\nThe resend method is on the inbound fax object.\n\n```php\n$fax = $client-\u003einbound-\u003efind(123456);\nif ($fax) {\n    $fax-\u003eresend(); \n}\n```\n\n---\n\n## Documents\n\n[Create](#create-document) | [Upload chunk](#upload-chunk) | [Properties](#document-properties) | [Cancel](#cancel-document)\n\nThe ```Interfax\\Document``` class allows for the uploading of larger files for faxing. The following is an example of how one should be created:\n\n```php\n$document = $client-\u003edocuments-\u003ecreate('test.pdf', filesize('test.pdf'));\n$stream = fopen('test.pdf', 'rb');\n$current = 0;\nwhile (!feof($stream)) {\n    $chunk = fread($stream, 500);\n    $end = $current + strlen($chunk);\n    $doc-\u003eupload($current, $end-1, $chunk);\n    $current = $end;\n}\nfclose($stream);\n```\n\n### Create document\n\n```php\n$params = [...]; // see documentation for possible params\n$document = $client-\u003edocuments-\u003ecreate($filename, filesize($filename), $params);\n// Interfax\\Document\n```\n\n[Documentation](https://www.interfax.net/en/dev/rest/reference/2967)\n\n### Upload chunk\n\n```php\n$document-\u003eupload($start, $end, $data); // returns the document object.\n```\n\nNote no verification of data takes place - an exception wil be raised if values do not match appropriately.\n\n### Document properties\n\nAs per the [documentation](https://www.interfax.net/en/dev/rest/reference/2965) a Document has a number of properties which are accessible:\n\n```php\n$document-\u003estatus;\n$document-\u003efileName;\n$document-\u003erefresh()-\u003eattributes();\n```\n\n```php\n$document-\u003elocation;\n// or as returned by the API:\n$document-\u003euri;\n```\n\n### Cancel document\n\n`$document-\u003ecancel(); //returns the $document instance`\n\nCan be done prior to completion or afterward\n\n## Helper Classes\n\n### Outbound Fax\n\nThe `Interfax\\Outbound\\Fax` class wraps the details of any fax sent, and is returned by most of the ```Outbound``` methods.\n\nIt offers several methods to manage or retrieve information about the fax.\n\n```php\n// fluent methods that return the $fax instance\n$fax-\u003erefresh(); // refreshes the data on the fax object\n$fax-\u003ecancel(); // cancel the fax, returns true on success\n$fax-\u003ehide(); // hides the faxes from the fax lists\n\n$image = $fax-\u003eimage(); // returns Interfax\\Image\n$new_fax = $fax-\u003eresend('+1111111'); // returns a new Interfax\\Outbound\\Fax\n$fax-\u003eattributes(); // hash array of fax data properties - see details below\n```\n\n### Outbound fax properties\n\nProperties on the Fax vary depending on which method call has been used to create the instance. Requesting a property that has not been received will raise a SPL ```\\OutOfBoundsException```\n\n[Documentation](https://www.interfax.net/en/dev/rest/reference/2921)\n\nThese are all accessible on a fax instance:\n\n```php\necho $fax-\u003ecompletionTime\necho $fax-\u003eduration\n...\n```\n\nNote values will all be returned as strings.\n\nFor convenience, a hash array of the properties can be retrieved\n\n```php\n$fax-\u003eattributes();\n```\n\nStatus should always be available. The values of the status codes are [Documented here](https://www.interfax.net/en/help/error_codes) \n\n### Inbound Fax\n\nThe incoming equivalent of the outbound fax class, the ```Interfax\\Inbound\\Fax``` class wraps the details of any incoming fax, and is returned by the ```Interfax\\Inbound``` methods where appropriate.\n\n```php\n// fluent methods that return the $fax instance for method chaining\n$fax-\u003erefresh(); // reload properties of the inbound fax\n$fax-\u003emarkRead(); // mark the fax read - returns true or throws exception\n$fax-\u003emarkUnread(); // mark the fax unread - returns true or throws exception\n$fax-\u003eresend();\n\n$image = $fax-\u003eimage(); // Returns a Interfax\\Image for this fax\n$email_array = $fax-\u003eemails(); // see below for details on the structure of this array\n$fax-\u003eattributes(); // hash array of properties\n```\n\n## Query parameters\n\nWhere methods support a hash array structure of query parameters, these will be passed through to the API endpoint as provided. This ensures that any future parameters that might be added will be supported by the API as is.\n \nThe only values that are manipulated are booleans, which will be translated to the text 'TRUE' and 'FALSE' as appropriate.\n\n[Documentation](https://www.interfax.net/en/dev/rest/reference/2927)\n\n## Exceptions\n\nAny method call that involves a call to the Interfax RESTful API may throw an instance of ```Interfax\\Exception\\RequestException```. \n \nAn exception is thrown for any requests that do not return a successful HTTP Status code. The goal of this Exception is to provide a convenience wrapper around information that may have been returned.\n\nCertain responses from the API will provide more detail, and where this occurs, it will be appended to the message of the Exception.\n\n```\ntry {\n    $interfax-\u003edeliver(...);\n} catch (Interfax\\Exception\\RequestException $e) {\n    echo $e-\u003egetMessage();\n    // contains text detail that is available\n    echo $e-\u003egetStatusCode();\n    // the http status code that was received\n    throw $e-\u003egetWrappedException();\n    // The underlying Guzzle exception that was caught by the Interfax Client.\n}\n```\n\n## Contributing\n\n 1. **Fork** the repo on GitHub\n 2. **Clone** the project to your own machine\n 3. **Commit** changes to your own branch\n 4. **Push** your work back up to your fork\n 5. Submit a **Pull request** so that we can review your changes\n\n### Which version of the library?\n\nFunctionality for the API in both versions of the library should be the same, and its therefore intended that the core code continues to be the same in both versions. The differences primarily exist to enable continuity of test coverage as PHP evolves (and phpunit evolves with it)\n\nAs such, the core functionality should be developed in a way that will work with PHP 5.6 and up, and be consistent in both versions. Usage of newer language features in PHP will not be accepted in the core code.\n \n### Running tests\n\nEnsure that composer is installed, then run the following commands.\n\n```sh\ncomposer install\n./vendor/bin/phpunit\n```\n\n## License\n\nThis library is released under the [MIT License](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Finterfax%2Finterfax-php","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Finterfax%2Finterfax-php","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Finterfax%2Finterfax-php/lists"}