Criando templates Twig personalizados para módulos personalizados

A ideia geral no Drupal 8 é que você queira evitar criar HTML diretamente no código PHP do seu módulo personalizado. Você quer que isso vá para templates Twig. Para criar novos templates Twig no seu módulo, siga estas etapas.

Etapa #1: Defina hook_theme no arquivo .module
Crie um arquivo [module].module, se ainda não existir, e adicione código que defina cada um dos seus templates Twig. A chave de cada elemento no array é o que você precisará chamar do template mais tarde. Não use hífens no nome do arquivo.

function test_twig_theme($existing, $type, $theme, $path) {
  return [
    'my_template' => [
      'variables' => ['test_var' => NULL],
    ],
  ];
}

Veja a documentação de hook_theme().

Etapa #2: Chamar o template
No local onde você retorna seu array de renderização (de um método do controlador, que é chamado de um arquivo yml do seu roteador, ou em qualquer outro lugar), chame o template Twig. Abaixo está um exemplo de um módulo de teste que é chamado de um arquivo yml de roteamento no módulo. (mais informações sobre esta parte são necessárias)

/**
 * @file
 * Contains \Drupal\test_twig\Controller\TestTwigController.
 */

namespace Drupal\test_twig\Controller;

use Drupal\Core\Controller\ControllerBase;

class TestTwigController extends ControllerBase {
  public function content() {

    return [
      '#theme' => 'my_template',
      '#test_var' => $this->t('Test Value'),
    ];

  }
}

Você também pode usar o método de renderização para construir a saída, se precisar usá-la como parte de outro fluxo de trabalho em seu código: -

$renderable = [
  '#theme' => 'my_template',
  '#test_var' => 'test variable',
];
$rendered = \Drupal::service('renderer')->renderPlain($renderable);

Tenha em mente que esta é uma implementação básica que não realiza nenhum armazenamento em cache. A documentação Render API Overview contém mais informações sobre como você pode adicionar cache a isso. Falando em cache - os nomes das variáveis serão armazenados em cache, e se você alterá-los (digamos, "test_var" para "my_var"), você terá que recriar o cache.

Etapa #3: Criar um template Twig
No seu módulo, dentro da pasta de templates, crie um template Twig. O nome do arquivo deve coincidir com o que você colocou em hook_theme() (substitua o sublinhado por um hífen). Neste caso, o nome do arquivo será my-template.html.twig.
Aqui está o arquivo que usei para teste:

<p>Test twig template!</p>

<p>test_var: {{ test_var }}</p>

A beleza disso é que o arquivo de template definido no seu módulo será usado se ainda não houver um arquivo desse tipo no seu tema. Simplesmente coloque o arquivo na pasta de templates de seu tema, limpe o cache (drush cache-rebuild), e ele lerá esse arquivo.

Você pode colocar o arquivo em qualquer subpasta aninhada do tema do site para manter tudo organizado.