Encapsulating the Deepl API in a data source


In the previous tutorial, we saw how to create a data source that encapsulates the OpenWeatherMap service API. Now we're going to create another data source, one that provides access to the Deepl translation service API, which can be used to easily translate texts.


In the etc/temma.php configuration file, we're going to add the definition of a rather special data source. As this is not a data source natively managed by Temma, we'll prefix the DSN with the name of the object to be used (in square brackets).

The DSN will take the form deepl://API_KEY@DEFAULT_LANG
API_KEY being the API key provided by OpenWeatherMap, and DEFAULT_LANG being the default language into which texts will be translated.

Example configuration:


return [
    "application" => [
        "dataSources" => [
            "transl" => '[\Deepl\Translate]deepl://0123456789abcdef0123456789abcdef@EN'

3Source code

Here's the code for our data source, which we'll save in the lib/Deepl/Translate.php file:


namespace Deepl;

class Translate extends \Temma\Base\Datasource {
    /** Constant: DSN prefix. */
    const DSN_SCHEME = 'deepl://';
    /** Constant: URL of Deepl API. */
    const API_URL = 'https://api-free.deepl.com/v2/translate';
    /** API access key. */
    private string $_key;
    /** Default translation language. */
    private string $_lang;

     * Factory. Creates an instance of the object from a DSN.
     * @param   string   $dsn   Configuration string.
     * @return  \Deepl\Translate    The instantiated object.
     * @throws  \Exception   If the DSN is incorrect.
    static public function factory(string $dsn) : \Deepl\Translate {
        // DSN interpretation
        $parts = parse_url($dsn);
        $scheme = $parts['scheme'] ?? null;
        $key = $parts['user'] ?? null;
        $lang = $parts['host'] ?? null;
        // checks
        if ($scheme != self::DSN_SCHEME || !$key || !$lang) {
            throw new \Exception("Invalid Deepl DSN '$dsn'.");
        return (new self($key, $lang));
     * Constructor.
     * @param   string   $key    API access key.
     * @param   string   $lang   Default translation language.
    public function __construct(string $key, string $lang) {
        $this->_key = $key;
        $this->_lang = $lang;
     * Translation of a text into the default language.
     * @param   string   $text     Text to be translated.
     * @param   mixed    $default  Unused parameter (required for inheritance reasons).
     * @param   mixed    $options  Unused parameter (required for inheritance reasons).
     * @return  mixed    The translated text.
     * @throws  \Exceptions   If an error has occurred.
    public function get(string $text, mixed $default=null, mixed $options=null) : mixed {
        $this->translate($text, $this->_lang);
     * Translates a text into a specific language.
     * @param   string   $text         Text to be translated
     * @param   string   $lang         Translation language.
     * @param   ?string  $sourceLang   (optionnel) Language of text to be translated.
     *                                 Deepl automatically detects it by default.
     * @return  string   The translation of the text, or an empty string if the text could not be translated.
     * @throws  \Exception       If an error has occurred.
    public function translate(string $text, string $lang, ?string $sourceLang=null) : string {
        // setting up data to be sent
        $data = [
            'text'        => [$text],
            'target_lang' => $lang,
        if ($sourceLang) {
            $data['source_lang'] = $sourceLang;
        $data = json_encode($data);

        // API call
        $curl = curl_init(self::API_URL);
        curl_setopt($curl, CURLOPT_CUSTOMREQUEST, 'POST');
        curl_setopt($curl, CURLOPT_POST, true);
        curl_setopt($curl, CURLOPT_POSTFIELDS, $data);
        curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($curl, CURLOPT_SSL_VERIFYPEER, false);
        curl_setopt($curl, CURLOPT_CONNECTTIMEOUT, 3);
        curl_setopt($curl, CURLOPT_HTTPHEADER, [
            'Authorization: DeepL-Auth-Key ' . $this->_key,
            'Content-Type: application/json',
        $result = curl_exec($curl);
        if ($result === false)
            throw new \Exception(curl_error($curl));

        // result retrieval
        $result = json_decode($result, true);
        return ($result['translations'][0]['text'] ?? '');
  • Lines 21 to 32: factory() method, called by Temma when the data source is created. This method interprets the DSN and calls the constructor.
  • Lines 38 to 41: Constructor, used to create an instance of the object directly.
  • Lines 50 to 52: get() method, which overrides that of the parent \Temma\Base\Datasource object, and calls the object's translate() method. This method can be used directly, but is also called automatically when the object is read as an array.
  • Lines 62 to 93: translate() method, which connects to the Deepl API to perform a translation. This method takes the text to be translated and the translation language as parameters. It can also take the source language, if you wish to translate a text in a language other than the default language defined in the configuration.
  • Lines 64 to 71: Creation of the data table to be sent to the Deepl API, after being serialized in JSON.
  • Lines 74 to 88: Connection to the Deepl API, sending the data and retrieving the return.
  • Lines 91 and 92: Unserialize recovered data and return method.


In a controller, the data source named "transl" in the configuration file is available in controllers by writing $this->trad. Text can be translated to the default language defined in configuration by calling the get() method or by using it as an array:

// using the get() method
$englishText = $this->transl->get('Bonjour, comment allez-vous ?');
// write as an array
$englishText = $this->transl['Bonjour, comment allez-vous ?'];

To define a different translation language, or to define the source language, use the translate() method:

$germanText = $this->transl->translate('Hi, how are you?', 'DE', 'EN');

Apart from controllers, you must use the dependency injection component:

$englishText = $this->_loader->transl->get('Bonjour, comment allez-vous ?');
$englishText = $this->_loader->transl['Bonjour, comment allez-vous ?'];
$germanText = $this->_loader->transl->translate('Hi, how are you?', 'DE', 'EN');