# File structure

Dotkernel Admin follows the [PSR-4](https://www.php-fig.org/psr/psr-4/) standards.

It is considered good practice to standardize the file structure of projects.

When using Dotkernel Admin the following structure is installed by default:

![Dotkernel Admin File Structure!](https://docs.dotkernel.org/img/admin/v6/file-structure-dk-admin.jpg
)

## Special purpose folders

* `.github` - Contains GitHub workflow files
* `.laminas-ci` - Contains laminas-ci workflow files

## `bin` folder

This folder contents are

* `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

## `config` folder

This folder contains all application-related config 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

### `config/autoload` folder

This folder contains all service-related local and global config files:

* `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
* `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.global.php` - 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

## `data` folder

This folder is a storage for project data files and service caches.
It contains these folders:

* `cache` - Twig and Doctrine cache files
* `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

## `src` folder

This folder contains a separate folder for each Module.

These are the modules included by default:

* `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
* `Core` – Contains the shared logic and base infrastructure used across multiple modules
* `Dashboard` – Contains the structure and rendering logic of the main admin dashboard, including layout, widgets, and default admin landing page
* `Page` - Contains reusable UI components and layout elements such as dropdowns, modal popups, error displays, and tooltips for the admin interface
* `Setting` - Contains functionality for saving and reading display settings
* `User` - Contains functionality for managing users; note these are users save in the `user` database table

### Module contents

Each Module folder, in turn, should contain the following folders, unless they are empty:

* `src/Handler` - Action classes
* `src/InputFilter` - Validation rules for inputs
* `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 `Adapter`, `Factory`, `Form`, `Delegator` etc.

The `src` folder in each Module folder normally also contains these files:

* `ConfigProvider.php` - Configuration data for the module
* `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`.

### Core module

The Core module is a common codebase set up to be used by the applications you added to your project.

These are the submodules included by default:

* `Admin` - Contains logic for the admin submodule features
* `App` - Contains shared application-level services and infrastructure utilities
* `Security` - Contains authentication, authorization, and related security mechanisms
* `Setting` - Contains configuration and application settings management
* `User` - Contains user entities, repositories, and services handling user data and logic

Each submodule folder should contain:

* `src/Entity` - Used by database entities
* `src/Repository` - Entity repository folder
* `ConfigProvider.php` - Configuration data for the module

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 `DBAL`, `Enum`, `Command`, `Factory` etc.