diff --git a/docs/en/00_Getting_Started/00_Server_Requirements.md b/docs/en/00_Getting_Started/00_Server_Requirements.md index c11d302b6..85b72b64f 100644 --- a/docs/en/00_Getting_Started/00_Server_Requirements.md +++ b/docs/en/00_Getting_Started/00_Server_Requirements.md @@ -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: diff --git a/docs/en/00_Getting_Started/01_Installation/04_Other_installation_Options/Mac_OSX_Homebrew.md b/docs/en/00_Getting_Started/01_Installation/04_Other_installation_Options/Mac_OSX_Homebrew.md index 0d6542708..c25f60cd3 100644 --- a/docs/en/00_Getting_Started/01_Installation/04_Other_installation_Options/Mac_OSX_Homebrew.md +++ b/docs/en/00_Getting_Started/01_Installation/04_Other_installation_Options/Mac_OSX_Homebrew.md @@ -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`). diff --git a/docs/en/00_Getting_Started/04_Directory_Structure.md b/docs/en/00_Getting_Started/04_Directory_Structure.md index 8375cd4c1..f53f85fa8 100644 --- a/docs/en/00_Getting_Started/04_Directory_Structure.md +++ b/docs/en/00_Getting_Started/04_Directory_Structure.md @@ -18,25 +18,30 @@ Directory | Description We're using `` 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 | + | --------- | ----------- | | `/` | This directory contains all of your code that defines your website. | | `/_config` | YAML configuration specific to your application | - | `/code` | PHP code for model and controller (subdirectories are optional) | - | `/templates` | HTML [templates](/developer_guides/templates) with *.ss-extension | + | `/src` | PHP code for model and controller (subdirectories are optional) | + | `/tests` | PHP Unit tests | + | `/templates` | HTML [templates](/developer_guides/templates) with *.ss-extension for the `$default` theme | | `/css ` | CSS files | | `/images ` | Images used in the HTML templates | - | `/javascript` | Javascript and other script files | + | `/javascript` | Javascript and other script files | | `/client` | More complex projects can alternatively contain frontend assets in a common `client` folder | + | `/themes/` | 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//` | Custom theme base directory | + | `themes//templates` | Theme templates | + | `themes//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.| diff --git a/docs/en/02_Developer_Guides/16_Execution_Pipeline/03_App_Object_and_Kernel.md b/docs/en/02_Developer_Guides/16_Execution_Pipeline/03_App_Object_and_Kernel.md new file mode 100644 index 000000000..8db4ba7b7 --- /dev/null +++ b/docs/en/02_Developer_Guides/16_Execution_Pipeline/03_App_Object_and_Kernel.md @@ -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 + 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. + + ::: + + # ... + RewriteCond %{REQUEST_URI} ^(.*)$ + RewriteCond %{REQUEST_FILENAME} !-f + RewriteRule .* mysite/main.php?url=%1 [QSA] + # ... + + + +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 + + # ... + # Non existant files passed to requesthandler + RewriteCond %{REQUEST_URI} ^(.*)$ + RewriteCond %{REQUEST_FILENAME} !-f + RewriteRule .* ../mysite/main.php?url=%1 [QSA] + + +## 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); + + + diff --git a/docs/en/02_Developer_Guides/16_Execution_Pipeline/index.md b/docs/en/02_Developer_Guides/16_Execution_Pipeline/index.md index 7e91aa99b..32f9937e7 100644 --- a/docs/en/02_Developer_Guides/16_Execution_Pipeline/index.md +++ b/docs/en/02_Developer_Guides/16_Execution_Pipeline/index.md @@ -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. diff --git a/docs/en/04_Changelogs/4.0.0.md b/docs/en/04_Changelogs/4.0.0.md index bda5bd454..6983d9146 100644 --- a/docs/en/04_Changelogs/4.0.0.md +++ b/docs/en/04_Changelogs/4.0.0.md @@ -1463,6 +1463,7 @@ A very small number of methods were chosen for deprecation, and will be removed #### 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)