Newer
Older
CiviCRM installs within a content-management system (CMS), and each CMS has a
different file structure. Never-the-less, the general concepts are the same:
one directory contains the CiviCRM **codebase**, another directory
contains **local data files**, and a third contains the CiviCRM **settings file**.
## Codebase
The codebase consists of the common CiviCRM code (found in the
[civicrm-core](https://github.com/civicrm/civicrm-core/) and
[civicrm-packages](https://github.com/civicrm/civicrm-packages/) repositories)
along with the code to integrate with the CMS. Obviously, Drupal and Backdrop
modules, Joomla components, and WordPress plugins have different structures, so
the [civicrm-drupal](https://github.com/civicrm/civicrm-drupal/),
[civicrm-backdrop](https://github.com/civicrm/civicrm-backdrop/),
[civicrm-joomla](https://github.com/civicrm/civicrm-joomla/), and
[civicrm-wordpress](https://github.com/civicrm/civicrm-wordpress/) repositories
contain the code connecting CiviCRM to the CMS along with some CMS-specific
features.
### Drupal and Backdrop
The CiviCRM module is typically found in the `sites/all/modules/civicrm`
directory. As with any Drupal module, it is possible to put CiviCRM in
several alternative folders, such as:
* `sites/example.com/modules/civicrm`
* `sites/default/modules/civicrm`
* `sites/all/modules/civicrm` (most common)
* `modules/civicrm`
Within the `civicrm` folder, there will be a
[`drupal/`](https://github.com/civicrm/civicrm-drupal/) or
[`backdrop/`](https://github.com/civicrm/civicrm-backdrop/) subfolder which
contains the `civicrm.module` along with the role sync modules, blocks, and
drush and views integration.
### Joomla
CiviCRM's codebase exists in *two* places within Joomla:
- A front-end component at `components/com_civicrm`
- A back-end component at `administrator/components/com_civicrm`
The back-end component contains the common CiviCRM code, in
`administrator/components/com_civicrm/civicrm`. The
[civicrm-joomla](https://github.com/civicrm/civicrm-joomla/) repository contains
a `site` directory for the front-end files and an `admin` directory for the
back-end files.
### WordPress
The CiviCRM plugin is found in `wp-content/plugins/civicrm`. This corresponds
to the [civicrm-wordpress](https://github.com/civicrm/civicrm-wordpress/)
repository, containing the plugin file as well as WP-CLI integration. The
common CiviCRM codebase is found at `wp-content/plugins/civicrm/civicrm`.
### Tip: Programmatic lookup
If you are writing an extension or integration that needs to reference the
codebase of an existing installation, use a command to lookup the correct
value. In `bash`, call the [`cv`](https://github.com/civicrm/cv)
command-line tool:
```
$ cv path -d '[civicrm.root]'
$ cv path -d '[civicrm.root]/README.md'
$ cv url -d '[civicrm.root]'
$ cv url -d '[civicrm.root]/README.md'
```
Or in PHP, use `Civi::paths()`:
```php
echo Civi::paths()->getPath("[civicrm.root]/.");
echo Civi::paths()->getPath("[civicrm.root]/README.md");
echo Civi::paths()->getUrl("[civicrm.root]/.");
echo Civi::paths()->getUrl("[civicrm.root]/README.md");
```
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
## Codebase: Dependencies
The CiviCRM codebase includes some third-party libraries. These are pulled
into three folders:
* __`vendor`__ is collection of PHP libraries which are automatically downloaded
by [`composer`](http://getcomposer.org/) based on the `composer.json` configuration.
* __`bower_components`__ is a collection of JS/CSS libraries which are automatically
downloaded by [`bower`](https://bower.io/) based on the `bower.json` configuration.
* __`packages`__ is a manually curated collection of library files.
It's maintained in [`civicrm-packages.git`](https://github.com/civicrm/civicrm-packages/).
!!! note "When adding a new dependency to core, use `composer.json` or `bower.json`."
### Tip: Programmatic lookup
Traditionally, one would use the root folder of `civicrm-core` to determine the path
or URL of a library, as in:
```php
global $civicrm_root;
echo "$civircm_root/packages/IDS/default_filter.xml";
```
This arrangement works, but it assumes that all three folders are immediate
descendents of the `civicrm-core` folder -- which may not hold in the
future.
In CiviCRM v4.7.21+, one should use `Civi::paths()` to lookup the path or
URL for a library:
```php
echo Civi::paths()->getPath('[civicrm.vendor]/dompdf/dompdf/README.md');
echo Civi::paths()->getUrl('[civicrm.vendor]/dompdf/dompdf/README.md');
echo Civi::paths()->getPath('[civicrm.bower]/jquery/dist/jquery.min.js');
echo Civi::paths()->getUrl('[civicrm.bower]/jquery/dist/jquery.min.js');
echo Civi::paths()->getPath('[civicrm.packages]/IDS/default_filter.xml');
echo Civi::paths()->getUrl('[civicrm.packages]/IDS/default_filter.xml');
```
Additionally, to register JS/CSS resources in `Civi::resources()`, you can use
a shorthand with the path variables, as in:
```php
echo Civi::resources()->addScriptFile('civicrm.bower', 'jquery/dist/jquery.min.js');
```
CiviCRM also needs a files directory for storing a variety of site-specific
files, including uploaded files, logs, and the template cache. This directory
is located away from the codebase in a location that is unlikely to be
overwritten during upgrades.
### Drupal and Backdrop
CiviCRM stores its files in a folder named `civicrm` within the site-specific
files directory. This is commonly `sites/default/files/civicrm`, though it
could be `files/civicrm`, `sites/example.org/files/civicrm`, or another
folder determined by the system administrator.
### Joomla
The CiviCRM local files are within the `media/civicrm` directory.
### WordPress
Newly-installed CiviCRM sites on WordPress have their local files at
`wp-content/uploads/civicrm`. Many older sites use the previous default:
`wp-content/plugins/files/civicrm`.
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
### Tip: Programmatic lookup
If you are writing an extension or integration that needs to reference the
data files of an existing installation, use a command to lookup the correct
value. In `bash`, call the [`cv`](https://github.com/civicrm/cv)
command-line tool:
```
$ cv path -d'[civicrm.files]'
$ cv path -d'[civicrm.files]/upload'
$ cv url -d'[civicrm.files]'
$ cv url -d'[civicrm.files]/upload'
```
Or in PHP, use `Civi::paths()`:
```php
echo Civi::paths()->getPath("[civicrm.files]/.");
echo Civi::paths()->getPath("[civicrm.files]/upload");
echo Civi::paths()->getUrl("[civicrm.files]/.");
echo Civi::paths()->getUrl("[civicrm.files]/upload");
```
Additionally, some items -- such as the log folder or cache folder -- are
configurable. The most correct way to find these is to read a config
variable. In `bash`:
```
$ cv path -c configAndLogDir
$ cv path -c templateCompileDir
$ cv path -c templateCompileDir/en_US
```
Or in PHP:
```
echo CRM_Core_Config::singleton()->configAndLogDir;
echo CRM_Core_Config::singleton()->templateCompileDir;
echo CRM_Core_Config::singleton()->templateCompileDir . '/en_US';
```
## Settings file
CiviCRM's database connection, base URL, site key, CMS, and file paths are defined in `civicrm.settings.php`.
### Drupal and Backdrop
The `civicrm.settings.php` file will be a sibling of Drupal's `settings.php`,
commonly at `sites/default/civicrm.settings.php`, or
`sites/example.org/civicrm.settings.php` in multi-site.
In Backdrop, the `civicrm.settings.php` is often located in the site root.
### Joomla
There are two instances of `civicrm.settings.php` in Joomla, within each of the
components:
- front-end at `components/com_civicrm/civicrm.settings.php`
- back-end at `administrator/components/com_civicrm/civicrm.settings.php`
The files are *nearly* identical. The one difference is that the front-end file
has the site's normal base URL, while the back-end file has `/administrator/` on
the end, pointing to the back-end of the site.
### WordPress
Newly-installed CiviCRM sites on WordPress have the settings file at
`wp-content/uploads/civicrm/civicrm.settings.php`. Many older sites, however,
put the settings file within the CiviCRM plugin folder at
`wp-content/plugins/civicrm/civicrm.settings.php`. This latter location can be
dangerous when upgrading: it is important in this case to keep the `civicrm`
folder until the upgrade is complete and the site is verified to be working
properly.
### Tip: Programmatic lookup
If you are writing an extension or integration that needs to reference the
settings of an existing installation, use the constant
`CIVICRM_SETTINGS_PATH` to locate `civicrm.settings.php`. In `bash`:
```
$ cv ev 'echo CIVICRM_SETTINGS_PATH;'
```
Or in PHP:
```php
echo CIVICRM_SETTINGS_PATH;
```