civicrm-setup

civicrm-setup is a library for writing a CiviCRM installer. It aims to support multiple installers, such as the CLI command cv (cv core:install and cv core:uninstall) or per-CMS web-based installers (e.g. for civicrm-drupal or civicrm-wordpress).

General design:

• Installers call a high-level API (Civi\Setup) which supports all major installation tasks/activities -- such as:
  • Check system requirements ($setup->checkRequirements())
  • Check installation status ($setup->checkInstalled())
  • Install data files ($setup->installFiles())
  • Install database ($setup->installDatabase())
• A data-model (Civi\Setup\Model) lists all the standard configuration parameters. This data-model is available when executing each task. For example, it includes:
  • The path to CiviCRM's code ($model->srcPath)
  • The system language ($model->lang)
  • The DB credentials ($model->db)
• Each major task corresponds to an event -- such as:
  • civi.setup.checkRequirements
  • civi.setup.checkInstalled
  • civi.setup.installFiles
  • civi.setup.installDatabase
• Plugins (plugins/*/*.civi-setup.php) work with the model and the events. For example:
  • The plugin init/WordPress.civi-setup.php runs during initialization (civi.setup.init). It reads the WordPress config (e.g.get_locale() and DB_HOST) then updates the model ($model->lang and $model->db).
  • The plugin installDatabase/SetLanguage.civi-setup.php runs when installing the database (civi.setup.installDatabase). It reads the $model->lang and updates various Civi settings.

Key features:

• The library can be used by other projects -- such as cv, civicrm-drupal, civicrm-wordpress -- to provide an installation process.
• It is a leap. It can coexist with the old installer, and it lives in a separate project/repo which can be deployed optionally.
  • Example: The civicrm-wordpress integration is phasing-in support for the new installer. By default, it uses the old installer. If you create a file civicrm/.use-civicrm-setup, then it will use the new installer.
• It has minimal external dependencies. (The codebase for CiviCRM and its dependencies must be available -- but nothing else is needed.)

Documentation

• Getting started
• Writing an installer
• Writing a plugin
• Managing plugins