Bulk Image Converter Pro

Version 2.0.2 — Comprehensive Installation & User Guide

Thank you for purchasing Bulk Image Converter Pro! This document covers everything you need to install, configure, and customise the application. For technical support, contact us via your Envato profile.

1. Overview & Features
2. Server Requirements
3. Installation
4. Configuration
5. Database Setup
6. Admin Access
7. Email Setup
8. Credit System & Payments
9. Free Tools
10. SEO & Sitemap
11. Customisation
12. Troubleshooting
13. Updating
14. Support

1. Overview & Features

Bulk Image Converter Pro is a premium, privacy-first image conversion platform. Users can convert, resize, and process images entirely client-side or through a powerful server-side engine.

Key Features

Bulk Image Conversion — JPEG, PNG, WebP, AVIF, HEIC, TIFF, BMP, ICO
PDF Tools — Image → PDF and PDF → Images
EXIF / Metadata Removal — Strip GPS, camera info, and hidden metadata
Resize & Quality Control — Custom dimensions and compression levels
Credit System — Monetize with pay-per-use credits or subscriptions
Free Tools Suite — EXIF Viewer, Image Cropper, Color Palette, Google Search, Image Inspector, Size Comparator
User Dashboard — History, settings, support tickets, subscription management
Admin Panel — Users, payments, packages, analytics, support, settings
Blog / SEO — Markdown-based blog, auto-sitemap, landing pages for format pairs
Mobile Views — Dedicated mobile-optimised pages
Dark Mode — Full dark mode support across all pages
Privacy First — Zero-server processing option, no image upload required

2. Server Requirements

Component	Minimum	Recommended
PHP	8.0	8.2+
MySQL / MariaDB	5.7 / 10.3	8.0 / 10.11
Web Server	Apache 2.4	Apache 2.4 + nginx reverse proxy
PHP Extensions	GD, PDO MySQL, ZipArchive	GD + Imagick, PDO MySQL, ZipArchive, mbstring, cURL
Disk Space	100 MB	500 MB
Memory (PHP)	128 MB	256 MB
HTTPS	Not required	Strongly recommended

Note: Imagick (ImageMagick) provides better quality conversions than GD. The app auto-detects and prefers Imagick when available.

3. Installation

3.1 Quick Install (Shared Hosting)

Upload files — Upload the entire project to your web root (e.g., public_html).
Create database — Create a MySQL database and user in your hosting control panel.
Import schema — Import database.sql into your database via phpMyAdmin or CLI:
```
mysql -u your_user -p your_database < database.sql
```
Set permissions — Ensure these directories are writable:
```
chmod 755 temp/ logs/ uploads/
```
Configure environment — Copy .env.example to .env and fill in your database credentials.
Visit your site — Open your domain in a browser. The converter should load immediately.

Important: Never commit .env to version control. It contains sensitive database and SMTP credentials.

3.2 Manual Configuration (No .env)

If your hosting doesn't support .env files, edit api/config.php directly:

define('DB_HOST', 'localhost');
define('DB_NAME', 'your_database_name');
define('DB_USER', 'your_database_user');
define('DB_PASS', 'your_database_password');

3.3 Using Composer (Optional)

The app uses Composer for PHPMailer and Parsedown. Run this from the project root:

composer install --no-dev

Composer is optional — the app falls back gracefully if vendor/ is not present, though email sending and blog features will be limited.

4. Configuration

4.1 Environment Variables

Variable	Default	Description
`APP_ENV`	`production`	`production`, `development`, `maintenance`
`DB_HOST`	`localhost`	Database server hostname
`DB_NAME`	`image_convert_pro`	Database name
`DB_USER`	`root`	Database username
`DB_PASS`	`root`	Database password
`GUEST_CREDITS_SECRET`	`fallback_...`	Random string for guest credit signing
`TRUST_PROXY_HEADERS`	`0`	Set to `1` behind Cloudflare/load balancer
`TRUSTED_PROXY_IPS`		Comma-separated IPs of trusted proxies

4.2 Site Settings (Admin Panel)

After logging in as admin, visit Admin → General Settings to configure:

Site name, favicon, support email
SMTP credentials for transactional emails
Guest credit limit and credit costs per feature
Admin security code protection

4.3 Apache Rewrite Rules

