Update developer documentation

This commit is contained in:
Damian Mooyman 2017-06-22 11:43:28 +12:00
parent 5c90d53a84
commit 6279d28e5e
No known key found for this signature in database
GPG Key ID: 78B823A10DE27D1A
6 changed files with 184 additions and 29 deletions

View File

@ -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:

View File

@ -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`).

View File

@ -22,21 +22,26 @@ existing modules or the directories lists in "Core Structure".
| --------- | ----------- |
| `<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>/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 |
| Directory | Description |
| ------------------ | --------------------------- |
| `themes/yourtheme/` | The themes folder can contain more than one theme - here's your own |
| `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.|

View File

@ -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);

View File

@ -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`
[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]
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.

View File

@ -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)