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.
Copied to your clipboard1/**2 * Interface for markdown library adapters3 */4namespace MyCompany\MyModule\Markdown\Parser\Adapter;56interface AdapterInterface7{8 /**9 * Converts markdown text into another format10 *11 * @param string $text12 * @return string13 */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.
Copied to your clipboard1namespace MyCompany\MyModule\Markdown\Parser\Adapter\PhpMarkdown;23use \Michelf\Markdown;4use MyCompany\MyModule\Markdown\Parser\Adapter\AdapterInterface;56/**7 * Adapter for php-markdown library8 */9class PhpMarkdown implements AdapterInterface10{11 /**12 * Convert markdown into HTML13 *14 * @param string $text15 * @return string16 */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.
Copied 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.
Copied to your clipboard1namespace MyCompany\MyModule\Markdown\Parser\Adapter\Ciconia;2use Ciconia\Ciconia;3use MyCompany\MyModule\Markdown\Parser\Adapter\AdapterInterface;45/**6 * Adapter for the Ciconia library7 */8class CiconiaParser implements AdapterInterface9{10 /**11 * @var Ciconia12 */13 protected $parser;1415 /**16 * @param Ciconia17 */18 public function __construct(Ciconia $parser)19 {20 $this->parser = $parser;21 }2223 /**24 * Convert markdown into HTML25 *26 * @param string $text27 * @return string28 */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.
Copied to your clipboard1<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>