1. Download and unzip the latest version of the application.
2. Upload the extracted application files to your domain.com web root (or your preferred subdirectory) using FTP, SFTP, SSH, or your hosting control panel.
   • If your download contains a software.zip archive, upload and extract it on the server.
   • Ensure the application's public directory is accessible from the web according to your deployment setup.
3. Verify that the required writable directories (such as storage/ and your configured local upload directory, if applicable) have the appropriate permissions before continuing with the installation.

Set the access permissions of the following to (CHMOD) 644 for files and 775 for folders:

• Files
  • .env
• Folders
  • storage/cache
  • storage/logs
  • Your configured local storage/upload directory (if using local file storage)

If you configure Amazon S3 for file storage, no writable upload directory is required on the web server. Only the storage/ directories used by the application must remain writable.

Set your domain’s web root to the application’s public directory according to your hosting environment.

For example, if the application is uploaded to the domain.com folder, configure your domain’s document root to point to:

domain.com/public

If your hosting provider does not allow changing the document root—such as when your domain is tied directly to the default public_html directory—upload the application files there and configure the included rewrite rules according to your server setup.

Ensure that application directories such as app/, storage/, views/, and vendor/ are not directly exposed publicly. Only the public/ directory should be accessible from the web.

1. Rename .env.example to .env and configure:
   • CAPTCHA provider and keys (Google reCAPTCHA or Cloudflare Turnstile)
   • Mail server settings (SMTP configuration)
   • Storage method and credentials (local storage or Amazon S3)
   • Attachment delivery mode (email attachment or secure download link)
   • Application URL and environment settings
   • OpenAI API Key (optional, for AI message generation)
2. Rename .htaccess.example to .htaccess if using Apache.
3. Edit app/config.php to customize:
   • Form fields and validation rules
   • Branding and interface options
   • Attachment handling and storage configuration
   • Mail and notification behavior
4. Add or modify languages in /lang/ as needed.
5. Test the complete application workflow:
   • Form submission and validation
   • CSRF protection
   • File uploads and attachment delivery
   • CAPTCHA rendering
   • Language switching
   • Dark/light mode
   • AI message generator modal (if enabled)
   • Email delivery and attachment handling

• Uses layout inheritance via @extends('layouts.app')
• Content is injected using @section('content')
• JavaScript and additional assets can be included with @push('scripts')
• Email templates are located in /views/email/ and support both standard attachments and secure download links.
• Templates automatically adapt to the configured branding, language, and attachment delivery mode.

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

• Duplicate an existing .json file.
• Translate all language keys into the target language.
• Rename the file using the appropriate language code (for example, fr.json).
• The application automatically detects and loads available language files.

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

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

• Dropdown menu: style.lang = 'switch'
• Flag icons: style.lang = 'icon'

• Form labels, placeholders, and validation messages.
• Email templates and notification messages.
• Attachment download text and password-protected link messages.
• AI message generator interface and system prompts.

• Email layout and branding
• Subject lines
• Message body content
• Attachment presentation (standard attachment or secure download link)
• Download button, password section, and attachment notices
• Language-specific email translations

Directory structure:

├── app/
│ ├── Controllers/ - HTTP and API logic
│ │ ├── MailController.php - Form submission and email processing
│ │ └── DownloadController.php - Secure attachment download handling
│ ├── Models/ - Data models
│ ├── Services/ - Reusable business logic and external integrations
│ │ ├── StorageService.php - Local and Amazon S3 storage handling
│ │ ├── AttachmentService.php - File validation and attachment rules
│ │ └── AttachmentDeliveryService.php - Secure download link generation and delivery handling
│ ├── bootstrap.php - Bootstrap and app initialization
│ └── config.php - Centralized configuration
├── lang/ - JSON language files
├── public/ - Public-facing assets (CSS, JS, images, uploads)
├── routes/ - Application routing including secure download routes
├── storage/ - Caching, logs, attachment metadata, and private file storage
├── 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

• Routing is handled by a lightweight custom router in the /routes/ folder, including secure attachment download routes.
• Controllers follow a single-responsibility principle and are located in app/Controllers.
• Views use Blade-style templates (rendered manually via PHP).
• Services encapsulate reusable logic such as CAPTCHA handling, mailing, CSRF protection, file validation, storage management, and secure attachment delivery.
• Attachment workflows are separated into dedicated services for validation, storage, and protected download generation.
• Configuration is centralized in app/config.php and loaded during bootstrap.

1. CSRF Protection
   • CSRF tokens are generated and validated manually.
   • Tokens are injected into forms via hidden input fields.
   • CSRF configuration is available in config.php['csrf'].
   • AJAX requests return refreshed tokens when sessions expire or validation fails.
