src/Tweeper.php: add a retry mechanism for cURL sessions

Sometimes the connection to a remote host may stall and a resource
cannot be retrieved. This makes Tweeper hang for a very long time which
can be annoying for users.

Setting a shorter timeout and a retry mechanism usually works around the
problem allowing the resource to be retrieved eventually.

Implement such a mechanism by adding curlExec() method and while at it
move non-curl related messages outside of getUrlContents() and
getUrlInfo() to give the user a better understanding of what actually
failed when even the retry mechanism was not able to retrieve the
resource.

src/Tweeper.php: harmonize error messages

Since the Tweeper class is supposed to be used as a library don't let
any error be fatal and convert all current uses of E_USER_ERROR into
E_USER_WARNING.

Also convert the few instances of E_USER_NOTICE into E_USER_WARNING.

Finally, stop using error_log as well in favour of trigger_error which
provides more context in the produced message.

src/Tweeper.php: make code more robust by properly check return values

Check return values to catch error earlier, and while at it also emit
more error messages in case of failures.

Add option to enable or disable showing usernames in RSS items

Tweeper shows usernames by default in items created from multi-user
sites like Twitter or Instagram.

This is because  the main use case is to aggregate multiple feeds in the
same viewer, and in this scenario having some info about where the
messages is coming from can be useful.

However sometimes tweeper can be used to track one single feed and in
this case having always the same username repeated over and over is
unnecessary.

Make showing the username optional, but keep the current behavior as
default.

NOTE: for Twitter keep always showing the username in case of retweets
($screen-name != $user-name).

src/rss_converter_*.xsl: add missing generate-enclosure parameter

XSL parameters do not necessarily need to be declared in the stylesheet
if no default value is explicitly set, however tweeper is doing that for
other stylesheet, so declare the parameter in rss_converter_pump.io.xsl
and rss_converter_dilbert.com.xsl as well for consistency.

src/Tweeper.php: silence error message when processing Instagram json

Remove the "knobs" element from the Instagram json data because it
contains elements with an undefined namespace which results in an error
message when json is converted to XML.

src/Tweeper.php: put a comment right before the code it refers to

src/Tweeper.php: rearrange blank lines to a consistent style

In other parts of the file there is no blank line between and the
assignment and check for the return value of a function call.

Use the same style everywhere.

Remove unneeded attribute extension-element-prefixes from xsl stylesheets

It looks like the "extension-element-prefixes" attribute is not strictly
needed for php extension functions to work, so remove it.

If it turns out that the attribute is actually needed in some cases it
can always be added back.

rss_converter_twitter.com.xsl: explain why the style attribute is removed

Since commit 6817108 (rss_converter_twitter.com.xsl: strip the style
attribute from HTML elements, 2017-06-08) the twitter.com stylesheet
removes the "style" attribute from elements when copying them.

This is in order to create a more visually neutral output, but also
because the style attribute may even contain dangerous content:
https://validator.w3.org/feed/docs/warning/DangerousStyleAttr.html

However someone who reads the code may not be familiar with (or have
forgotten) why this is done, so explain that in a comment to avoid them
the burden of digging in the project history.

src/rss_converter_twitter.com.xsl: add a label to tweets containing GIFs

The static scraped content only provides a preview of GIF files with the
first frame only, just like in the case of videos.

Set a label when a tweet contains a GIF so that the user can decide to
open the tweet in a full fledged browser to properly see the GIF.

src/rss_converter_twitter.com.xsl: make images more adaptive

Adapt images to the screen width to avoid horizontal scrolling in the
feed reader.

Tweeper.php: bump version in the User-Agent string

By using a more recent version of the User-Agent, twitter.com will
return more entries in the result when visiting hashtag pages.

This makes tracking hashtag pages more usable.

