Developer Guide

This guide is intended for developers working with Securaine, a secure, extensible contact form application built for modern, production-level deployments.

📁 Project Structure


Securaine/
├── app/
│   ├── Controllers/      # HTTP and API logic
│   ├── Models/           # Data models
│   ├── Services/         # Reusable business logic and external integrations
│   ├── bootstrap.php     # Bootstrap and app initialization
│   └── config.php        # Centralized configuration
│
├── lang/                 # JSON language files
├── public/               # Public-facing assets (CSS, JS, images)
├── routes/               # Application routing
├── storage/              # Secure files, metadata, caching, and logs
├── vendor/               # Composer dependencies
├── views/
│   ├── email/            # Email templates
│   ├── layouts/          # Shared Blade layouts
│   └── form.blade.php    # Form rendering template
│
├── .env.example          # Environment variable template
├── .htaccess.example     # Apache rewrite rules template
└── index.php             # Entry point

🧱 Architecture Overview

Routing is handled by a lightweight custom router in the /routes/ folder.
Controllers follow a single-responsibility principle and are located in app/Controllers.
Views use Blade-style templates (rendered manually via PHP).
Services encapsulate logic such as CAPTCHA handling, mailing, CSRF, validation, storage, and file processing.
StorageService manages secure file storage using local storage or AWS S3.
AttachmentDeliveryService handles protected download links, expiration, passwords, and download limits.
Config is centralized in app/config.php, loaded during bootstrap.

⚙️ Configuration System

All UI and backend behavior is configured via:


/app/config.php

Example settings:

return [
  'form' => [
    'fields' => [
      'name' => ['enabled' => true, 'required' => true],
      'email' => ['enabled' => true, 'required' => true],
      'message' => ['enabled' => true, 'required' => true],
      'attachment' => ['enabled' => true, 'required' => false],
      'captcha' => ['enabled' => true],
    ],
  ],
];

Storage Configuration

File storage is controlled through the storage configuration:

'storage' => [
  'enabled' => true,
  'type' => 'local', // local or s3
],

Supported storage backends:

local — stores files on the application server
s3 — stores files securely in AWS S3

Files are stored privately and are not exposed through public URLs.

Attachment Delivery Mode

Attachment delivery behavior is controlled through:

'mode' => $_ENV['ATTACHMENT_DELIVERY_MODE'] ?? 'attachment',

Available modes:

attachment

Stores the file securely.
Attaches the file directly to the outgoing email.
Does not include a download link.

link

Stores the file securely.
Sends a protected download link.
Supports password protection, expiration dates, download limits, and logging.

🔐 Security Architecture

1. CSRF Protection

CSRF tokens are generated and validated manually.
Tokens are injected into the form via hidden input.
CSRF config is in config.php['csrf'].

2. CAPTCHA System

Implemented via App\Services\CaptchaService:

Google reCAPTCHA v2 or Cloudflare Turnstile
Based on CAPTCHA_PROVIDER in .env
Rendered dynamically in Blade view:

{!! $captcha !!}

3. Input Validation

Handled in the App\Services\FormValidationService:

Checks for required fields
Sanitization
Email validation
File validation
MIME type verification
File extension validation
Maximum file size validation

4. Secure File Uploads

Files are validated before storage.
Allowed types and maximum sizes are enforced.
Files are stored through App\Services\StorageService.
Files are not publicly accessible.

Supported storage:

Local secure storage
AWS S3 private bucket storage

Attachment workflows:

Direct Attachment

attachment

File is stored securely.
File is attached directly to the email.
No download button or URL is included in the email.

Secure Download Link

link

File is stored securely.
Email contains a protected download URL.
Supports:
- Token-based access
- Optional password protection
- Expiration dates
- Download limits
- Download logging

🖼️ Blade Templating

Blade-style templates are used with custom PHP rendering methods.

Main view file:

/views/form.blade.php

Layout inheritance via @extends('layouts.app')
Content injection via @section('content')
Asset pushing via @push('scripts')

🤖 AI-Powered Message Generator

Intelligent message drafting with OpenAI integration.

How it works:

A modal asks users: “What do you want to say?”
Based on their intent, the system contacts OpenAI’s API.
A full, human-like message is generated and placed into the form.
User can review and send or edit further.

Highlights:

Smooth loading state with spinner
Error handling and success toasts
Works with Dark Mode
Placeholder guidance for best UX

To enable:

Set your OpenAI API key in the .env file.
Endpoint and token handling are performed through secure backend calls.

🌍 Internationalization (i18n)

Language files are JSON-based:

/lang/en.json
/lang/es.json

To add a language:

Copy an existing .json file.
Translate all keys.
Ensure the filename (for example fr.json) matches the language code.
The UI automatically detects available languages.

Add the corresponding language-specific pattern to the form rendering template.

const languagePatterns = {
  fr: {
    subjectLabels: ['sujet'],
    namePlaceholders: ['votre nom']
  },
},

Language switcher types:

Dropdown: style.lang = switch
Flags: style.lang = icon

📄 Email Templates

HTML templates are stored in:

/views/email/

Customize the email layout, subject, or message body as needed.

Attachment rendering depends on the configured delivery mode:

Attachment Mode

File is included directly as an email attachment.
No download button or URL is displayed.

Link Mode

Email contains a secure download button.
Password information is displayed when enabled.

📨 Submission Logic

Located in:

app/Controllers/MailController.php

Responsibilities include:

Validating request data
Validating CAPTCHA and CSRF token
Validating uploaded files
Storing files through StorageService
Creating secure download links through AttachmentDeliveryService
Sending email via PHPMailer
Attaching files directly or sending secure download links depending on delivery mode
Responding with JSON for frontend JavaScript

🧪 Testing & Debugging

Enable debug mode in .env:

LOG_LEVEL=DEBUG

Logs are written to:

/storage/logs/

Frontend uses Bootstrap toasts and inline validation for user feedback.

⚡ Scripts & Assets

Frontend JavaScript:

/public/assets/js/contact(.min).js

Manages form submission
Client-side validation
Shows spinner and toast messages
Manages file input UI and resets

Frontend Styles:

/public/assets/css/

Bootstrap-based styling
Theme and layout customizations

🧩 Extending the Form

To add a new field:

Update config.php['form']['fields'] to enable the field.
Add form input logic to form.blade.php.
Add language keys to lang/*.json.
Add validation logic to the controller.
Optionally add email template support.

🧼 Deployment Notes

Disable APP_ENV=development in production.
Always configure .env securely.
Apply correct file/folder permissions:
- Required storage directories must be writable (typically 775 CHMOD).
- Local secure file storage directories must be writable.
- AWS S3 credentials must be configured securely.
Secure the /public directory via web server configuration.
Logs should be rotated or cleared regularly.

🛠 Maintenance Tips

Task	How
Add new field	Edit `config.php` + `form.blade.php`
Add new language	Add `lang/xx.json`
Change theme	Edit CSS and `style['mode']` or `lang` in config
Modify email format	Edit `views/email/*.blade.php`
Reset logs	Delete files in `storage/logs/`
Update CAPTCHA keys	Edit `.env`
Change file storage	Edit `storage` configuration
Change attachment behavior	Edit `attachment_delivery.mode`

🤝 Contributing

If you are working as a certified vendor or contractor, follow these standards:

PSR-12 code style
Use descriptive commits
Document all changes
Avoid modifying core logic without approval