facebookarchive / facebook-instant-articles-sdk-extensions-in-php

Facebook Instant Articles SDK Extensions in PHP.

Facebook Instant Articles SDK Extensions in PHP

The Facebook Instant Articles SDK Extensions in PHP provides a native PHP interface for converting valid Instant Articles into AMP. This gives developers the ability to have AMP content right after getting his own Instant Article markup format ready.

The Extension package consists of:

• Environment: PHP >= 5.4
• Dependencies: It relies solely on the Instant Articles SDK and its dependencies to get the Instant Article markup format available into the Elements object tree structure. It also depends on Composer dependency manager.
• AMP: The AMP transformation was based on the current implementation and definition from AMP project.

Quick Start

$ composer require facebook/facebook-instant-articles-sdk-extensions-in-php

After the installation, you can include the auto loader script in your source with:

require_once('vendor/autoload.php');

Also be sure to check the quick start example.

Official Documentation

You can find examples on how to use the different components of this SDK to integrate with your CMS in the Quick Start Guide of the documentation.

Contributing

Clone the repository

$ git clone https://github.com/facebook/facebook-instant-articles-sdk-extensions-in-php.git

Composer is a prerequisite for testing and developing. Install composer globally, then install project dependencies by running this command in the project's root directory:

$ composer install

To run the tests:

$ composer test

To fix and check for coding style issues:

$ composer cs

Extra lazy? Run

$ composer all

to fix and check for coding style issues, and run the tests.

If you change structure, paths, namespaces, etc., make sure you run the autoload generator:

$ composer dump-autoload

---

For us to accept contributions you will have to first sign the Contributor License Agreement. Please see CONTRIBUTING for details.

---

Troubleshooting

If you are encountering problems, the following tips may help in troubleshooting issues:

• If your images are having dimension/aspect ratio problems, please check the the quick start example for more information.
• At the moment, we have no way to determine a video's width and height, you need to explicitly pass that information via properties, see how to do it here.

Filing an issue

• Be sure you've looked for the similar issue into the Issues list

• Inform the Canonical URL of your Instant Article being converted

• Inform the exported JSON from the style editor

Issue template:

# Issue Data
Instant Article Canonical URL: `http://yourdomain.com/path/article.html`
Exported Style JSON: `{...}`
Page ID: `12345`

# Problem noticed
1. Image XYZ missing

# Expected result
1. The Image XYZ should be present.

License

Please see the license file for more information.

facebook-instant-articles-sdk-extensions-in-php's Issues

Analytics property throws "Call to undefined method" error

Problem noticed

Adding the analaytics property

$properties[AMPArticle::ANALYTICS_KEY] = array(
      '<amp-pixel src="http://mydomain.com/my_tracking_pixel.gif">',
      '<amp-analytics config="https://mydomain.com/analytics.config.json"></amp-analytics>'
    );

from your quick start example and rendering the article throws an Error:

Error: Call to undefined method Facebook\InstantArticles\AMP\AMPArticle::getContext() in Facebook\InstantArticles\AMP\AMPArticle->buildAnalytics() (line 207 of [...]vendor/facebook/facebook-instant-articles-sdk-extensions-in-php/src/Facebook/InstantArticles/AMP/AMPArticle.php).

Facebook\InstantArticles\AMP\AMPArticle->buildAnalytics() (Line: 281)
Facebook\InstantArticles\AMP\AMPArticle->transformInstantArticle(Object) (Line: 189)
Facebook\InstantArticles\AMP\AMPArticle->toDOMElement(Object) (Line: 38)
Facebook\InstantArticles\Elements\Element->render('', 1) (Line: 145)
Facebook\InstantArticles\AMP\AMPArticle->render() (Line: 55)

There is no getContext() method in AMPArticle, so adding analytics the way described in your example does not work.

Expected result

Analytics text in rendered AMP Article markup.

Bug: AMPArticle::create() doesn't always handle utf-8 characters correctly

On my production server (but not my development server), AMP articles has an encoding issue. For example, ‘Who said growing old had to be graceful?’ became â��Who said growing old had to be graceful?â��.

I think I've tracked this down to the AMPArticle::create() method, specifically $document->loadHTML ($instantArticle);.

For debug purposes, I've modified the code to read:

    if (isset($_GET['debug'])) { echo $instantArticle;}
    $document->loadHTML($instantArticle);
    if (isset($_GET['debug'])) { echo $document->saveHTML();die();}

That will output two versions of the string — one before $document=>loadHTML() and one after. You can see the result here. The first version outputs correctly, the second version incorrectly (sorry about the large images — just scroll past them.) If you remove the debug parameter, the page will display correctly. That's only because I have added an mb_convert_encoding() function to fix the problem. With the standard code, I get the errors.

If I'm wrong in my diagnosis, I'm happy to help with any further debugging.

I initially reported this bug here: Automattic/facebook-instant-articles-wp#824

Recognition of Interactive elements too restrictive

The recognition of interactive elements in the instant article is too restrictive.

else if ((Type::is($child, Interactive::getClassName()) || Type::is($child, SocialEmbed::getClassName())) && !Type::isTextEmpty($child->getSource())) {
                    if (!$containsIframe) {
                        $containsIframe = true;
                        $context->getHead()->appendChild($this->buildCustomElementScriptEntry('amp-iframe', 'https://cdn.ampproject.org/v0/amp-iframe-0.1.js', $context));
                    }
                    $childElement = $this->observer->applyFilters('IA_INTERACTIVE', $this->buildIframe($child, $context, 'interactive', true), $child, $context);
                }

Filters with tag "IA_INTERACTIVE" are only applied when the iframe has a "src" attribute, because of && !Type::isTextEmpty($child->getSource()).

Standard Twitter, Facebook, Instagram elements for example are not getting recognized (@see https://developers.facebook.com/docs/instant-articles/reference/embeds)

<figure class="op-interactive">
  <iframe>
    <!-- Include Twitter embed code here. Your embed code should look like <blockquote class="twitter-tweet" ... -->    
  </iframe>
</figure>

Please change the recognition so that iframes without src within "op_interactive" figures are getting recognized too.

Generated amp-img tags should default to layout=responsive

AMP itself should probably have defaulted to layout=responsive but decided to go with fixed for compat with regular img. I'd suggest adding layout=responsive by default, since that makes the images scale with device width.

Adding a filter (for example IA_IMAGE) throws an exception.

Problem noticed

Adding a filter as described on https://developers.facebook.com/docs/instant-articles/other-formats throws an Exception:

InvalidArgumentException: Method expects this value ----[ NULL ]---- to be one of the types ====[ string(10) "DOMElement" ]==== in Facebook\InstantArticles\Validators\Type::throwException() (line 182 of [...]/vendor/facebook/facebook-instant-articles-sdk-php/src/Facebook/InstantArticles/Validators/Type.php).
Facebook\InstantArticles\Validators\Type::is(NULL, 'DOMElement', 1) (Line: 39)
Facebook\InstantArticles\Validators\Type::enforce(NULL, 'DOMElement') (Line: 589)
Facebook\InstantArticles\AMP\AMPContext->addItem(NULL) (Line: 444)
Facebook\InstantArticles\AMP\AMPArticle->transformArticleContent(Object) (Line: 264)
Facebook\InstantArticles\AMP\AMPArticle->transformInstantArticle(Object) (Line: 189)
Facebook\InstantArticles\AMP\AMPArticle->toDOMElement(Object) (Line: 38)
Facebook\InstantArticles\Elements\Element->render('', 1) (Line: 145)
Facebook\InstantArticles\AMP\AMPArticle->render() (Line: 67)

Code:

$amp_article = AMPArticle::create($instant_article_html, $properties);
$amp_article->getObserver()->addFilter(
    'IA_IMAGE',
    function (
        /*DOMElement*/ $amp_image,
        /*Facebook\InstantArticles\Elements\Image*/ $ia_image,
        /*AMPContext*/ $context
    ) {
        // filter code
    },
    10,
    3
);
$amp_string = $amp_article->render();

Expected result

Adding a filter throws no exception and filter is executed.

Environment variable $GITHUB_TOKEN is not defined

For reference, see https://travis-ci.org/facebook/facebook-instant-articles-sdk-extensions-in-php/jobs/239783593#L212-L218.

example-quick-start.php has parsing error

Need to make it so so the example is included into tests, this way, any refactoring issue or any coding problem should be validated.

Parse error: parse error in facebook-instant-articles-sdk-extensions-in-php/src/Facebook/InstantArticles/AMP/Examples/example-quick-start.php on line 61

Example has a missing ;

• Add test case for example
• Fix ';' refactoring issue.