Jump to content
Jump to navigation
GitHub

Jump to heading Scaffolding a new app

Phabalicious has a simple but powerful app:scaffold-command. It will read a yml-file and interpret the contents. It will use the existing pattern-replacement used for scripts and twig for changing file-contents. The scaffolding and fixture-files can live on a remote server or on your file-system.

Here's an example of an app scaffold-file:

questions:
  name:
    question: "The Name of this project"
  shortName:
    question: "The short-name of this project"
    validation: "/^[A-Za-z0-9]{3,5}$/"
    error: "The shortname may consist of 3 to 5 letters (A-Z) or digits (0-9)"
    # Questions can have a default:
    default: "SP"
    transform: lowercase

variables:
  composerProject: drupal-composer/drupal-project:8.x-dev
  webRoot: web
  allowOverride: 0 # Setting it to 1 will not show a warning if the target folder exists.
  skipSubfolder: 0 # Setting it to 1 will instruct phabalicious to not create a subfolder.

assets:
  - .fabfile.yaml
  - docker-compose.yml
  - docker-compose-mbb.yml

deployModuleAssets:
  - deployModule/%shortName%_deploy.info.yml
  - deployModule/%shortName%_deploy.module
  - deployModule/%shortName%_deploy.install

scaffold:
  - rm -rf %rootFolder%
  - composer create-project %composerProject% %rootFolder% --stability dev --no-interaction
  - cd %rootFolder%; composer require drupal/coffee
  - cd %rootFolder%; composer require drupal/devel
  - copy_assets(%rootFolder%)
  - copy_assets(%rootFolder%/%webRoot%/modules/custom/%shortName%_deploy, deployModuleAssets)
  - cd %rootFolder%; git init .
  - cd %rootFolder%; git add .
  - cd %rootFolder%; git commit -m "Initial commit by phabalicious"

The fabfile needs at least the questionsand the scaffold-section. The scaffold-section is a list of commands, executed by phabalicious one by one. It will use the pattern-replacement known for scripts.

Jump to heading The questions-section

This section contains a list of questions to be asked when running the scaffold-command. The yaml-key will get the value inputted by the user and can be used as a replacement pattern or in twig-templates. Answers can be validated against a regex and/or transformed to lower- or uppercase.

The following question-types are supported:

Jump to heading question

A regular question, with optional default, validation and/ or autocomplete values. If hidden is true then the user wont see their input, ideal for sensitive data like passwords.

key:
  question: the prompot to show
  type: question
  validation: the regex to use to validate the input
  error: the message to display, if the validation fails
  default: the default-value, when the user hits return
  transform: [lowercase|uppercase]
  hidden: [true|false]
  autocomplete:
    - Option 1
    - Option 2
    - Option 3

Jump to heading array

A question, where the use can supply multiple values. The question gets repeated until the user provides an empty answer. For possible options see question.

Jump to heading confirm

A question which can be answered with yes or no. The value will be 1 or 0. The default value can be true or false.

key:
  question: Should we continue?
  type: confirm
  default: true

Jump to heading choices

Choices provides a list of options, where the user can pick one or many answers from:

key:
  question: What fruits do you want to buy
  type: choices
  multiselect: true
  choices:
    - Apples
    - Oranges
    - Lemons
    - Papayas
    - Coconuts

Jump to heading Non-interactive usage

For non-interactive usage you can pass the values via commandline-options, where the option-name is dash-cased version of the key, for the above example:

command-line option Question key
--[key] [key]
--name name
--short-name shortName

The scaffolder stores the answers in a hidden file called .phab-scaffold-tokens in the newly created folder and will reuse if the scaffolder runs aagain.

Jump to heading The scaffold-section

Phabalicious will provide the following replacement-patterns out of the box:

Pattern Value
%rootFolder% The folder the app will be installed into
%name% The name of the app
%projectFolder% a cleaned version of the app-name, suitable for machine-names.
%shortName% The short-name
%uuid% a random-uuid

