Adapters

Adapter classes follow the adapter pattern and wrap around classes from third-party libraries. These classes allow you to use functionality from third-party libraries in your code by converting the third-party class interfaces into an interface that is expected by your native code.

When to use#

You should always use adapter classes instead of directly using classes from third-party libraries. This reduces the change impact on your code when the API changes in a third-party library.

We recommend using adapter classes for dependency injection to get access to the functionality provided by third-party classes.

How to write#

A common approach in developing an adapter is to create an interface named AdapterInterface to describe the functionality the third-party class provides. This class is typically found in a directory labeled Adapter. Classes implementing this adapter interface use the third-party class directly to provide indirect functionality.

This approach allows you to update or substitute different implementations provided by other third-party classes without the need to update code that uses your adapter.

Types#

Magento/Framework/Code/Minifier#

The minifier functionality provided by the Magento/Framework/Code library involves the use of third-party libraries for code compression.

The AdapterInterface for this class contains a minify($content) function that the CSSmin and JShrink implementation class define.

The jshrink(tedivm/jshrink) and cssmin(tubalmartin/cssmin) libraries registered in the composer.json file provide the functionalities for the implementation classes.

Magento/Framework/Image#

The Magento/Framework/Image library uses adapters to access functionality provided by GD(php-gd2) and ImageMagick(php-imagick) third-party libraries.

The AdapterInterface class defines the available functionality, and the Gd2 and ImageMagick adapter classes provides the concrete implementation using the third-party libraries.

Examples#

The code below describes an interface for an adapter that parses markdown.

/**
 * Interface for markdown library adapters
 */
namespace MyCompany\MyModule\Markdown\Parser\Adapter;

interface AdapterInterface
{
    /**
     * Converts markdown text into another format
     *
     * @param string $text
     * @return string
     */
    public function parse($text);
}
CopyCopied to your clipboard
1/**
2 * Interface for markdown library adapters
3 */
4namespace MyCompany\MyModule\Markdown\Parser\Adapter;
5
6interface AdapterInterface
7{
8    /**
9     * Converts markdown text into another format
10     *
11     * @param string $text
12     * @return string
13     */
14    public function parse($text);
15}

The code below is an implementation class of the AdapterInterface that uses the php-markdown library to convert markdown into HTML.

namespace MyCompany\MyModule\Markdown\Parser\Adapter\PhpMarkdown;

use \Michelf\Markdown;
use MyCompany\MyModule\Markdown\Parser\Adapter\AdapterInterface;

/**
 * Adapter for php-markdown library
 */
class PhpMarkdown implements AdapterInterface
{
    /**
     * Convert markdown into HTML
     *
     * @param string $text
     * @return string
     */
    public function parse($text)
    {
        return Markdown::defaultTransform($text);
    }
}
CopyCopied to your clipboard
1namespace MyCompany\MyModule\Markdown\Parser\Adapter\PhpMarkdown;
2
3use \Michelf\Markdown;
4use MyCompany\MyModule\Markdown\Parser\Adapter\AdapterInterface;
5
6/**
7 * Adapter for php-markdown library
8 */
9class PhpMarkdown implements AdapterInterface
10{
11    /**
12     * Convert markdown into HTML
13     *
14     * @param string $text
15     * @return string
16     */
17    public function parse($text)
18    {
19        return Markdown::defaultTransform($text);
20    }
21}

To configure the ObjectManager to use the PhpMarkdown implementation when the AdapterInterface class is requested as a dependency, add the following code in your di.xml file.

<preference for="MyCompany\MyModule\Markdown\Parser\Adapter\AdapterInterface" type="MyCompany\MyModule\Markdown\Parser\Adapter\PhpMarkdown\PhpMarkdown" />
CopyCopied to your clipboard
<preference for="MyCompany\MyModule\Markdown\Parser\Adapter\AdapterInterface" type="MyCompany\MyModule\Markdown\Parser\Adapter\PhpMarkdown\PhpMarkdown" />

The code below is an alternate implementation class of the AdapterInterface that uses the Ciconia library to parse markdown into HTML. This code differs from the previous implementations in that an instance of the Ciconia class is a constructor dependency.

namespace MyCompany\MyModule\Markdown\Parser\Adapter\Ciconia;
use Ciconia\Ciconia;
use MyCompany\MyModule\Markdown\Parser\Adapter\AdapterInterface;

/**
 * Adapter for the Ciconia library
 */
class CiconiaParser implements AdapterInterface
{
    /**
     * @var Ciconia
     */
     protected $parser;

    /**
     * @param Ciconia
     */
    public function __construct(Ciconia $parser)
    {
        $this->parser = $parser;
    }

    /**
     * Convert markdown into HTML
     *
     * @param string $text
     * @return string
     */
    public function parse($text)
    {
        return $this->parser->render($text);
    }
}
CopyCopied to your clipboard
1namespace MyCompany\MyModule\Markdown\Parser\Adapter\Ciconia;
2use Ciconia\Ciconia;
3use MyCompany\MyModule\Markdown\Parser\Adapter\AdapterInterface;
4
5/**
6 * Adapter for the Ciconia library
7 */
8class CiconiaParser implements AdapterInterface
9{
10    /**
11     * @var Ciconia
12     */
13     protected $parser;
14
15    /**
16     * @param Ciconia
17     */
18    public function __construct(Ciconia $parser)
19    {
20        $this->parser = $parser;
21    }
22
23    /**
24     * Convert markdown into HTML
25     *
26     * @param string $text
27     * @return string
28     */
29    public function parse($text)
30    {
31        return $this->parser->render($text);
32    }
33}

The following dependency injection entries belong in the di.xml file. They describe to the ObjectManager how to create the third-party and adapter classes.

<virtualType name="defaultCiconia" type="Ciconia\Ciconia" shared="false">
   <arguments>
       <argument name="renderer" xsi:type="null"/>
   </arguments>
</virtualType>
<type name="MyCompany\MyModule\Markdown\Parser\Adapter\Ciconia\CiconiaParser">
   <arguments>
       <argument name="parser" xsi:type="object">defaultCiconia</argument>
   </arguments>
</type>
CopyCopied to your clipboard
1<virtualType name="defaultCiconia" type="Ciconia\Ciconia" shared="false">
2   <arguments>
3       <argument name="renderer" xsi:type="null"/>
4   </arguments>
5</virtualType>
6<type name="MyCompany\MyModule\Markdown\Parser\Adapter\Ciconia\CiconiaParser">
7   <arguments>
8       <argument name="parser" xsi:type="object">defaultCiconia</argument>
9   </arguments>
10</type>