XRay
====
XRay parses structured content from a URL.
## Discovering Content
XRay will parse content in the following formats. First the URL is checked against known services:
* Instagram
* Twitter
* GitHub
* XKCD
* Hackernews
* Facebook (public events)
If the contents of the URL is XML or JSON, then XRay will parse the Atom, RSS or JSONFeed formats.
Finally, XRay looks for Microformats on the page and will determine the content from that.
* h-card
* h-entry
* h-event
* h-review
* h-recipe
* h-product
* h-item
* h-feed
## Library
XRay can be used as a library in your PHP project. The easiest way to install it and its dependencies is via composer.
```
composer require p3k/xray
```
You can also [download a release](https://github.com/aaronpk/XRay/releases) which is a zip file with all dependencies already installed.
### Parsing
```php
$xray = new p3k\XRay();
$parsed = $xray->parse('https://aaronparecki.com/2017/04/28/9/');
```
If you already have an HTML or JSON document you want to parse, you can pass it as a string in the second parameter.
```php
$xray = new p3k\XRay();
$html = '....';
$parsed = $xray->parse('https://aaronparecki.com/2017/04/28/9/', $html);
```
```php
$xray = new p3k\XRay();
$jsonfeed = '{"version":"https://jsonfeed.org/version/1","title":"Manton Reece", ... ';
// Note that the JSON document must be passed in as a string in this case
$parsed = $xray->parse('https://manton.micro.blog/feed.json', $jsonfeed);
```
In both cases, you can add an additional parameter to configure various options of how XRay will behave. Below is a list of the options.
* `timeout` - The timeout in seconds to wait for any HTTP requests
* `max_redirects` - The maximum number of redirects to follow
* `include_original` - Will also return the full document fetched
* `target` - Specify a target URL, and XRay will first check if that URL is on the page, and only if it is, will continue to parse the page. This is useful when you're using XRay to verify an incoming webmention.
* `expect=feed` - If you know the thing you are parsing is a feed, include this parameter which will avoid running the autodetection rules and will provide better results for some feeds.
Additional parameters are supported when making requests that use the Twitter or GitHub API. See the Authentication section below for details.
```php
$xray = new p3k\XRay();
$parsed = $xray->parse('https://aaronparecki.com/2017/04/28/9/', [
'timeout' => 30
]);
$parsed = $xray->parse('https://aaronparecki.com/2017/04/28/9/', $html, [
'target' => 'http://example.com/'
]);
```
The `$parsed` return value will look like the below. See "Primary Data" below for an explanation of the vocabularies returned.
```
$parsed = Array
(
[data] => Array
(
[type] => card
[name] => Aaron Parecki
[url] => https://aaronparecki.com/
[photo] => https://aaronparecki.com/images/profile.jpg
)
[url] => https://aaronparecki.com/
[code] => 200,
[source-format] => mf2+html
)
```
### Processing Microformats2 JSON
If you already have a parsed Microformats2 document as an array, you can use a special function to process it into XRay's native format. Make sure you pass the entire parsed document, not just the single item.
```php
$html = 'Hello World
