Skip to content

file-structure.md

Latest commit

 

History

History
141 lines (97 loc) · 6.92 KB

file-structure.md

File metadata and controls

141 lines (97 loc) · 6.92 KB

File structure

Dotkernel Admin follows the 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!

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
  • 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

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.