2011-02-07 07:48:44 +01:00
# Directory Structure
## Introduction
2011-03-08 22:05:51 +01:00
The directory-structure in SilverStripe it 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
We're using `<mysite>` as an example - arbitrary directory-names are allowed, as long as they don't collide with
2011-03-08 22:05:51 +01:00
existing modules or the directories lists in "Core Structure".
2011-02-07 07:48:44 +01:00
2017-06-22 12:50:45 +02:00
| Directory | Description |
| --------- | ----------- |
2016-04-25 11:55:33 +02:00
| `<mysite>/` | This directory contains all of your code that defines your website. |
| `<mysite>/_config` | YAML configuration specific to your application |
2017-06-22 12:50:45 +02:00
| `<mysite>/src` | PHP code for model and controller (subdirectories are optional) |
| `<mysite>/tests` | PHP Unit tests |
| `<mysite>/templates` | HTML [templates ](/developer_guides/templates ) with *.ss-extension for the `$default` theme |
2016-04-25 11:55:33 +02:00
| `<mysite>/css ` | CSS files |
| `<mysite>/images ` | Images used in the HTML templates |
2017-06-22 12:50:45 +02:00
| `<mysite>/javascript` | Javascript and other script files |
2016-04-25 11:55:33 +02:00
| `<mysite>/client` | More complex projects can alternatively contain frontend assets in a common `client` folder |
2017-06-22 12:50:45 +02:00
| `<mysite>/themes/<yourtheme>` | Custom nested themes (note: theme structure is described below) |
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
Example Forum Documentation:
2016-04-25 11:55:33 +02:00
| Directory | Description |
| --------- | ----------- |
2017-10-02 13:30:24 +02:00
| `blog/docs` | |
| `blog/docs/_manifest_exclude` | Empty file to signify that SilverStripe does not need to load classes from this folder |
| `blog/docs/en/` | English documentation |
| `blog/docs/en/index.md` | Documentation homepage. Should provide an introduction and links to remaining docs |
| `blog/docs/en/Getting_Started.md` | Documentation page. Naming convention is Uppercase and underscores. |
| `blog/docs/en/_images/` | Folder to store any images or media |
| `blog/docs/en/Some_Topic/` | You can organise documentation into nested folders. Naming convention is Uppercase and underscores. |
| `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 )