diff --git a/docs/book/v1/introduction/file-structure.md b/docs/book/v1/introduction/file-structure.md index da93f6f..acf1c6b 100644 --- a/docs/book/v1/introduction/file-structure.md +++ b/docs/book/v1/introduction/file-structure.md @@ -8,102 +8,86 @@ When using Dotkernel Light, the following structure is installed by default: ![Dotkernel Light File Structure!](https://docs.dotkernel.org/img/light/file-structure-dk-light.png) -## Main directories +## Special purpose folders -* `bin` - various helper scripts -* `config` - various configuration files -* `data` - should contain project-related data -* `log` - storage of log files generated by dot-error-log library -* `public` - publicly visible files. The webserver need to have this folder as www-document root folder. -* `src` - should contain the source code files -* `test` - should contain the test files +* `.github` - containes workflow files +* `.laminas-ci` - contains laminas-ci workflow files -### `bin` directory +## `bin` folder -This directory contains one file, `clear-config-cache.php` which removes the config cache file (`data/cache/config-cache.php` - available only when development mode is enabled). +This folder contents are -### `config` directory +* `clear-config-cache.php` - Removes the config cache file `data/cache/config-cache.php`; available only when development mode is enabled -This directory contains all application-related config files: +## `config` folder -* `config.php`: here you will register ConfigProviders after installing packages -* `container.php`: main service container, providing access to all registered services -* `development.config.php.dist`: gets symlinked as `development.config.php` when enabling development mode - activates debug mode -* `pipeline.php`: contains a list of middlewares, in their order of execution -* `twig-cs-fixer.php`: configuration file for Twig code style checker/fixer +This folder contains all application-related config files: -#### `autoload` directory +* `config.php` - Registers ConfigProviders for installing packages +* `container.php` - Main service container that provides access to all registered services +* `development.config.php.dist` - Activates debug mode; gets symlinked as `development.config.php` when enabling development mode +* `pipeline.php` - Contains a list of middlewares, in the order of their execution +* `twig-cs-fixer.php` - Configuration file for Twig code style checker/fixer -This directory contains all service-related local and global config files: +### `config/autoload` folder -* `app.global.php`: sets the application name -* `dependencies.global.php`: config file to set global dependencies that should be accessible by all modules -* `development.local.php.dist`: gets symlinked as `development.local.php` when enabling development mode - activates error handlers -* `error-handling.global.php`: configures and activates error logs -* `local.php.dist`: local config file where you can overwrite application name and URL -* `mezzio.global.php`: Mezzio core config file -* `templates.global.php`: dotkernel/dot-twigrenderer config file +This folder contains all service-related local and global config files: -### `data` directory +* `app.global.php` - Configures basic app variables +* `dependencies.global.php` - Config file to set global dependencies that should be accessible by all modules +* `development.local.php.dist` - Gets symlinked as `development.local.php` when enabling development mode; activates error handlers +* `error-handling.global.php` - Configures and activates error logs +* `local.php.dist` - Local config file where you can overwrite application name and URL +* `mezzio.global.php` - Mezzio core config file +* `templates.global.php` - dotkernel/dot-twigrenderer config file -This directory is a storage for project data files and service caches. -Inside you will find: +## `data/cache` folder -* `cache`: Twig's cache directory +This folder is a storage for service caches. -> AVOID storing sensitive data on VCS. +## `log` folder -### `log` directory - -This directory stores daily log files. +This folder stores daily log files. When you access the application from the browser, (if not already created) a new log file gets created in the format specified in the `config/autoload/error-handling.global.php` config file under the `stream` array key. -### `public` directory - -This directory contains all publicly available assets and serves as the entry point of the application: - -* `css`: contains `app.css`, a single file containing the entire CSS code collected from all modules, in a minified form -* `fonts`: contains `app`, a directory containing custom font files collected from all modules -* `images`: contains `app`, a directory containing all image files collected from all modules -* `js`: contains `app.js`, a single file containing the entire JavaScript code collected from all modules, in a minified form -* `.htacess`: server configuration file used by Apache web server - this file enables the URL rewrite functionality -* `index.php`: the application's main entry point -* `robots.txt.dist`: a sample robots.txt file, providing settings allow/deny bot access to certain areas of your application - activate it by duplicating the file as `robots.txt` and comment out the lines that don't match your environment +## `public` folder -### `src` directory +This folder contains all publicly available assets and serves as the entry point of the application: -This directory contains two directories, called modules: +* `css` and `js` - Contains the css and js file(s) generated by the webpack (npm) from the assets folder +* `fonts` and `images` - Contain the font and image file(s) copied by the webpack (npm) from the assets folder +* `uploads` - a folder that normally contains admin avatar images +* `.htaccess` - server configuration file used by Apache web server; it enables the URL rewrite functionality +* `index.php` - the application's main entry point +* `robots.txt.dist` - a sample robots.txt file that allows/denies bot access to certain areas of your application; activate it by duplicating the file as `robots.txt` and comment out the lines that don't match your environment -* `App` -* `Page` +## `src` directory -#### `App` directory +This folder contains a separate folder for each Module. -This is the `App` module. -It contains all generic functionalities your application depends on. +These are the modules included by default: -The `assets` directory contains all generic assets, reusable across the application. +* `App` - Core functionality, from authentication, to rendering, to error reporting +* `Page` - Contains functionality for displaying a page -The `src` contains `ConfigProvider.php`, a file that sets template path aliases (`getTemplates`) but can also provide dependencies (`getDependencies`). +### Module contents -The `templates`: contains misc components like the home page, custom error pages, template partials and the default layout template. +Each Module folder, in turn, should contain the following folders, unless they are empty: -#### `Page` directory +* `src/Controller` - Action classes +* `src/Service` - Service classes -This is the `Page` module. -It contains page-related components for your application. +The above example is just some of the folders a project may include, but they should give you an idea about the recommended structure. +Other classes the `src` folder may include are `InputFilter`, `EventListener`, `Helper`, `Command`, `Factory` etc. -The `src` directory contains the following items: +The `src` folder in each Module folder normally also contains these files: -* `Controller`: contains module controllers -* `Factory`: contains module factories, which are used to provide ready-to-use instances of certain classes -* `Service`: contains module service files, which contain classes that provide custom functionalities -* `ConfigProvider.php` - provides module configuration data -* `RoutesDelegator.php` - stored main routes found in the module +* `ConfigProvider.php` - Configuration data for the module +* `RoutesDelegator.php` - Module specific route registrations -The `templates` directory contains the `page` directory, with template files for various web pages. +### `templates` directory for modules -## Special purpose directories +This directory contains the template files. -* `.github` - contains workflow files -* `.laminas-ci` - contains Laminas Continuous Integration (CI) workflow files +> `twig` is used as Templating Engine. +> All template files have the extension `.html.twig`.