This change is similar to what was done in commit 0db2f37 ("Tweeper.php:
bump version in the User-Agent string", 2018-06-06)

NEWS: add release notes for the v1.3.0 release

src/rss_converter_twitter.com.xsl: only output channel image when it's available

Hashtag pages do not have an image usable as a channel logo, and in
cases like this the <url/> element would be empty, but this would make
the feed invalid according to https://www.feedvalidator.org

So, to produce feeds which validate, avoid outputting the whole <image/>
element when there is no suitable image to use as a channel logo.

src/rss_converter_twitter.com.xsl: fix getting description for hashtag pages

TODO: remove the entry about instagram tags, tweeper can now track them

src/rss_converter_instagram.com.xsl: add support for Instagram.com tags

Supporting Instagram tags is quite easy, so let's do it and while at it
refactor how the channel description is set depending of the kind of
page.

src/rss_converter_pump.io.xsl: fix getting the channel logo URL

Tweeper.php: bump version in the User-Agent string

By using a more recent version of the User-Agent, twitter.com will
return more entries in the result when visiting hashtag pages.

This makes tracking hashtag pages actually usable.

Tested with https://twitter.com/hashtag/tweeper

Tweeper.php: update the User-Agent string to fix parsing twitter.com

It looks like twitter.com started serving the mobile version of the site
to old browsers and Tweeper cannot parse that content.

By using a more up to date User-Agent string twitter.com returns the
desktop version of the page which Tweeper can process without problems.

rss_converter_instagram.com.xsl: don't put location coordinates in screen name

Remove location coordinates from the location screen name as the latter
also shows up in item titles, but still emit the coordinates in the
channel description.

rss_converter_instagram.com.xsl: use the screen name in item titles

The user name is not always defined, for example in case of locations,
so use the screen name in item titles.

rss_converter_instagram.com.xsl: fix scraping Instagram.com

rss_converter_twitter.com.xsl: show again the user name in the description

Having the user name also in the description makes it easier to see who
the author is in case of re-tweeted messages.

Leave the line-break after the username to have the actual message start
at the beginning of the line, this is done to preserve the formatting of
the original message as much as possible.

Update copyright years

INSTALL: add some notes for about dependencies

INSTALL: explain better what "usable HTML" means in this context

NEWS: add release notes for the v1.2.0 release

rss_converter_instagram.com.xsl: fix validation for Instagram location feeds

Avoid outputting an <image/> element without an empty <url/>, this
breaks validation.

Tweeper.php: a more robust fix for 4b9692a19e06f3cf698d23a3854fd34b9914a32a

The "qe" element in the json data is the one containing the problematic
element mentioned in commit 4b9692a19e06f3cf698d23a3854fd34b9914a32a and
it may contain multiple elements with problematic names, so just remove
the "qe" element altogether.

rss_converter_twitter.com.xsl: preserve spaces in tweet content

Wrap the tweet content into a span element with a CSS style attribute
set to "white-space: pre-wrap", this allows to have the spaces rendered
like on the twitter web page: with spaces and newlines preserved.

This is especially desirable if the tweet content contains any ASCII
art, like in https://twitter.com/sarahjeong/status/955651919279722496

rss_converter_twitter.com.xsl: add support for permalink URLs

This way it is possible to generate an RSS feed of all the replies to
a certain tweet using its permalink URL.

rss_converter_twitter.com.xsl: add a line break after the "(Video)" label

This is to start the actual original tweet content on a new line, this
is important for example if the content contains some ASCII art.

rss_converter_twitter.com.xsl: don't print the user name in description

This is in the spirit of leaving the tweet content untouched as much as
possible.

rss_converter_twitter.com.xsl: use a different rule to get the tweet user-name

Instead of looking for 'js-stream-tweet' in the class attribute, pick
the element which has the 'data-tweet-id' attribute, this is more
generic and works also with permalink tweets.

Tweeper.php: fix converting Instagram data to RSS

There is one new element in the json data served by Instagram named
"404_as_react", and this makes the conversion from json to XML fail
because names starting with a number are illegal in XML.

Fix the problem by prepending an underscore to the problematic name.

rss_converter_facebook.com.xsl: fix channel link, image, and description

rss_converter_facebook.com.xsl: fix scraping facebook.com pages once again

Add back support for 'userContentWrapper' which seems to be still used.

TODO: add an entry about Instagram tags

rss_converter_facebook.com.xsl: fix scraping facebook.com pages once again

Tip: in order to get more posts, and not just the last two, append
"/posts" to the facebook page URL, or use the URL of the "See all" link
in the "Posts" section.

rss_converter_instagram.com.xsl: support scraping Instagram locations pages

rss_converter_instagram.com.xsl: improve the comment about full names

NEWS: add release notes for the v1.1.0 release

TODO: add an entry about the use of trigger_error()

Remove support for Howtoons.com, the old blog is not available anymore

Add an example of instrumentation to capture the HTML for later analysis

rss_converter_twitter.com.xsl: filter out promoted tweets

rss_converter_twitter.com.xsl: strip the style attribute from HTML elements

Elements in an RSS item description are not supposed to have a style
attribute, and they don't really need to anyways, so filter it out in
the identity template.

This also fixes an issue with Twitter images being shown with a offset
in liferea.

rss_converter_facebook.com.xsl: match both the new and the old wrapper class

Facebook still seems to use the "userContentWrapper" sometimes, it's not
clear if "fbUserContent" was only used for a short period of time or if
both are actually used; in the doubt support both.

HACKING: add instructions about installing the Drupal style in PHP_CodeSniffer

Add the helper script tests/tweeper_file

The script allows to scrape a local file, this speeds up development and
testing.

Add the helper script tests/fetch_facebook_page.sh

The script helps retrieving the actual html of a public page on
facebook.com, ignoring the pages which require the CAPTCHA.

This allows to have a local copy of the page to test tweeper on.

Tweeper.php: allow to pass parameters to Tweeper::tweep()

This allows to call Tweeper::tweep() on file:// URLs which can make
development faster.

rss_converter_facebook.com.xsl: fix the URL of the channel image

rss_converter_facebook.com.xsl: new wrapper classname

Facebook seems to have changed the classname of the wrapping div
from "userContentWrapper" to "fbUserContent".

NEWS: add release notes for the v1.0.0 release

The release numbering scheme has been changed to match what composer
expects.

composer.json: make the dependencies on symfony components more relaxed

Makefile: mention DESTDIR in the "INSTALLATION COMPLETE" message

Makefile: make the symlink in BIN_DIR refer to the executable in DESTDIR

Also make the symlink relative, this way it is always valid whether
DESTDIR is specified or not.

Makefile: fix installation after the code restructuring

tweeper: allow running tweeper from vendor/bin also when it's not a symlink

autoload.php: improve the comment about the system-wide dependencies

TODO: add a note about the version of the dependencies in composer.json

Update copyright years in recently modified files

tweeper: allow to run tweeper either with or without composer

Add a composer.json file

rss_converters_*.xsl: prefix the namespace when calling Tweeper class methods

The Tweeper class is now in a namespace, without this change the XSLT
processor would give errors like this:

PHP Warning:  XSLTProcessor::transformToXml(): Unable to call handler Tweeper::epochToRssDate() in .../src/Tweeper.php on line 356

tweeper: move the main Tweeper class to its own file under src/

This matches more closely the project structure expected by composer
packages.

TODO: improve wording and remove fullstops at the end of items

Fix information leakage by validating the URL scheme

Validate the scheme to prevent leaking information by abusing the
file:// scheme.

Before this change it was possible to see what files are available on
the system running tweeper.

The script in tests/test_information_leakage.sh shows the problem on
earlier versions.

Here is an execution with tweeper-0.6:

-----------------------------------------------------------------------
URL file://twitter.com//etc/passwd
--> /etc/passwd
    exists

URL file://twitter.com//etc/file_with_an_unlikely_name
... /etc/file_with_an_unlikely_name
    does not exist

Staring a test server

URL file://twitter.com//etc/passwd
--> /etc/passwd on http://localhost:8000
    exists

URL file://twitter.com//etc/file_with_an_unlikely_name
... /etc/file_with_an_unlikely_name on http://localhost:8000
    does not exist

Shutting down the test server
-----------------------------------------------------------------------

Here is an execution after this fix:

-----------------------------------------------------------------------
PHP Fatal error:  unsupported scheme: file in /home/ao2/Proj/Tweeper/tweeper/tweeper.php on line 323
URL file://twitter.com//etc/passwd
... /etc/passwd
    does not exist

PHP Fatal error:  unsupported scheme: file in /home/ao2/Proj/Tweeper/tweeper/tweeper.php on line 323
URL file://twitter.com//etc/file_with_an_unlikely_name
... /etc/file_with_an_unlikely_name
    does not exist

Staring a test server

URL file://twitter.com//etc/passwd
... /etc/passwd on http://localhost:8000
    does not exist

URL file://twitter.com//etc/file_with_an_unlikely_name
... /etc/file_with_an_unlikely_name on http://localhost:8000
    does not exist

Shutting down the test server
-----------------------------------------------------------------------

tweeper.php: check the return value of Tweeper::tweep()

If the tweep() method fails return 1 to the calling process so that it
can know that something failed.

tweeper.php: check curl_exec() return value

Also show the message of curl_error() when curl_exec() fails, this way
it's easier to diagnose problems.

tweeper.php: support "application/pdf" as an enclosure content type

tweeper.php: support "application/octet-stream" as an enclosure content type

This allows binary attachment without a more specific content type to be
supported for the enclosure element.

Adding "application/octet-stream" also covers the weird case of servers
sending multiple Content-Type headers, e.g.:

< HTTP/1.1 200 OK
< Server: Apache
< ETag: "a46d495ba00c35580f83344dd523ece2:1473631283"
< Last-Modified: Sun, 11 Sep 2016 22:01:22 GMT
< Accept-Ranges: bytes
< Content-Length: 14346711
< Content-Type: audio/mpeg
< Content-Type: application/octet-stream
< content-disposition: attachment
< Date: Mon, 26 Sep 2016 23:36:11 GMT
< Connection: keep-alive
< Content-Type: application/octet-stream
< content-disposition: attachment

In this case the ideal solution would be to use the more _specific_
content type, but CURL just remembers the _last_ one ad it's not really
worth parsing the HTTP headers in tweeper just for this rare scenario.

Reported-by: Torsten Grote

NEWS: add release notes for the v0.6 release

rss_converter_instagram.com.xsl: strip unneeded trailing space

Add a HACKING file to describe the coding style used in the project

INSTALL: mention php-symfony-property-access as a dependency

tweeper.php: fix a problem with https URLs ending up in the enclosure element

When the remote host forces every URLs to be redirected to https, the
info returned by Tweeper::getUrlInfo() would contain an https URL, which
will end up being used in the "url" attribute of the enclosure element,
and this is invalid according to the RSS specification.

So make sure that an http URL is actually used for the "url" attribute.

Use php:functionString() in the stylesheets where appropriate

Instead of converting to string in XSL and then calling php:function(),
use directly php:functionString() when calling PHP functions which
actually expect a string argument.

Besides possible performance improvements, this is done mainly for
readability.

Don't convert the timestamp to a number when calling php:functionString()

It's not needed to convert the $timestamp variable to a number before
passing it as an argument to php:functionString() as the latter will
convert it to a string anyways.

TODO: remove entry about using enclosure for pump.io images

rss_converter_pump.io.xsl: add enclosure element for images

TODO: remove the item about enclosures for dilbert.com, now they are supported

rss_converter_instagram.com.xsl: don't use a template for the enclosure

Each post has exactly one image, it is enough to copy the generated
element in-place without applying templates.

rss_converter_dilbert.com.xsl: add support for the <enclosure/> element

TODO: add an entry about adding direct links to Instagram videos

rss_converter_instagram.com.xsl: make images adapt to the viewer width

This way the user does not have to scroll horizontally to see the whole
picture.

rss_converter_instagram.com.xsl: use a stricter match for some elements

rss_converter_instagram.com.xsl: fix the channel link

TODO: update the entry about twitter images and cards, images are now supported

rss_converter_twitter.com.xsl: generate enclosure for images

rss_converter_twitter.com.xsl: show explicitly if the item has a video

Tweeper does not provide direct links to videos, so it's useful to tell
users that the content has a video so they can follow the link and view
it on the twitter.com page.

rss_converter_twitter.com.xsl: don't repeat background in embedded media

Tweeper doesn't provide direct links to videos and vines from twitter
but it still shows the preview picture provided by the original HTML
code; unfortunately the picture repeats itself, so avoid that.

rss_converter_twitter.com.xsl: present images in a more convenient way

Make images clickable and pointing to the original full-size picture.

rss_converter_twitter.com.xsl: show media content in the feed item description

rss_converter_twitter.com.xsl: use direct URLs for links, when possible

Replace the t.co URLs with the actual location the link was originally
meant to point to.

rss_converter_twitter.com.xsl: add a mode attribute to the enclosure template

This is needed because another template with
match="a[@data-expanded-url]" will be added in a future commit.

rss_converter_twitter.com.xsl: cleanup titles

Prepend a white space in front of some URLs (those not preceded by an
open parenthesis) because otherwise they get rendered attached to the
preceding text.

Also strip non-breaking spaces and horizontal ellipses, they are not
needed because the RSS feed show the full URLs.