VMLY&R's Drupal KIT is a project scaffold distribution which helps build and maintain Drupal projects.
GPL-2.0 License
VMLY&R's Drupal 9 KIT is a distribution which helps build and maintain Drupal 9 projects.
Via a suite of Docksal commands, an installation profile, and a base theme, the distribution provides support for the following:
KIT uses composer for handling project dependencies. The distribution includes a selection of Modules and libraries by default. The list was determined using either the following criteria:
KIT enforces structure by adding it's own scaffolding, which runs after Drupal's default scaffolding on composer install and update. Drupal's scaffolding automatically wipes and re-copies the files which get copied outside of Drupal core and into public directories (like default.settings.php, htaccess, robots.txt, etc.). VMLY&R additionally creates the standard config folder structure, as well as removes and updates files that should be modified via patches (like .htaccess) or compiled (like drupal.settings.additional.php compiling into drupal.settings.php) instead of being checked-into the repository directly.
The project uses Docksal for local-environment development and project-building. The following is a list of Docksal commands that come included in the project:
init
Typically used when building or rebuilding the projectbuilder
, which is explained in detail below under theinit-deps
Used when project dependencies need to be redownloadedinit-services
Used when project-based command and tool dependenciesk
A simple wrapper command to make it easier to run kit commands.fin k gulp
instead of fin kit/gulp
.pre-deploy
This is used in situations where there needs to beAdditional commands are included via the vmlyr-drupal/kit-docksal-commands
package and installed under a "kit" sub directory in the docksal commands
directory. See the README.md file in that directory after composer is
installed for more information on those commands.
Docksal and KIT's commands can be used for running build processes. The
command init
can toggle "CI mode" by running appending the
ci
command: fin init ci
. This is best used when
docksal is used to create the build files to be released. By default,
the builder runs composer in --no-dev mode, and auto-removes
build-related files amound other things.
This composer project comes with 2 VMLY&R-created Drupal profiles:
fin kit/theme
and generate a new theme off of theMulti-environment configuration is pre-configured as part of the
distribution via the default settings.php
file and the Biplane and Blackbird profiles.
The each site's default settings.php file
includes the
/sites/environment.settings.php
, which has configuration to toggle the
status of relevant configuration based on the current site's
environment. Remote environments, such as those hosted by Acquia,
Pantheon, or Platform.sh, have $_ENV
or $_SERVER
variables which
tell the site that it is a certain environment and to enable certain
configuration or settings. When working on the site locally, all
configuration splits should say either "inactive". The "local"
config_split status is only enabled by the fin command conf
on
export/import. This makes sure that configuration can be exported
regularly without a certain environment taking accidental precedence.
Development and docksal settings files are automatically included via
the environment.settings.php
file, if they exist. These files are
ignored by git and helpful for development overrides such as disabling
cache or allowing verbose error reporting. The KitScriptHandler script,
which is ran by composer, automatically copies a settings.local.php
and settings.docksal.php
into each sites directories to better assist
local development.
The VMLY&R profiles include config-split options by default, and have additional tasks during install to establish the default configuration and each split's configuration, as well as import as the local environment before the installation is complete.
The four included default configurations include:
Multi-site support is baked into the project via our supplied Docksal
tools. When another site needs to be added, it's as simple as creating a
the new drush alias file and running composer install
. The command will
build out the site folder structure, copy the default settings.php file
into the site directory and is then ready for installation. The kit/sync
and kit/conf
tools both support syncing and exporting/importing any
site in a multi-site Drupal instance.
KIT automatically includes a base theme (Bazo) and two scaffolding themes which use Bazo as a base theme.
The Bazo base theme is meant to help assist its child-themes. It includes standard templates but moves most of the classes into its preprocesses to allow them to be more-easily removed later by the child preprocess. The two more-important factors of the subtheme are:
Automatic Drupal library attachment Bazo automatically attaches child-theme libraries to their related entities as long as they follow a naming convention:
This not only helps your project stay organized, but it allows front-end developers to attach their libraries to components without needing to touch PHP.
Note: notice the entity-id--view-mode--bundle is different than Drupal's default theme-name convention of entity-id--bundle--view-mode. This was done purposely, because typically all bundles of a certain view-mode will share a library versus all view-modes sharing a library of a certain bundle. This allows a universal library to be included for view-modes and then more-specific implementations that are bundle-specific also be included .
Automatic attribute-variable conversion Baso automatically converts
specified arrays to attribute variables in a "postprocess" function
that are listed in the preprocess's
$variables['#attribute_variables']
array. IE:
$variables['#attribute_variables'][] = 'figcaption_attributes';
$variables['#attribute_variables'][] = 'wrapper_attributes';
$variables['#attribute_variables'][] = 'figcaption_attributes';
$variables['#attribute_variables'][] = 'image_attributes';
VMLY&R has a couple scaffolding themes included to build from, but
they're not included in the project directly. Instead they can be
generated via the fin kit/theme
command.
Getting a running site takes only a few steps for a project.
Install Docksal if it's not already installed.
Install the project.
fin run-cli "composer create-project --no-install vmlyr-drupal/kit [FOLDER_NAME_HERE]"
cd [FOLDER_NAME_HERE]
git init
git remote add origin [REMOTE_REPOSITORY_URL_HERE]
Run fin start
in the project to create the Docksal project.
Open each site's Drush alias file (/drush/sites/
to update the
local URI as well as any relevant server information if it's already
known. (note: Your local should have been listed by Docksal at the end
of running fin start
)
If running a multisite install, open /sites/sites.php
folder to
make sure domains are mapped to the correct site.
Docksal's domain name is the project folder name in alphanumeric appended with .docksal. (I.E. drupal-8-kit becomes drupal8kit.docksal)
$sites['domainname.docksal'] = 'www';
$sites['www.domainname.docksal'] = 'www';
External domains are mapped here as well.
$sites['www.domainname.com'] = 'www';
$sites['dev-www.domainname.com'] = 'www';
$sites['stg-www.domainname.com'] = 'www';
$sites['prod-www.domainname.com'] = 'www';
Docksal supports subdomains, and Drupal supports mapping subdomains on a multi-site install.
$sites['subdomain.domainname.docksal'] = 'subdomain';
External subdomains are mapped here as well.
$sites['subdomain.domainname.com'] = 'subdomain';
$sites['dev-subdomain.domainname.com'] = 'subdomain';
$sites['stg-subdomain.domainname.com'] = 'subdomain';
$sites['prod-subdomain.domainname.com'] = 'subdomain';
Run fin init
Open a browser and go to the site; it should have been redirected to the site install page.
Walk through the install process. (note: the site should
automatically start installing after a profile is selected; if it
doesn't, and it asks for database settings, reload the
/core/install.php
URL without any GET parameters)
Fill out the site configuration. If using either of the VMLY&R
Profiles and the environment URLs are unknown, make a best guess at what
they could be
(we suggest following the //ENV-WWW.SITE_PROD.DOMAIN
structure).
The domains are used for indicating current environment and using other
environment's assets via Stage File Proxy. Setting these up now helps
not needing to set these in multiple places later on during development.
If you selected either of the VMLY&R profiles, upon saving configuration, the site should export all relevant configuration into the site's sync directory and import as the local environment.
Installation is complete once redirected to the homepage of the site.
To start building your own theme, run fin kit/theme
to
generate a new theme + theme source setup based on our example scaffold
themes. If the Blackbird profile was installed, we suggest scaffolding
from the Blackbird theme option of the same name. If you're not using
Blackbird and want a more simple starting point for you theme we
suggest scaffolding from Biplane scaffold theme.
Based on the hosting provider, some configuration needs to be created or updated. Similarly, some configuration will also be unneeded and can be removed.
@TODO Jenkins setup walk-through.
To enable bitbucket pipeline builds, rename bitbucket-pipelines-example.yml
to bitbucket-pipelines.yml
. Note: Bitbucket Pipelines needs to be
enabled in bitbucket to work.
There is a small amount of configuration to get pipelines talking to your external repository after copying the pipelines file into the repository. In your Bitbucket account:
DESTINATION_REPOSITORY
with the url to your hosting providers repository (example: ssh://codeserver.example.drush.in:2222/~/repository.git
for Pantheon).deployment
key:value inside your pipelines file (example: deployment: Development
)DESTINATION_REPOSITORY_BRANCH
and put the value as the branch you want to push into on your hosting providers repository (example: master
).ssh-keygen -b 4096
in your local terminal (consider naming it something descriptive) and then adding its private and public keys to Bitbucket.
Note: sometimes it takes some playing-around-with to make sure that pipelines can connect to the hosting-provider repository, such as recreating the key pairs.
This pipeline watches the master branch, and when code is merged into it, automatically builds and deploys the code to the relevant "Development" environment repository.
This pipeline uses the default "Build package" and "Deploy package" pipeline steps. The "Deploy package" step defaults to run the "Development" deployment.
In scenarios where there should be a development branch building to the Development environment, and the master branch building to Stage or Production environments, the deployment
would be changed to the relevant environment name, and a new branch-based pipeline would be created to push to Development.
This pipeline takes any branch and allows to build to a custom "feature" branch on the hosting provider repository. This allows for easily creating "Feature" environments on the hosting provider.
This pipeline uses the default "Build package" and "Deploy package" pipeline steps. "The Deploy package" step defaults to run a "Feature" deployment, which will need to be created under the Settings > Pipelines > Deployments tab on Bitbucket Pipelines.
To run this pipeline:
This pipeline automatically runs on pull-requests. It does a full build and then lints the code; it fails if any issues arise.
This pipeline uses the default "Build package" and "Test package" pipeline steps. It does not deploy code.
The following are grouped to give context for which files/directories can be modified or removed.
/hooks/common
/hooks/dev
/hooks/prod
/hooks/samples
/hooks/test
/.ebextensions
/pantheon.yml
/scripts/pantheon/*
/docroot/web.config
(we don't typically use ASP.NET; kept for reference if needed in the project)/env.example
(we don't suggest env files; kept for reference if needed in the project)/package.json
(was used by packagist to create project and no longer needed)/travis.yml
(we don't typically use travis; kept for reference if needed in the project)Modifications to make to the project based on which hosting provider is chosen.
/docroot/sites/www/settings.php
and find the "Include server-specific configuration." section./docroot/sites/www/settings.php
and find the "Include server-specific configuration." section.rm -rf files
to remove current files directory.ln -s ../default/files files
to create symlink to default files directory (which is then symlinked to /files on Pantheon's end). Make sure that a /default/files directory exists locally so files have a place to go.git add files
and commit symlink to repo./web/private/scripts
directory./scripts/pantheon/post_deploy.php
file into /web/private/scripts
./scripts/pantheon
folder.www
(or relevant sites directory)./web/sites/www/settings.php
and find the "Include server-specific configuration." section.www
(or relevant sites directory)./docroot/sites/www/settings.php
and find the "Include server-specific configuration." section.@TODO Some files and configuration are missing for Platform.sh, which still needed to be included in KIT.
Some providers require a different docroot directory.
docroot
directory to web
.docroot
references to web
in the following files:
/.docksal/docksal.env
/.gitignore
/composer.json
(will need to run composer install afterward to regenerate autoload.php file)/drush/*
files (/drush/sites/www.site.yml
, etc.)/patches/htaccess.patch
/source/gulpfile.js
/source/eslintrc.js
www.domainname.com
dev-www.domainname.com
stg-www.domainname.com
prod-www.domainname.com (for pre-go-live)
We've found that adding an environment prefix to the production url is a low-effort/high-reward action. This allows for environment URLs that are easier to remember and access, both for those working on the site and for clients.
When creating a new theme using the fin kit/theme
command you'll have two directory structures created for you:
docroot/themes/custom/yourtheme - This is meant to only contain the files Drupal needs to render the site - e.g. css, javascript, images, template files. It does not contain any source files used to generate those files (e.g. sass files). It's important to note that some files under this directory are generated (see next point) and some (e.g. template files) should be edited directly.
source/themes/custom/yourtheme - Contains all of the source files used to generate the files in docroot/themes/custom/yourtheme.
Gulp is used to process the files in source and writes the corresponding output to the matching theme directory under docroot. The default gulp file (source/gulpfile.js) is set up with a set of basic tasks needed by most themes. It is also set up to run those tasks in all of the directories under source/themes/custom. This allows the developer to have multiple themes (e.g. a base theme and child themes) under development and use a single command to build them all.
The following functionality is provided by the default gulp file:
Tasks provided by the default gulp file are: