# File structure

## Summary

A tour of the directories a default Dotkernel API installation ships with — `bin` for CLI entry points, `config` and `config/autoload` for application and service configuration, `data` for caches, migrations and OAuth keys, `log` for daily logs, `public` as the web entry point, and `src` for the modules — plus the folders and files each module is expected to contain.

## Details

The Dotkernel API file structure follows the [PSR-4](https://www.php-fig.org/psr/psr-4/) standards.
Standardizing the file structure of your project is considered good practice because it makes it easier to find and navigate the code.

When using Dotkernel API, the following structure is installed by default:

![Dotkernel API File Structure!](https://docs.dotkernel.org/img/api/v7/file-structure-dk-api.png)

## Special purpose folders

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

## `bin` folder

This folder contains:

* `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, cron jobs
* `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

### `config/autoload` folder

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

* `authorization.global.php` - Configures access per route for user roles
* `cli.global.php` - Configures cli
* `content-negotiation.global.php` - Configures request and response formats
* `cors.local.php.dist` - Configures Cross-Origin Resource Sharing, like call origin, headers, cookies
* `dependencies.global.php` - Sets 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 configuration 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
* `mezzio-tooling-factories.global.php`  Add or remove factory definitions
* `response-header.global.php` - Defines headers per route
* `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` - Cache for e.g. Twig files
* `doctrine` - Database migrations and fixtures
* `oauth` - Encryption, private and public keys needed for authentication
* `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:

* `uploads` - Normally contains files uploaded via the application
* `.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 functionality such as error reporting
* `Core` - Contains core functionality, from authentication, to rendering
* `Security` - Contains security-related functionality
* `User` - Contains functionality for managing regular users

### Module contents

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

* `src/Handler` - Action classes (similar to Controllers but can only perform one action)
* `src/Entity` - Used by database entities
* `src/Service` - Service classes
* `src/Repository` - Entity repository folder

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

## FAQ

**Q: Which standard does the structure follow?**

A: [PSR-4](https://www.php-fig.org/psr/psr-4/) autoloading, so a class's namespace maps directly onto its path.

**Q: Where does my own code go?**

A: In a new folder under `src`, alongside the default `Admin`, `App`, `Core`, `Security` and `User` modules.
See [Core and App](../extended-features/core-and-app.md).

**Q: Which files must every module have?**

A: `ConfigProvider.php` for its configuration, `RoutesDelegator.php` for its routes and `OpenAPI.php` for its endpoint documentation.

**Q: What folders does a module typically contain?**

A: `Handler`, `Entity`, `Service` and `Repository`, omitting any that would be empty.
Modules commonly also add `InputFilter`, `EventListener`, `Helper`, `Command` and `Factory`.

**Q: Which directories need to be writable?**

A: `data`, `log` and `public/uploads`.
See [Clone the project](../installation/getting-started.md).

**Q: What is the application's entry point?**

A: `public/index.php`.
Only the `public` folder is served directly; everything else is routed through it by the `.htaccess` rewrite rules.

**Q: Where is the middleware pipeline defined?**

A: `config/pipeline.php`, which lists the middlewares in execution order.
See [Middleware flow](../flow/middleware-flow.md).

**Q: What is the difference between `config` and `config/autoload`?**

A: `config` holds application-level wiring — the container, the pipeline, the config aggregator.
`config/autoload` holds per-service configuration, split into `*.global.php` files that are committed and `*.local.php` files that are not.

**Q: Where are the OAuth2 keys kept?**

A: In `data/oauth`.
They are generated during installation and must never be committed.
See [OAuth2 security](../security/oauth2-security.md).

**Q: Why is `robots.txt` shipped as `robots.txt.dist`?**

A: So you can activate it deliberately: copy it to `robots.txt` and comment out the lines that do not match your environment.