diff --git a/docs/book/v5/introduction/file-structure.md b/docs/book/v5/introduction/file-structure.md index 1d8be7c..77abcd3 100644 --- a/docs/book/v5/introduction/file-structure.md +++ b/docs/book/v5/introduction/file-structure.md @@ -8,54 +8,112 @@ When using Dotkernel Admin the following structure is installed by default: ![Dotkernel Admin File Structure!](https://docs.dotkernel.org/img/admin/file-structure-dk-admin.jpg) -## Main directories - -* `bin` - Executable files from CLI -* `config` - Various configuration files -* `data` - Should contain project-related data (AVOID storing sensitive data on VCS) -* `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 - ## Special purpose folders -* `.github` - Contains workflow files +* `.github` - Contains GitHub workflow files * `.laminas-ci` - Contains laminas-ci workflow files -## `src` directory +## `bin` folder -This directory contains all source code related to the Module. -It should contain the following directories, if they are not empty: +This folder contents are -* Handler - Action classes (similar to Controllers but can only perform one action) -* Entity - Database entities -* Service - Service classes -* Collection - Database entities collections -* Repository - Entity repository folder +* `clear-config-cache.php` - Removes the config cache file `data/cache/config-cache.php`; available only when development mode is enabled +* `cli.php` - Used to build console applications based on [laminas-cli](https://github.com/laminas/laminas-cli) +* `doctrine` - Used by the doctrine fixtures to populate the database tables -> The above example lists just a part of the directories in a project, but it should give you an idea of what the structure should look like. +## `config` folder -Other classes in the `src` directory may include `InputFilter`, `EventListener`, `Helper`, `Command`, `Factory` etc. +This folder contains all application-related config files: -The `src` directory should also contain 2 files: +* `cli-config.php` - Command line interface configuration used by migrations, fixtures, crons +* `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 +* `migrations.php` - Configuration for database migration, like migration file location and table to save the migration log +* `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 -* `ConfigProvider.php` - Provides configuration data -* `RoutesDelegator.php` - Module main routes entry file +### `config/autoload` folder -## `templates` directory for modules +This folder contains all service-related local and global config files: -This directory contains the template files, used for example to help render e-mail templates. +* `app.global.php` - Configures basic app variables +* `authentication.global.php` - Defines the Admin identity +* `authorization.global.php` - Configures permissions for user roles +* `authorization-guards.global.php` - Configures access per route for user roles +* `cli.global.php` - Configures cli +* `cors.global.php` - Configures Cross-Origin Resource Sharing, like call origin, headers, cookies +* `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 +* `doctrine.global.php` - Configuration used by Object–relational mapping +* `error-handling.global.php` - Configures and activates error logs +* `local.php.dist` - Local config file where you can overwrite application name and URL +* `local.test.php.dist` - Local configuration for functional tests +* `mail.local.php.dist` - Mail configuration; e.g. sendmail vs smtp, message configuration, mail logging +* `mezzio.global.php` - Mezzio core config file +* `navigation.global.php` - Configures the top menu +* `session.global.php` - Configures the session +* `templates.global.php` - dotkernel/dot-twigrenderer config file -> Dotkernel Admin uses `twig` as Templating Engine. -> All template files have the extension `.html.twig`. +## `data` folder + +This folder is a storage for project data files and service caches. +It contains these folders: + +* `cache` - Cache for e.g. Twig files +* `doctrine` - Database migrations and fixtures +* `geoip` - Holds the GeoLite2 databases +* `lock` - Contains lock files generated by [`dotkernel/dot-cli`](https://docs.dotkernel.org/dot-cli/v3/lock-files/) + +> AVOID storing sensitive data on the repository! + +## `log` folder + +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` folder + +This folder contains all publicly available assets and serves as the entry point of the application: + +* `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 -## `data` directory +## `src` folder -This directory contains project-related data, like cache and file uploads. +This folder contains a separate folder for each Module. -We recommend using the following directory structure: +These are the modules included by default: -* `data/cache` - Location where caches are stored -* `data/doctrine` - Fixtures and migrations -* `data/lock` - Lock files generated by [dotkernel/dot-cli](https://docs.dotkernel.org/dot-cli/v3/lock-files/) +* `Admin` - Contains functionality for managing users with `admin` role; note these are users save in the `admin` database table +* `App` - Contains core functionality, from authentication, to rendering, to error reporting +* `Setting` - Contains functionality for saving and reading display settings + +### Module contents + +Each Module folder, in turn, should contain the following folders, unless they are empty: + +* `src/Controller` - Action classes +* `src/Entity` - Used by database entities +* `src/Repository` - Entity repository folder +* `src/Service` - Service classes + +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` folder in each Module folder normally also contains these files: + +* `ConfigProvider.php` - Configuration data for the module +* `OpenAPI.php` - Detailed descriptions for each endpoint in the OpenAPI format +* `RoutesDelegator.php` - Module specific route registrations + +### `templates` folder for modules + +This folder contains the template files, used for example to help render e-mail templates. + +> `twig` is used as Templating Engine. +> All template files have the extension `.html.twig`.