# File structure

## Summary

This page describes the default folder and file layout of Dotkernel Admin, including the purpose of `bin`, `config`, `data`, `log`, `public` and `src`, along with the Core module's submodule structure.

## Details

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/v7/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
* `pipeline.php` - Contains a list of middlewares, in the order of their execution
* `routes.php` - Registers the application's routes
* `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:

* `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
* `geoip.global.php` - Configures the GeoLite2 synchronizer command
* `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` - controls bot access to certain areas of your application; ships ready to use, edit 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.

## FAQ

**Q: What standard does Dotkernel Admin's file structure follow?**

A: It follows the [PSR-4](https://www.php-fig.org/psr/psr-4/) standard.

**Q: Where do application configuration files live?**

A: In the `config` folder, with service-related local and global config files under `config/autoload`.

**Q: What does each Module folder typically contain?**

A: Folders such as `src/Handler`, `src/InputFilter` and `src/Service`, plus a `ConfigProvider.php` and a `RoutesDelegator.php`.

**Q: What is the Core module used for?**

A: It is a common codebase shared across the applications in your project, containing submodules such as `Admin`, `App`, `Security`, `Setting` and `User`, each typically with `src/Entity`, `src/Repository` and a `ConfigProvider.php`.