Jump to heading the variables-section

You can add own variables via the variables-section. In the above example, the variable composerProject will be available in the scaffold-section via the pattern %composerProject%

Jump to heading the assets-section

You can have multiple assets-sections, assets is a default one. It contains a list if template files which will be processed by twig and placed at a specific location. You'll have all variables available as twig-variables inside the template, to use them, use {{ theNameOfVariable }} e.g. {{ name }} To add a new asset-section, use a new root-level key (in the above example this would be deploymentModuleAssets

The assets-paths must be relative to the yaml-file containing the scaffold-commands.

Jump to heading List of supported internal commands

  • copy_assets
  • alter_json_file
  • log_message

These are documented here.

Jump to heading Inheritance

Similar to other parts of Phabalicious, scaffold-files can use inheritance, for example to use the above scaffold-file, but install drupal commerce:

inheritsFrom:
  - drupal-8.yml
  -
variables:
  composerProject: drupalcommerce/project-base

This will inherit all content from the drupal-8.yml-file and merged with this content. This means, the `composerProject´-variable will be overridden, but everything else will be inherited. This makes it easy to reuse existing scaffold-files

Jump to heading Examples

Jump to heading Drupal 8 (d8.yml)

variables:
  composerProject: drupal-composer/drupal-project:8.x-dev
  webRoot: web
assets:
  - .fabfile.yaml
  - docker-compose.yml
  - docker-compose-mbb.yml

deployModuleAssets:
  - deployModule/%shortName%_deploy.info.yml
  - deployModule/%shortName%_deploy.module
  - deployModule/%shortName%_deploy.install

sshKeys:
  - ssh-keys/docker-root-key
  - ssh-keys/docker-root-key.pub
  - ssh-keys/known_hosts

scaffold:
  - rm -rf %rootFolder%
  - composer create-project %composerProject% %rootFolder% --stability dev --no-interaction
  - cd %rootFolder%; composer require drupal/coffee
  - cd %rootFolder%; composer require drupal/devel
  - copy_assets(%rootFolder%)
  - copy_assets(%rootFolder%/%webRoot%/modules/custom/%shortName%_deploy, deployModuleAssets)
  - copy_assets(%rootFolder%/ssh-keys, sshKeys)
  - cd %rootFolder%; git init .
  - cd %rootFolder%; git add .
  - cd %rootFolder%; git commit -m "Initial commit by phabalicious"

Jump to heading drupal commerce

inheritsFrom:
  - d8.yml

variables:
  composerProject: drupalcommerce/project-base

Jump to heading thunder

inheritsFrom:
  - d8.yml

variables:
  composerProject: burdamagazinorg/thunder-project
  webRoot: docroot

Jump to heading Laravel

Jump to heading the scaffold-file:

variables:
  composerProject: laravel/laravel:5.4
  webRoot: public

assets:
  - .fabfile.yaml
  - docker-compose.yml
  - docker-compose-mbb.yml

scaffold:
  - rm -rf %rootFolder%
  - composer create-project %composerProject% %rootFolder% --stability dev --no-interaction
  - copy_assets(%rootFolder%)
  - cd %rootFolder%; git init .
  - cd %rootFolder%; git add .
  - cd %rootFolder%; git commit -m "Initial commit by phabalicious"

Jump to heading the fabfile-template

name: {{ name }}
key: {{ shortName }}
deploymentModule: {{ shortName }}_deploy

requires: 2.0.0

needs:
  - ssh
  - composer
  - docker
  - git
  - files

hosts:
  mbb:
    host: {{ projectFolder }}.test
    user: root
    port: {{ 1024 + random(20000) }}
    type: dev
    rootFolder: /var/www/{{ webRoot }}
    gitRootFolder: /var/www
    backupFolder: /var/www/backups
    branch: develop
    database:
      name: {{ projectFolder|replace({'-': '_'}) }}_db
      user: root
      pass: admin
      host: mysql