Module scaffold

The module scaffold, ys_base, is a working custom module to build your project's own code on. It comes with a deploy file and a test scaffold already in place.

This page is for developers adding custom code to a project built from Vortex. It describes the custom modules the template ships, so you can decide what to build on, what to learn from, and what to remove. The installer's Custom modules question selects which of the base, search, and demo modules ship, and all 3 are selected by default. The installer still drops the search module when the Services question leaves out Solr, which that question selects by default. ys_migrate follows the Use a second database for migrations? question instead, which defaults to No. For the contributed modules, see Contributed modules.

Keep a custom ys_base module in your project to hold general-purpose code that doesn't belong in a dedicated, feature-specific module.

The ys prefix abbreviates your project's machine name (your_site here). Use the same prefix for all your custom modules, and the site machine name for the theme, so each module and theme shows which project it belongs to. The installer suggests both. Its Custom modules prefix question offers up to 4 characters from the machine name. A name with underscores gives the initials of its words, such as ys for your_site or sw for star_wars. A name without underscores gives its first 4 characters. Its Custom theme machine name question offers the machine name itself.

The your_site and ys names, and the other tokens like them, are placeholders. The installer replaces them with your project's own names when you install Vortex. The one exception is ys_migrate, which keeps its name.

Deploy file

The ys_base.deploy.php file is a Drush deploy file: Drush runs each of its ys_base_deploy_*() functions once, during site provisioning, and records which ones have run. Its single hook, ys_base_deploy_install_active_theme(), installs the core Olivero theme and sets it as the default, then does the same for the custom theme when the project has one.

Demo module

The ys_demo module demonstrates the integration patterns for 3 contributed modules:

• Drupal helpers - utility facades for deploy hooks
• Generated Content - plugin-based content generation
• Testmode - content filtering during Behat tests (declared as a dependency, so it installs together with ys_demo)

The demo module ships a pages view at /pages and a generated content plugin that populates it. It also ships the deploy hooks that place a counter block, add the Pages menu link, and register the view with Testmode. The counter block, with its CSS, JavaScript, and Twig template, also exercises the test tooling. It has Unit, Kernel, and FunctionalJavascript PHPUnit tests, a Jest test, and the counter.feature Behat feature.

To confirm the demo module works on a provisioned site, check the following:

• /pages lists 20 nodes whose titles start with Demo page, 10 per page.
• A Counter Block shows in the content region of the default theme.
• The main menu has a Pages link.

ahoy test-bdd -- --tags=@counter runs its Behat feature, and ahoy test-js runs its Jest test with those of the other custom modules.

Leaving the demo module out of the Custom modules question removes the following:

• The ys_demo module directory
• The drush pm:install ys_demo line in scripts/provision-00-enable-demo-modules.sh, the only block the template marks with CUSTOM_MODULE_DEMO
• The Behat features tagged @demo, which are counter.feature and pages.feature

Without the search module too, the installer also removes the recipes/page content model and the provisioning step that applies it. Drupal helpers stays a Composer requirement, but nothing installs it. Generated Content and Testmode follow their own entries in the Modules question, so scripts/provision-10-enable-dev-modules.sh still installs them.

Other shipped modules

2 more custom modules ship alongside the scaffold and demo modules:

• ys_search - configures the Search API index, the Solr server, and the search view for the Solr service, and brings in the workflows and content_moderation core modules. On install it uninstalls core's search module, and its deploy hook attaches an editorial workflow to the page content type. It ships only with the Solr service.
• ys_migrate - a demo migration module that migrates the categories table of the second database into tags terms. It ships only with the migration feature (see Migrations).

Tests scaffold

The ys_base module's tests directory holds a working example test and a base class for each PHPUnit test type: Unit, Kernel, Functional, and FunctionalJavascript. A new test then starts from something that already runs. It ships when PHPUnit is selected during installation.

To start a kernel test, copy tests/src/Kernel/ExampleTest.php and rename the file and the class. The copy extends YsBaseKernelTestBase, which the installer renames after your prefix. For a test in another module, put the copy in that module's tests/src/Kernel directory, set its namespace to Drupal\Tests\<module>\Kernel, and import the base class from Drupal\Tests\ys_base\Kernel. ahoy test-kernel runs it, because the kernel suite in phpunit.xml collects every web/modules/custom/**/tests/src/Kernel directory.

Its Traits directory adds the following 5 helper traits for writing tests:

• ArrayTrait
• AssertTrait
• BrowserHtmlDebugTrait
• MockTrait
• ReflectionTrait

Remove the ones you don't need.