2. CAPTCHA System
   • Implemented via the CaptchaService class in App\Services.
   • Supports Google reCAPTCHA v2 or Cloudflare Turnstile.
   • Provider selection is controlled through the CAPTCHA_PROVIDER value in the .env file.
   • Rendered dynamically in Blade views using:
     {!! $captcha !!}
3. Input Validation
   • Handled through dedicated validation services and controller-level request processing.
   • Checks for required fields.
   • Input sanitization and filtering.
   • Email validation and security checks.
   • File validation using MIME detection, extension rules, and size restrictions.
4. Secure File Uploads and Attachment Handling
   • Files are processed through dedicated attachment and storage services.
   • Uploads are validated using MIME checks, extension validation, file size limits, and integrity checks.
   • Storage can use local private storage or Amazon S3.
   • Direct access to stored files is prevented by using controlled delivery workflows.
   • Attachment delivery supports both direct email attachments and protected download links.
5. Protected Attachment Downloads
   • Secure download URLs are generated using unique tokens.
   • Optional password protection is available for sensitive files.
   • Download expiration and maximum download limits can be configured.
   • Download access is handled through dedicated secure routing.

• Validating incoming request data
• Verifying CSRF and CAPTCHA protection
• Processing validated form submissions
• Coordinating attachment workflows through dedicated services
• Sending email via PHPMailer
• Attaching uploaded files directly when attachment delivery mode is enabled
• Generating secure attachment links when protected download mode is enabled
• Returning JSON responses for the frontend

• app/Services/AttachmentService.php - File validation rules and upload requirements
• app/Services/AttachmentDeliveryService.php - Secure download link generation and delivery workflows
• app/Services/StorageService.php - Local and Amazon S3 storage management

• Set LOG_LEVEL=DEBUG in .env

• Form validation failures
• CSRF and CAPTCHA verification issues
• File upload validation errors
• Attachment storage and delivery processing events
• Secure download access attempts
• Email sending status and errors

• Bootstrap toasts
• Inline error and validation messages
• AJAX response handling with automatic CSRF token refresh when required
• File upload status and validation feedback

• Located in /public/assets/js/
• Handles form submission, AJAX communication, client-side validation, CSRF token refresh handling, toasts, spinner animations, and dynamic form interactions
• Manages file input controls, attachment validation feedback, upload state handling, and user interface updates
• Uses configured application URLs to support deployments across different environments

• Located in /public/assets/css/
• Includes Bootstrap overrides, responsive styling, accessibility improvements, and theme customizations
• Supports light and dark mode presentation adjustments

1. Enable the field in config.php['form']['fields']
2. Add the input field to form.blade.php
3. Add new language strings to each lang/*.json file
4. Add backend validation rules through the appropriate validation service or controller logic
5. Update email templates in views/email/ if the field data should be included in outgoing messages
6. Update frontend JavaScript handling if the field requires custom validation, dynamic behavior, or UI interaction

• Backup all files from your current installation directory.
• Backup the following critical files:
  • .env
  • app/config.php
  • Any custom Blade views you modified (especially under views/)
  • Uploaded files stored through your configured storage location
  • Private attachment storage files (local storage or configured cloud storage)
  • Attachment metadata and secure download records if applicable
  • Logs (storage/logs/) if needed for audits or troubleshooting
• Verify that storage configuration settings are preserved, including local paths, Amazon S3 credentials, and attachment delivery settings.

• Download the latest licensed version of Securaine from the official distribution channel.
• Unzip the new version locally.

Before upgrading production:

• Set up a staging site using a copy of your .env and configuration files.
• Verify:
  • Form loads and submits successfully
  • CAPTCHA and CSRF validations work correctly
  • Emails are sent correctly through the configured mail provider
  • File upload validation works as expected
  • Attachment delivery mode works correctly (email attachment or secure download link)
  • Protected download links, passwords, expiration rules, and download limits function correctly if enabled
  • Local storage and Amazon S3 storage integrations work correctly if configured
  • Any custom Blade views, language files, and frontend customizations still function as expected

Carefully replace or merge files. Recommended steps:

1. Open your existing .env file.
2. Compare it with the new .env.example file.
3. Add any new environment variables introduced in the update.

• Once everything has been uploaded and configured:
  • Open your site in a private/incognito browser window.
  • Test the complete contact form submission workflow.

• Form validation
• CSRF protection
• File uploads
• Attachment delivery (Attachment mode or Secure Link mode)
• CAPTCHA functionality (Google reCAPTCHA or Cloudflare Turnstile)
• AI message generation (if enabled)
• Email delivery and attachments
• Language switching and translations