civicrm/civicrm-setup

CiviCRM installation library

v0.3.0 2018-05-15 08:39 UTC

README

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