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**
   ```bash
   # 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
```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/)
```apache
<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:

```json
{
    "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](https://github.com/php-pds/skeleton)
- [PSR-4 Autoloading](https://www.php-fig.org/psr/psr-4/)
- [Composer Documentation](https://getcomposer.org/doc/)