Merge tag 'v1.4.0' into debian/master

Release v1.4.0

NEWS: add release notes for the v1.4.0 release

src/Tweeper.php: make enclosure validate when there is no Content-Length

When the server does not provide a Content-Length header, curl_getinfo()
would return a negative value for "download_content_length".

However RSS recommends to use 0 when the enclosure's size cannot be
determined.

See: https://www.feedvalidator.org/docs/error/UseZeroForUnknown.html

src/rss_converter_dilbert.com.xsl: fix generating enclosures

Enclosures were not generated for Dilbert.com because the URL of the
picture are protocol-relative and curl cannot work with these URLs.

Fix the URLs by prepending a protocol schema to them.

Add option to enable or disable showing multimedia content in RSS items

Tweeper by default shows multimedia contents like Twitter and Instagram
images in items descriptions.

However sometimes just having multimedia contents in the <enclosure/>
element may be enough, so make it optional to also have the content in
the item description.

Keep the current default behavior for backwards compatibility.

Fix PHP_CodeSniffer errors

Fix the following errors reported by PHP_CodeSniffer:

FILE: .../tweeper.php
-----------------------------------------------------------------------------
FOUND 1 ERROR AFFECTING 1 LINE
-----------------------------------------------------------------------------
 1 | ERROR | [x] The PHP open tag must be followed by exactly one blank line
-----------------------------------------------------------------------------
PHPCBF CAN FIX THE 1 MARKED SNIFF VIOLATIONS AUTOMATICALLY
-----------------------------------------------------------------------------

FILE: .../src/Tweeper.php
-----------------------------------------------------------------------------------------------------------------------------------
FOUND 6 ERRORS AFFECTING 2 LINES
-----------------------------------------------------------------------------------------------------------------------------------
 373 | ERROR | [x] Incorrect spacing between argument "$host" and equals sign; expected 1 but found 0
 373 | ERROR | [x] Incorrect spacing between default value and equals sign for argument "$host"; expected 1 but found 0
 373 | ERROR | [x] Incorrect spacing between argument "$validate_scheme" and equals sign; expected 1 but found 0
 373 | ERROR | [x] Incorrect spacing between default value and equals sign for argument "$validate_scheme"; expected 1 but found 0
 388 | ERROR | [x] Inline comments must start with a capital letter
 388 | ERROR | [x] Inline comments must end in full-stops, exclamation marks, colons, question marks, or closing parentheses
-----------------------------------------------------------------------------------------------------------------------------------
PHPCBF CAN FIX THE 6 MARKED SNIFF VIOLATIONS AUTOMATICALLY
-----------------------------------------------------------------------------------------------------------------------------------

FILE: .../autoload.php
-----------------------------------------------------------------------------
FOUND 1 ERROR AFFECTING 1 LINE
-----------------------------------------------------------------------------
 1 | ERROR | [x] The PHP open tag must be followed by exactly one blank line
-----------------------------------------------------------------------------
PHPCBF CAN FIX THE 1 MARKED SNIFF VIOLATIONS AUTOMATICALLY
-----------------------------------------------------------------------------

Time: 260ms; Memory: 10Mb

TODO: remove the item about trigger_error, the concern has been addressed

Tweeper stopped using E_USER_ERROR and survives after trigger_error()
calls.

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)

debian/changelog: release package version 1.3.0-1

Gbp-Dch: ignore

debian/control: bump Standards-Version to 4.1.4

Suggested by lintian:
I: tweeper source: out-of-date-standards-version 4.1.3 (released 2017-12-27) (current is 4.1.4)

Merge tag 'v1.3.0' into debian/master

Release v1.3.0

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

debian/changelog: release package version 1.2.0-1

Gbp-Dch: ignore

debian/copyright: update copyright years

debian/control: fix the short description

Remove parentheses from the short description as this may trigger
a false positive in lintian.

Parentheses are usually used to specify the role of alternative
packages, see the Debian Developer's Reference, section 6.2.2.

The change fixes this lintian notice:
I: tweeper: description-synopsis-might-not-be-phrased-properly

debian/control: bump Standards-Version to 4.1.3

Suggested by lintian:
I: tweeper source: out-of-date-standards-version 4.0.0 (released 2017-05-28) (current is 4.1.3)

debian/{compat,control}: increase debhelper compatibility version to 11

This has been suggested by lintian:
P: tweeper source: package-uses-old-debhelper-compat-version 9

debian/{control,gbp.conf}: change the debian branch name to follow DEP-14

Merge tag 'v1.2.0' into debian/master

Release v1.2.0

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

debian/changelog: release package version 1.1.0-1

Gbp-Dch: ignore

debian/watch: use https for the git repository URL

debian/copyright: minor updates suggested by "cme update dpkg-copyright"

debian/control: don't mention Howtoons.com, it's not supported anymore

debian/control: bump Standards-Version to 4.0.0

Merge tag 'v1.1.0' into debian

Release v1.1.0

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".

debian/changelog: release package version 1.0.0-1

Gbp-Dch: ignore

debian/{control,rules}: use pkg-php-tools

Suggested by lintian:
I: tweeper source: composer-package-without-pkg-php-tools-builddep

debian/copyright: some cleanup suggested by "cme update dpkg-copyright"

debian/watch: simplify the watch file, use the git mode to fetch tags

Fun fact: the uscan man page uses tweeper as an example for mode=git.
So the new tweeper watch file is actually an *exact* copy of the uscan
example :)

Merge tag 'v1.0.0' into debian

Release v1.0.0

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.