mirror of
https://github.com/silverstripe/silverstripe-framework
synced 2024-10-22 14:05:37 +02:00
Update developer documentation
This commit is contained in:
Damian Mooyman
parent
5c90d53a84
commit
6279d28e5e
@ -24,12 +24,13 @@ Our web-based [PHP installer](installation/) can check if you meet the requireme
|
||||
* `/dev/urandom`
|
||||
* [`mcrypt_create_iv()`](http://php.net/manual/en/function.mcrypt-create-iv.php)
|
||||
* CAPICOM Utilities (`CAPICOM.Utilities.1`, Windows only)
|
||||
* Required modules: dom, gd2, fileinfo, hash, iconv, mbstring, mysqli (or other database driver), session, simplexml, tokenizer, xml.
|
||||
* Required modules: ctype, dom, fileinfo, hash, intl, mbstring, session, simplexml, tokenizer, xml.
|
||||
* At least one from each group of extensions:
|
||||
* Image library extension (gd2, imagick)
|
||||
* DB connector library (pdo, mysqli, pgsql)
|
||||
* Recommended configuration
|
||||
|
||||
safe_mode = Off
|
||||
magic_quotes_gpc = Off
|
||||
memory_limit = 48M
|
||||
* Dev (local development for running test framework): memory_limit 512MB
|
||||
* Production: memory_limit = 64M
|
||||
|
||||
* See [phpinfo()](http://php.net/manual/en/function.phpinfo.php) for more information about your environment
|
||||
* One of the following databases:
|
||||
|
||||
@ -27,9 +27,9 @@ First we're telling Homebrew about some new repositories to get the PHP installa
|
||||
brew tap homebrew/dupes
|
||||
brew tap homebrew/php
|
||||
|
||||
We're installing PHP 5.5 here, with the required `mcrypt` module:
|
||||
We're installing PHP 5.6 here, with the required `mcrypt` module:
|
||||
|
||||
brew install php55 php55-mcrypt
|
||||
brew install php56 php56-mcrypt php56-intl php56-apcu
|
||||
|
||||
There's a [Homebrew Troubleshooting](https://github.com/Homebrew/homebrew/blob/master/share/doc/homebrew/Troubleshooting.md) guide if Homebrew doesn't work out as expected (run `brew update` and `brew doctor`).
|
||||
|
||||
|
||||
@ -18,25 +18,30 @@ Directory | Description
|
||||
We're using `<mysite>` as an example - arbitrary directory-names are allowed, as long as they don't collide with
|
||||
existing modules or the directories lists in "Core Structure".
|
||||
|
||||
| Directory | Description |
|
||||
| --------- | ----------- |
|
||||
| Directory | Description |
|
||||
| --------- | ----------- |
|
||||
| `<mysite>/` | This directory contains all of your code that defines your website. |
|
||||
| `<mysite>/_config` | YAML configuration specific to your application |
|
||||
| `<mysite>/code` | PHP code for model and controller (subdirectories are optional) |
|
||||
| `<mysite>/templates` | HTML [templates](/developer_guides/templates) with *.ss-extension |
|
||||
| `<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 |
|
||||
| `<mysite>/css ` | CSS files |
|
||||
| `<mysite>/images ` | Images used in the HTML templates |
|
||||
| `<mysite>/javascript` | Javascript and other script files |
|
||||
| `<mysite>/javascript` | Javascript and other script files |
|
||||
| `<mysite>/client` | More complex projects can alternatively contain frontend assets in a common `client` folder |
|
||||
| `<mysite>/themes/<yourtheme>` | Custom nested themes (note: theme structure is described below) |
|
||||
|
||||
Check our [JavaScript Coding Conventions](javascript_coding_conventions) for more details
|
||||
on folder and file naming in SilverStripe core modules.
|
||||
|
||||
## Themes Structure
|
||||
|
||||
| `themes/simple/` | Standard "simple" theme |
|
||||
| ------------------ | --------------------------- |
|
||||
| `themes/yourtheme/` | The themes folder can contain more than one theme - here's your own |
|
||||
| Directory | Description |
|
||||
| ------------------ | --------------------------- |
|
||||
| `themes/simple/` | Standard "simple" theme |
|
||||
| `themes/<yourtheme>/` | Custom theme base directory |
|
||||
| `themes/<yourtheme>/templates` | Theme templates |
|
||||
| `themes/<yourtheme>/css` | Theme CSS files |
|
||||
|
||||
|
||||
See [themes](/developer_guides/templates/themes)
|
||||
@ -77,7 +82,7 @@ Example Forum Documentation:
|
||||
| `forum/docs/en/` | English documentation |
|
||||
| `forum/docs/en/index.md` | Documentation homepage. Should provide an introduction and links to remaining docs |
|
||||
| `forum/docs/en/Getting_Started.md` | Documentation page. Naming convention is Uppercase and underscores. |
|
||||
| `forum/docs/en//_images/` | Folder to store any images or media |
|
||||
| `forum/docs/en/_images/` | Folder to store any images or media |
|
||||
| `forum/docs/en/Some_Topic/` | You can organise documentation into nested folders. Naming convention is Uppercase and underscores. |
|
||||
|`forum/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.|
|
||||
|
||||
|
||||
@ -0,0 +1,143 @@
|
||||
title: App Object and Kernel
|
||||
summary: Provides bootstrapping and entrypoint to the SilverStripe application
|
||||
|
||||
# Kernel
|
||||
|
||||
The [api:Kernel] object provides a container for the various manifests, services, and components
|
||||
which a SilverStripe application must have available in order for requests to be executed.
|
||||
|
||||
This can be accessed in user code via Injector
|
||||
|
||||
:::php
|
||||
$kernel = Injector::inst()->get(Kernel::class);
|
||||
echo "Current environment: " . $kernel->getEnvironment();
|
||||
|
||||
## Kernel services
|
||||
|
||||
Services accessible from this kernel include:
|
||||
|
||||
* getContainer() -> Current [api:Injector] service
|
||||
* getThemeResourceLoader() -> [api:ThemeResourceLoader] Service for loading of discovered templates.
|
||||
Also used to contain nested theme sets such as the `$default` set for all root module /templates folders.
|
||||
* getEnvironment() -> String value for the current environment. One of 'dev', 'live' or 'test'
|
||||
|
||||
Several meta-services are also available from Kernel (which are themselves containers for
|
||||
other core services) but are not commonly accessed directly:
|
||||
|
||||
* getClassLoader() -> [api:ClassLoader] service which handles the class manifest
|
||||
* getModuleLoader() -> [api:ModuleLoadel] service which handles module registration
|
||||
* getConfigLoader() -> [api:ConfigLoader] Service which assists with nesting of [api:Config] instances
|
||||
* getInjectorLoader() -> [api:InjectorLoader] Service which assists with nesting of [api:Injector] instances
|
||||
|
||||
## Kernel nesting
|
||||
|
||||
As with Config and Injector the Kernel can be nested to safely modify global application state,
|
||||
and subsequently restore state. Unlike those classes, however, there is no `::unnest()`. Instead
|
||||
you should call `->activate()` on the kernel instance you would like to unnest to.
|
||||
|
||||
:::php
|
||||
$oldKernel = Injector::inst()->get(Kernel::class);
|
||||
try {
|
||||
// Injector::inst() / Config::inst() are automatically updated to the new kernel
|
||||
$newKernel = $oldKernel->nest();
|
||||
Config::modify()->set(Director::class, 'alternate_base_url', '/myurl');
|
||||
}
|
||||
finally {
|
||||
// Any changes to config (or other application state) have now been reverted
|
||||
$oldKernel->activate();
|
||||
}
|
||||
|
||||
|
||||
# Application
|
||||
|
||||
An application represents a basic excution controller for the top level application entry point.
|
||||
The role of the application is to:
|
||||
|
||||
- Control bootstrapping of a provided kernel instance
|
||||
- Handle errors raised from an application
|
||||
- Direct requests to the request handler, and return a valid response
|
||||
|
||||
## HTTPApplication
|
||||
|
||||
The HTTPApplication provides a specialised application implementation for handling HTTP Requests.
|
||||
This class provides basic support for HTTP Middleware, such as [api:ErrorControlChainMiddleware].
|
||||
|
||||
`main.php` contains the default application implementation.
|
||||
|
||||
:::php
|
||||
<?php
|
||||
|
||||
use SilverStripe\Control\HTTPApplication;
|
||||
use SilverStripe\Control\HTTPRequestBuilder;
|
||||
use SilverStripe\Core\CoreKernel;
|
||||
use SilverStripe\Core\Startup\ErrorControlChainMiddleware;
|
||||
|
||||
require __DIR__ . '/src/includes/autoload.php';
|
||||
|
||||
// Build request and detect flush
|
||||
$request = HTTPRequestBuilder::createFromEnvironment();
|
||||
|
||||
// Default application
|
||||
$kernel = new CoreKernel(BASE_PATH);
|
||||
$app = new HTTPApplication($kernel);
|
||||
$app->addMiddleware(new ErrorControlChainMiddleware($app));
|
||||
$response = $app->handle($request);
|
||||
$response->output();
|
||||
|
||||
|
||||
Users can customise their own application by coping the above to a file in `mysite/main.php`, and
|
||||
updating their `.htaccess` to point to the new file.
|
||||
|
||||
:::
|
||||
<IfModule mod_rewrite.c>
|
||||
# ...
|
||||
RewriteCond %{REQUEST_URI} ^(.*)$
|
||||
RewriteCond %{REQUEST_FILENAME} !-f
|
||||
RewriteRule .* mysite/main.php?url=%1 [QSA]
|
||||
# ...
|
||||
</IfModule>
|
||||
|
||||
|
||||
Note: This config must also be duplicated in the below template which provide asset routing:
|
||||
|
||||
`silverstripe-assets/templates/SilverStripe/Assets/Flysystem/PublicAssetAdapter_HTAccess.ss`:
|
||||
|
||||
:::ss
|
||||
<IfModule mod_rewrite.c>
|
||||
# ...
|
||||
# Non existant files passed to requesthandler
|
||||
RewriteCond %{REQUEST_URI} ^(.*)$
|
||||
RewriteCond %{REQUEST_FILENAME} !-f
|
||||
RewriteRule .* ../mysite/main.php?url=%1 [QSA]
|
||||
</IfModule>
|
||||
|
||||
## Custom application actions
|
||||
|
||||
If it's necessary to boot a SilverStripe kernel and application, but not do any
|
||||
request processing, you can use the Application::execute() method to invoke a custom
|
||||
application entry point.
|
||||
|
||||
This may be necessary if using SilverStripe code within the context of a non-SilverStripe
|
||||
application.
|
||||
|
||||
For example, the below will setup a request, session, and current controller,
|
||||
but will leave the application in a "ready" state without performing any
|
||||
routing.
|
||||
|
||||
:::php
|
||||
$request = CLIRequestBuilder::createFromEnvironment();
|
||||
$kernel = new TestKernel(BASE_PATH);
|
||||
$app = new HTTPApplication($kernel);
|
||||
$app->execute($request, function (HTTPRequest $request) {
|
||||
// Start session and execute
|
||||
$request->getSession()->init();
|
||||
|
||||
// Set dummy controller
|
||||
$controller = Controller::create();
|
||||
$controller->setRequest($request);
|
||||
$controller->pushCurrent();
|
||||
$controller->doInit();
|
||||
}, true);
|
||||
|
||||
|
||||
|
||||
@ -78,21 +78,26 @@ can leave sensitive files exposed to public access (the `RewriteRule` conditions
|
||||
|
||||
## Bootstrap
|
||||
|
||||
All requests go through `framework/main.php`, which sets up the execution environment:
|
||||
The `constants.php` file is included automatically in any project which requires silverstripe/framework.
|
||||
This is included automatically when the composer `vendor/autoload.php` is included, and performs its
|
||||
tasks silently in the background.
|
||||
|
||||
* Tries to locate an `.env`
|
||||
* Tries to locate an `.env`
|
||||
[configuration file](/getting_started/environment_management) in the webroot.
|
||||
* Sets constants based on the filesystem structure (e.g. `BASE_URL`, `BASE_PATH` and `TEMP_FOLDER`)
|
||||
* Normalizes the `url` parameter in preparation for handing it off to `Director`
|
||||
* Connects to a database, based on information stored in the global `$databaseConfig` variable.
|
||||
The configuration is either defined in your `_config.php`, or through `.env`
|
||||
* Sets up [error handlers](../debugging/error_handling)
|
||||
* Optionally continues a [session](../cookies_and_sessions/sessions) if the request already contains a session identifier
|
||||
* Loads manifests for PHP classes, templates, as well as any [YAML configuration](../configuration).
|
||||
* Optionally regenerates these manifests (if a ["flush" query parameter](flushable) is set)
|
||||
* Executes all procedural configuration defined through `_config.php` in all discovered modules
|
||||
* Loads the Composer PHP class autoloader
|
||||
* Hands control over to [api:Director]
|
||||
* Sets constants based on the filesystem structure (e.g. `BASE_URL`, `BASE_PATH` and `TEMP_FOLDER`)
|
||||
|
||||
All requests go through `framework/main.php`, which sets up the core [api:Kernel] and [api:HTTPApplication]
|
||||
objects. See [/developer_guides/execution_pipeline/app_object_and_kernel] for details on this.
|
||||
The main process follows:
|
||||
|
||||
|
||||
* Include `autoload.php`
|
||||
* Construct [api:HTTPRequest] object from environment.
|
||||
* Construct a `Kernel` instance
|
||||
* Construct a `HTTPApplication` instance
|
||||
* Add any necessary middleware to this application
|
||||
* Pass the request to the application, and request a response
|
||||
|
||||
|
||||
While you usually don't need to modify the bootstrap on this level, some deeper customizations like
|
||||
adding your own manifests or a performance-optimized routing might require it.
|
||||
|
||||
@ -1463,6 +1463,7 @@ A very small number of methods were chosen for deprecation, and will be removed
|
||||
|
||||
#### <a name="overview-orm-api"></a>ORM API Additions / Changes
|
||||
|
||||
* Deprecated globals `$database` and `$databaseConfig`. Please use `DB::setConfig()` instead.
|
||||
* Deprecate `SQLQuery` in favour `SQLSelect`
|
||||
* `DataObject.many_many` 'through' relationships now support join dataobjects in place of
|
||||
automatically generated join tables. See the [/developer_guides/relations](datamodel relationship docs)
|
||||
|
||||
Loading…
Reference in New Issue
Block a user