2011-02-07 07:48:44 +01:00
# Directory Structure
## Introduction
2018-09-06 01:43:49 +02:00
The directory-structure in SilverStripe is built on "convention over configuration", so the placement of some files and
2011-02-07 07:48:44 +01:00
directories is meaningful to its logic.
2016-04-25 11:55:33 +02:00
2011-02-07 07:48:44 +01:00
## Core Structure
2018-01-12 04:25:02 +01:00
Directory | Description
--------- | -----------
`public/` | Webserver public webroot
`public/assets/` | Images and other files uploaded via the SilverStripe CMS. You can also place your own content inside it, and link to it from within the content area of the CMS.
`public/resources/` | Exposed public files added from modules. Folders within this parent will match that of the source root location.
`vendor/` | SilverStripe modules and other supporting libraries (the framework is in `vendor/silverstripe/framework` )
`themes/` | Standard theme installation location
2011-02-07 07:48:44 +01:00
## Custom Code Structure
2018-06-25 00:39:53 +02:00
We're using `app/` as the default folder.
Note that until SilverStripe 4.2, this directory was named `mysite/` ,
and PHP code was stored in a `code/` rather than `src/` folder.
2011-02-07 07:48:44 +01:00
2017-06-22 12:50:45 +02:00
| Directory | Description |
| --------- | ----------- |
2018-06-25 00:39:53 +02:00
| `app/` | This directory contains all of your code that defines your website. |
| `app/_config` | YAML configuration specific to your application |
| `app/src` | PHP code for model and controller (subdirectories are optional) |
| `app/tests` | PHP Unit tests |
| `app/templates` | HTML [templates ](/developer_guides/templates ) with *.ss-extension for the `$default` theme |
| `app/css ` | CSS files |
| `app/images ` | Images used in the HTML templates |
| `app/javascript` | Javascript and other script files |
| `app/client` | More complex projects can alternatively contain frontend assets in a common `client` folder |
| `app/themes/<yourtheme>` | Custom nested themes (note: theme structure is described below) |
Arbitrary directory-names are allowed, as long as they don't collide with
existing modules or the directories lists in "Core Structure".
Here's how you would reconfigure your default folder to `myspecialapp` .
*myspecialapp/_config/config.yml*
```yml
---
Name: myspecialapp
---
SilverStripe\Core\Manifest\ModuleManifest:
project: 'myspecialapp'
```
2016-04-25 11:55:33 +02:00
Check our [JavaScript Coding Conventions ](javascript_coding_conventions ) for more details
on folder and file naming in SilverStripe core modules.
2011-02-07 07:48:44 +01:00
## Themes Structure
2017-06-22 12:50:45 +02:00
| Directory | Description |
| ------------------ | --------------------------- |
| `themes/simple/` | Standard "simple" theme |
| `themes/<yourtheme>/` | Custom theme base directory |
| `themes/<yourtheme>/templates` | Theme templates |
| `themes/<yourtheme>/css` | Theme CSS files |
2011-02-07 07:48:44 +01:00
2015-01-13 20:59:55 +01:00
See [themes ](/developer_guides/templates/themes )
2011-02-07 07:48:44 +01:00
2017-10-02 13:30:24 +02:00
## Module Structure {#module_structure}
2011-02-07 07:48:44 +01:00
2017-10-02 13:30:24 +02:00
Modules are commonly stored as composer packages in the `vendor/` folder.
They need to have a `_config.php` file or a `_config/` directory present,
and should follow the same conventions as posed in "Custom Site Structure".
2011-02-07 07:48:44 +01:00
Example Forum:
2016-04-25 11:55:33 +02:00
| Directory | Description |
| --------- | ----------- |
2017-10-02 13:30:24 +02:00
| `vendor/silverstripe/blog/` | This directory contains all of your code that defines your website. |
| `vendor/silverstripe/blog/code` | PHP code for model and controller (subdirectories are optional) |
2016-04-25 11:55:33 +02:00
| ... | ... |
2011-02-07 07:48:44 +01:00
2017-10-02 13:30:24 +02:00
Note: Before SilverStripe 4.x, modules were living as top-level folders in the webroot itself.
Some modules might not have been upgraded to support placement in `vendor/`
2011-02-07 07:48:44 +01:00
2012-09-02 02:30:11 +02:00
### Module documentation
Module developers can bundle developer documentation with their code by producing
plain text files inside a 'docs' folder located in the module folder. These files
2015-01-13 20:59:55 +01:00
can be written with the Markdown syntax (See [Contributing Documentation ](/contributing/documentation ))
2012-09-02 02:30:11 +02:00
and include media such as images or videos.
2017-10-02 13:30:24 +02:00
Inside the `docs/` folder, developers should organise the markdown files into each
2016-04-25 11:55:33 +02:00
separate language they wish to write documentation for (usually just `en` ). Inside
each languages' subfolder, developers then have freedom to create whatever structure
2015-01-13 20:59:55 +01:00
they wish for organising the documentation they wish.
2012-09-02 02:30:11 +02:00
2018-06-25 00:39:53 +02:00
Example Blog Documentation:
2012-09-02 02:30:11 +02:00
2016-04-25 11:55:33 +02:00
| Directory | Description |
| --------- | ----------- |
2018-06-25 00:39:53 +02:00
| `vendor/silverstripe/blog/docs` | |
| `vendor/silverstripe/blog/docs/_manifest_exclude` | Empty file to signify that SilverStripe does not need to load classes from this folder |
| `vendor/silverstripe/blog/docs/en/` | English documentation |
| `vendor/silverstripe/blog/docs/en/index.md` | Documentation homepage. Should provide an introduction and links to remaining docs |
| `vendor/silverstripe/blog/docs/en/Getting_Started.md` | Documentation page. Naming convention is Uppercase and underscores. |
| `vendor/silverstripe/blog/docs/en/_images/` | Folder to store any images or media |
| `vendor/silverstripe/blog/docs/en/Some_Topic/` | You can organise documentation into nested folders. Naming convention is Uppercase and underscores. |
| `vendor/silverstripe/blog/docs/en/04_Some_Topic/00_Getting_Started.md` |Structure is created by use of numbered prefixes. This applies to nested folders and documentations pages, index.md should not have a prefix.|
2012-09-02 02:30:11 +02:00
2011-02-07 07:48:44 +01:00
2014-11-15 04:01:47 +01:00
## Autoloading
2011-02-07 07:48:44 +01:00
2014-11-15 04:01:47 +01:00
SilverStripe recursively detects classes in PHP files by building up a manifest used for autoloading,
as well as respecting Composer's built-in autoloading for libraries. This means
in most cases, you don't need to worry about include paths or `require()` calls
in your own code - after adding a new class, simply regenerate the manifest
by using a `flush=1` query parameter. See the ["Manifests" documentation ](/developer_guides/execution_pipeline/manifests ) for details.
2011-02-07 07:48:44 +01:00
## Best Practices
### Making /assets readonly
2018-01-12 04:25:02 +01:00
See [Secure coding ](/developer_guides/security/secure_coding#filesystem )