File structure

Summary

This page describes the folders and files installed with Dotkernel Frontend, from bin, config, data, log and public to the modules in src. It also describes what each module folder is expected to contain.

Details

Dotkernel Frontend follows the PSR-4 standards.

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

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

Special purpose folders

• .github - Contains workflow files
• .laminas-ci - Contains pre-run.sh, which prepares the laminas-ci environment (installs sqlite3, copies the local config files) before the PHPUnit jobs

bin folder

This folder contents are

• clear-config-cache.php - Removes the config cache file data/cache/config-cache.php; also available as composer clear-config-cache
• composer-post-install-script.php - Runs after composer install/composer update and copies local.php.dist, local.test.php.dist (development only) and dot-mail's mail.global.php.dist into config/autoload when they are missing
• doctrine - Used by the doctrine fixtures to populate the database tables
• doctrine-migrations - Used to create the database tables

config folder

This folder contains all application-related config files:

• cli-config.php - Command line interface configuration used by Doctrine Migrations
• 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
• routes.php - Application-level route registration; empty by default, as each module registers its own routes in its RoutesDelegator
• 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 User identity
• authorization.global.php - Configures permissions for user roles
• authorization-guards.global.php - Configures access per route for user roles
• 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.global.php - Mail configuration defaults (sendmail vs esmtp, message options, SMTP options); not shipped in the repository, it is copied from vendor/dotkernel/dot-mail/config/mail.global.php.dist by bin/composer-post-install-script.php; it is not ignored by git, so keep SMTP credentials in a mail.local.php instead
• mezzio.global.php - Mezzio core config file
• navigation.global.php - dotkernel/dot-navigation menu containers (left_menu, guest_menu, user_menu, user_profile_menu)
• response-header.global.php - Defines headers per route
• 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 - Created at runtime and ignored by git; holds the config cache, the Doctrine cache and compiled Twig templates
• doctrine - Database migrations and fixtures

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 - contains user avatar images, stored under uploads/user/{userUuid}/
• .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 directory

This folder contains a separate folder for each Module.

These are the modules included by default:

• App - Core functionality, from authentication, to rendering, to error reporting
• Contact - Contains functionality for the contact us form
• Page - Contains functionality for displaying a page
• Plugin - Contains plugin functionality for dynamic forms and templates
• User - Contains functionality for users, from login and registering, to account management

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 folders the src folder may include are Form, Fieldset, InputFilter, EventListener, Factory, Middleware, Enum, DBAL etc.

The App module also contains an assets folder (fonts, images, js, scss), which webpack compiles into public.

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 directory for modules

This directory contains the template files.

twig is used as Templating Engine. All template files have the extension .html.twig.

FAQ

Q: Where do I register a new route?

A: In the module's RoutesDelegator.php. config/routes.php is empty by default, because each module registers its own routes.

Q: Where should I put passwords and other local settings?

A: In config/autoload/local.php or another config/autoload/*.local.php file. config/autoload/.gitignore ignores local.php and *.local.php, so they are never committed.

Q: Where are uploaded avatars stored?

A: In public/uploads/user/{userUuid}/, as set by the uploads key in config/autoload/local.php.

Q: Where do I edit the CSS and JavaScript?

A: In src/App/assets. Webpack compiles them into public/css and public/js when you run npm run watch or npm run prod.

Q: How do I add a new module?

A: Create src/<Module>/src with a ConfigProvider.php (and a RoutesDelegator.php if it has routes). Add a Frontend\\<Module>\\ PSR-4 entry to composer.json, register the ConfigProvider in config/config.php, and run composer dump-autoload.