xamxam/DIRECTORY_STRUCTURE.md

Recommended Directory Structure

Based on the Standard PHP Package Skeleton (researched by Paul M. Jones from thousands of GitHub projects).

Directory Layout

posterg-website/
├── public/                 # DocumentRoot - publicly accessible files
│   ├── index.php          # Front controller
│   ├── assets/            # Public assets (CSS, JS, images)
│   │   ├── css/
│   │   ├── js/
│   │   └── images/
│   └── .htaccess          # Apache/nginx rules
│
├── src/                   # Application source code (private)
│   ├── Controller/        # Controllers
│   ├── Model/             # Models
│   ├── View/              # Views/templates
│   ├── Service/           # Business logic services
│   ├── Repository/        # Data access layer
│   └── Middleware/        # Middleware components
│
├── config/                # Configuration files (private)
│   ├── app.php
│   ├── database.php
│   ├── routes.php
│   └── .env.example       # Environment variables template
│
├── database/              # Database-related files
│   ├── migrations/        # Database migrations
│   ├── seeds/             # Database seeders
│   └── schema.sql         # Database schema
│
├── tests/                 # Unit and integration tests
│   ├── Unit/
│   ├── Integration/
│   └── bootstrap.php
│
├── vendor/                # Third-party dependencies (Composer)
│   └── autoload.php
│
├── bin/                   # Executable scripts
│   └── console            # CLI commands
│
├── var/                   # Variable/temporary files (private)
│   ├── cache/            # Application cache
│   ├── logs/             # Log files
│   └── tmp/              # Temporary files
│
├── docs/                  # Documentation
│   └── *.md
│
├── scripts/               # Build/deployment scripts
│   └── deploy.sh
│
├── resources/             # Non-PHP resources (private)
│   ├── views/            # Template files
│   ├── lang/             # Translations
│   └── emails/           # Email templates
│
├── lib/                   # Internal libraries (if not using src/)
│
├── .git/                  # Git repository
├── .gitignore
├── composer.json          # Composer dependencies
├── composer.lock
├── phpunit.xml            # PHPUnit configuration
├── README.md              # Project documentation
└── LICENSE                # License file

Directory Purposes

public/ (PUBLIC - DocumentRoot points here)

• Only directory accessible via web browser
• Contains: front controller (index.php), assets (CSS/JS/images)
• Web server DocumentRoot should point to this directory
• Security: No sensitive files here

src/ (PRIVATE)

• Application source code
• All classes following PSR-4 autoloading
• Organized by responsibility (Controller, Model, Service, etc.)
• Not accessible from the web

config/ (PRIVATE)

• Configuration files
• Database credentials, API keys, app settings
• .env file for environment-specific configuration
• Never committed sensitive values (use .env.example)

database/ (PRIVATE)

• Database migrations, seeds, schema definitions
• Version-controlled database structure

tests/ (PRIVATE)

• PHPUnit tests
• Organized by test type (Unit, Integration, Functional)
• Mirror the src/ structure

vendor/ (PRIVATE)

• Composer dependencies
• Auto-generated, excluded from version control
• Contains autoload.php for autoloading

bin/ (PRIVATE)

• Executable scripts and CLI commands
• Make scripts executable: chmod +x bin/*

var/ (PRIVATE)

• Runtime-generated files
• cache/, logs/, tmp/
• Typically .gitignored (except .gitkeep files)
• Needs write permissions

docs/ (PRIVATE)

• Project documentation
• API docs, guides, architecture decisions

scripts/ (PRIVATE)

• Build, deployment, maintenance scripts
• Not part of the application runtime

resources/ (PRIVATE)

• Non-PHP application resources
• Templates, translations, email layouts

Migration from Current Structure

Your current structure → Recommended structure:

Current              →  Recommended
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
index.php            →  public/index.php
memoire.php          →  public/memoire.php OR src/Controller/
search.php           →  public/search.php OR src/Controller/
assets/              →  public/assets/
inc/                 →  src/ OR config/
admin/               →  src/Admin/ OR public/admin/
database/            →  database/ (keep as-is)
tests/               →  tests/ (keep as-is)
vendor/              →  vendor/ (keep as-is)
lib/                 →  lib/ OR src/
docs/                →  docs/ (keep as-is)
scripts/             →  scripts/ (keep as-is)
nginx/               →  scripts/nginx/ OR config/nginx/

Security Best Practices

1. DocumentRoot = public/

   • Configure web server to serve only from public/
   • All other directories are above DocumentRoot

2. Sensitive Files

   • Keep .env, config files outside public/
   • Never commit passwords, API keys
   • Use .env.example for templates

3. Permissions

   # Private directories (not writable by web server)
   chmod 755 src/ config/ database/ tests/
   
   # Writable by web server
   chmod 775 var/cache/ var/logs/ var/tmp/
   

4. .gitignore

   /vendor/
   /var/cache/*
   /var/logs/*
   /var/tmp/*
   /.env
   composer.lock
   

Web Server Configuration

Nginx

server {
    root /path/to/posterg-website/public;
    index index.php;
    
    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }
    
    location ~ \.php$ {
        fastcgi_pass unix:/var/run/php/php-fpm.sock;
        fastcgi_index index.php;
        include fastcgi_params;
    }
}

Apache (.htaccess in public/)

<IfModule mod_rewrite.c>
    RewriteEngine On
    RewriteCond %{REQUEST_FILENAME} !-f
    RewriteCond %{REQUEST_FILENAME} !-d
    RewriteRule ^ index.php [L]
</IfModule>

Composer Configuration

Update composer.json to use PSR-4 autoloading:

{
    "autoload": {
        "psr-4": {
            "App\\": "src/"
        }
    },
    "autoload-dev": {
        "psr-4": {
            "Tests\\": "tests/"
        }
    }
}

Next Steps

1. Create public/ directory
2. Move web-accessible files to public/
3. Organize classes into src/ with namespaces
4. Move configuration to config/
5. Update web server DocumentRoot
6. Update paths in application code
7. Run composer dump-autoload
8. Test the application

References

• Standard PHP Package Skeleton
• PSR-4 Autoloading
• Composer Documentation