The included .htaccess enables clean URLs for format pairs (e.g., /png-to-webp), blog posts, and the sitemap. Ensure mod_rewrite is enabled on your server.

5. Database Setup

5.1 Schema Overview

Table	Purpose
`users`	Registered users, passwords, credit balances, subscription status
`admins`	Admin login credentials
`packages`	Credit packages (Starter, Pro, Enterprise) with pricing
`payment_methods`	Available payment options (Bank Transfer, Crypto, etc.)
`transactions`	Payment receipt tracking (pending/approved/declined)
`support_tickets`	User-submitted support requests
`ticket_replies`	Admin replies to support tickets
`site_settings`	Key-value store for all configurable settings
`activity_logs`	Audit trail for user and admin actions
`visitor_activity`	Anonymized visitor tracking for analytics
`page_views`	Page view statistics
`advertisements`	Built-in promotional ads and cross-promotions
`support_resources`	Help center articles and links

5.2 Seed Data

The database.sql includes seed data with sample packages, payment methods, ads, and a default admin account (admin / admin123). Change this password immediately after first login.

6. Admin Access

6.1 First Login

Navigate to /admin/login.php
Login with default credentials (if not changed):
Username: admin
Password: admin123
Change your password from the Admin Users page.

Security: Always change the default admin password. For production, use the CLI tool instead:

php tools/create_admin.php --username=admin --password="your-strong-password"

6.2 Admin Panel Sections

Section	Description
Dashboard	Analytics overview: signups, payments, conversions, errors, recent activity
Users	Manage registered users, view credits, approve/decline, search
Payments	Review payment receipts, approve or decline with reason
Finance	Revenue analytics, transaction history, receipt viewer
Packages	Create/edit credit packages with pricing and limits
Settings	Site name, email SMTP, credit costs, favicon, security code
Ads	Manage in-app advertisements and cross-promotions
Support	View, reply, and close user support tickets
Notifications	System activity log with read/unread tracking
Performance	Conversion success rates, error tracking

7. Email Setup

7.1 Configure SMTP

Go to Admin → General Settings
Fill in SMTP Host, Port, Username, Password, and Encryption
Set the Support Email address (used as the From address)
Click Save

7.2 Email Templates

HTML email templates are located in api/templates/email/. You can customise these freely:

welcome.html — Sent after registration
verify_email.html — Email verification link
forgot_password.html — Password reset request
password_reset_success.html — Password changed confirmation
receipt_received.html — Payment proof received
pending_invoice.html — Invoice/reminder
plan_activated.html — Plan/subscription activated
payment_declined.html — Payment declined notification

Templates use {{variable}} placeholders which are replaced dynamically.

Tip: If SMTP is not configured, the app logs email errors and continues operating normally. All core features work without email.

8. Credit System & Payments

8.1 How Credits Work

Each file conversion costs 1 credit. Advanced features (PDF, EXIF strip) cost additional credits as configured in Admin Settings. Users start with a daily guest limit and can purchase packages to increase their balance.

8.2 Subscription Plans

The app supports monthly subscription cycles. When a user's plan expires, their credits revert to the default package. You can configure:

Credit packages (name, limit, price, description)
Payment methods (bank transfer, crypto, or custom)
Admin approval workflow for receipts

8.3 User Flow

User selects a package from the Pricing page
Choose a payment method and upload a receipt
Admin reviews and approves/declines the payment in Payments
Credits are added to the user's account automatically on approval

9. Free Tools Suite

Six free tools are included to drive engagement and SEO traffic:

Tool	URL	Description
EXIF Viewer	`/tools/exif-viewer.php`	Upload an image to view all EXIF, GPS, IPTC, and XMP metadata
Image Inspector	`/tools/image-inspector.php`	Detailed image analysis: dimensions, color depth, compression info
Color Palette	`/tools/color-palette.php`	Extract dominant colors from any image with hex codes
Size Comparator	`/tools/size-comparator.php`	Compare file sizes across formats and quality settings
Image Cropper	`/tools/image-cropper.php`	Client-side image cropping with aspect ratio presets (1:1, 16:9, etc.)
Google Operator Search	`/tools/google-operator-search.php`	Build advanced Google search queries with operators and presets

All tools are rate-limited for guest users (configurable in Admin Settings). Signed-in users get unlimited access.

10. SEO & Sitemap

10.1 Built-in SEO Features

