Project Structure
Derafu Foundation provides a standardized directory structure for your projects. This document explains the purpose of each directory and key files.
Root Directories
.github/
Contains GitHub-specific configurations:
workflows/ci.yml
: Continuous Integration workflow that runs tests and code quality checks.workflows/cd.yml
: Continuous Deployment workflow for automatically deploying. By default, it is configured to deploy to GitHub Pages. Deployment is disabled by default, just remove thefalse &&
in the file to enable it.
app/
Application bootstrap files:
bootstrap.php
: The main bootstrap file that initializes the application runtime.
assets/
Frontend assets organized by type:
css/
: CSS stylesheets.js/
: JavaScript files.img/
: Images and other media files.
config/
Configuration files:
routes.yaml
: Route definitions for your application.services.yaml
: Service container configuration (dependency injection).
public/
Web server document root:
index.php
: Application entry point with Front Controller.static/
: Compiled assets (generated by the build process).
Note: If your application doesn’t need a Front Controller, by default, it’s used only for documentation.
src/
Application source code. Organize your PHP classes here according to their namespace. By convention, but not enforced out of Derafu ORG, use:
Abstract/
: Abstract classes, withAbstract
prefix.Contract/
: Interfaces for your application, withInterface
suffix.Controller/
: Controller classes, withController
suffix.Service/
: Service classes.
templates/
Template files for rendering HTML:
components/
: Reusable template components (header, footer, etc.).layouts/
: Layout templates that define page structure.pages/
: Page-specific templates.base.html.twig
: Base template that defines the HTML structure for all layouts.error.html.twig
: Error page template.html.html.twig
: HTML wrapper template, used when rendering a markdown o php template.
tests/
Test files:
fixtures/
: Test fixtures and sample data.src/
: Tests for your source code. You can organize your tests by tests suits, mirroring the structure of thesrc/
directory, by features or any other criteria (but not enforced out of Derafu ORG).
var/
Temporary files and caches:
cache/
: Cache files.logs/
: Log files.tmp/
: Temporary files.
Key Files
Configuration Files
.gitignore
: Specifies files that Git should ignore.LICENSE
: MIT license file by default.package.json
: NPM configuration for frontend assets.php-cs-fixer.php
: PHP CS Fixer configuration.phpstan.neon
: PHPStan configuration.phpunit.xml
: PHPUnit configuration.vite.config.js
: Vite build configuration.
Application Files
public/index.php
: Main entry point that bootstraps the application.app/bootstrap.php
: Initializes the runtime environment.
File Copying Mechanism
The Installer
class in Installer.php
is responsible for copying foundation files to new projects during Composer installation. This class:
- Defines a list of files to copy in the
FILES
constant. - Copies each file from the foundation package to the project directory.
- Creates necessary directories if they don’t exist.
- Handles file overwrite rules (some files are configured to be overwritten in updates, others not).
Files marked with true
in the FILES
constant will be overwritten if they already exist:
private const FILES = [
// Files that will not be overwritten if they exist.
'.github/workflows/cd.yml',
'.github/workflows/ci.yml',
// Files that will be overwritten even if they exist.
'app/bootstrap.php' => true,
// ...
];
Note: The idea behind overwriting files is to make it easier to update the foundation. But, you can disable it by removing the Derafu\\Foundation\\Installer::copyFiles
from the post-install-cmd
and post-update-cmd
scripts in your composer.json
file.
Extending the Structure
When creating a new project based on this foundation, you should:
- Keep the existing directory structure.
- Add your own directories as needed.
- Follow PSR-4 autoloading standards for your PHP classes.
- Place tests in the corresponding structure within the
tests/
directory.
The structure is designed to be flexible while providing a consistent organization pattern across projects.