Automatic XML sitemap at /sitemap.xml — includes all pages, format-pair landing pages, and blog posts
Format-pair landing pages — Each conversion pair (e.g., /png-to-webp) is a unique indexable page
SEO-friendly URLs — Clean URLs via .htaccess, canonical tags, Open Graph meta
Blog engine — Markdown-based blog with automatic slug generation and sitemap inclusion
JSON-LD structured data — Organization and BreadcrumbList schema markup
Meta tags — Description, keywords, OG/Twitter card meta on every page
Robots.txt — Proper crawl directives and sitemap reference

10.2 Adding Blog Posts

Create a markdown file in blog/posts/ with this naming convention:

YYYY-MM-DD-your-post-slug.md

Blog posts automatically appear on the blog index and are added to the sitemap.

11. Customisation

11.1 Styling

CSS is organised into three files:

css/tailwind.input.css — Tailwind source (can be recompiled)
css/tailwind.css — Compiled Tailwind output
css/styles.css — Custom styles organised by component

11.2 JavaScript

js/converter-api.js — Backend API client and upload logic
js/converter.js — Main UI wiring, preview, and download handlers
js/toast.js — Toast notification utility

11.3 Layouts & Components

layouts/public.php — Public-facing pages (home, about, pricing)
layouts/dashboard.php — Authenticated user dashboard shell
layouts/auth.php — Login/register pages
layouts/auth_split.php — Split-screen auth layout
components/header.php — Main site header with Free Tools dropdown
components/sidebar.php — Dashboard sidebar navigation
components/footer.php — Site footer with links

11.4 Adding Format Pairs

Edit config/format-pairs.php to add new conversion pairs. Each entry automatically creates a landing page and sitemap entry.

11.5 White-Labelling

To rebrand the application:

Update APP_NAME and APP_AUTHOR in api/config.php
Change site_name in Admin Settings
Replace favicons in assets/icons/
Update email templates in api/templates/email/
Update the footer copyright text in components/footer.php

12. Troubleshooting

Issue	Solution
Uploads fail	Increase `upload_max_filesize` and `post_max_size` in PHP. The .htaccess sets 100M by default.
ZIP download fails	Ensure the `ZipArchive` PHP extension is installed and enabled.
Conversions fail	Ensure GD or Imagick is installed. Check PHP error logs for details.
Blank page / 500 error	Enable `APP_ENV=development` to see PHP errors. Check that all file paths are correct.
404 on format pages	Ensure `mod_rewrite` is enabled and `.htaccess` is present in the web root.
Database connection error	Verify DB_HOST, DB_NAME, DB_USER, DB_PASS in your `.env` file. Check that the MySQL server is running.
Emails not sending	Verify SMTP settings in Admin → Settings. Check that PHPMailer is installed (`composer install`).
"Daily limit reached"	Increase `tool_daily_limit_guest` in Admin Settings or have the user create an account.
Admin security screen loops	Disable admin security in Admin Settings, or set `admin_security_enabled` to `0` in the database.
Images not showing after deploy	Flush any CDN or server cache. Verify that `temp/` and `uploads/` directories are writable.
500 on `vendor/autoload.php`	Run `composer install --no-dev` or create an empty `vendor/` directory if not using Composer.

Debug Mode: Set APP_ENV=development in your .env to display PHP errors and enable verbose logging. Never use this in production.

13. Updating

Backup your database and custom files (.env, custom templates, uploaded files).
Replace files — Upload the new version, overwriting existing files (keep your .env safe).
Run migrations — Check the changelog for any database schema changes. Apply them manually if needed.
Clear caches — Clear any PHP opcache, CDN cache, or browser cache.
Verify — Test conversion, login, admin panel, and email sending.

Always make a full backup before updating! This includes both the database and all application files.

14. Support

Support is provided exclusively through Envato's item support policy:

Item Support — 6 months of support included with purchase. Extendable.
What's covered: Bugs, installation issues, feature questions, and configuration help.
What's not covered: Custom modifications, third-party integrations, or white-labelling services.

Before contacting support:

Check this documentation thoroughly
Check the troubleshooting section above
Check your server error logs
Provide your APP_ENV, PHP version, and web server details

You're all set! Bulk Image Converter Pro is fully installed and ready to use. For feature updates and new tools, follow us on Envato.