Master Maria Ratings with this comprehensive installation and user guide, covering everything from basic setup to advanced features and spam protection.

1. System Requirements

PHP: Version 8.0 or higher.
Extensions: json and mbstring are required. If you choose MySQL/MariaDB for storage, the mysqli extension is also required.
CAPTCHA (Pro): To use Cloudflare Turnstile or Google reCAPTCHA v3, outbound HTTPS is required (the curl extension is preferred; otherwise allow_url_fopen must be On in your server's php.ini).
Emails (Pro): Outbound SMTP or PHP mail() capabilities are required for Double Opt-in verification and admin notification emails.

2. Installation Guide

Step 1: Uploading the Files

Extract the downloaded Maria Ratings archive and upload the entire folder to your web hosting environment via FTP, SFTP, or your hosting control panel's file manager.

Step 2: Running the Installer

Navigate to the installation file in your web browser (for example: https://yourwebsite.com/maria-ratings/install.php). The visual installer will guide you through creating your administrator account (username and password).

Step 3: Choosing a Storage Driver

During installation, you must select how you want to store your review data:

JSON File Storage: The simplest option. Requires zero configuration and is great for small sites or testing. Ensure your storage/ folder has write permissions.
MySQL/MariaDB: Strongly recommended for production environments, Pro media workflows, and high-traffic websites. You will need to provide your database host, name, username, password, and a table prefix.

Once installation is complete, you can log in to your admin panel by navigating to /admin/.

3. Upgrading from Free to Pro

If you are upgrading from Maria Ratings Free to Pro, you do not have to lose your existing reviews:

Upload the Pro files and overwrite your existing Free installation.
Important for JSON users: Ensure you do not overwrite your existing storage/ directory, as this contains your live data.
If you used MySQL/MariaDB, simply run the Pro installer and connect using the exact same database credentials. Your existing data will be recognized automatically.

4. Embedding the Review Widget

To display the review widget on your website, place the following HTML snippet exactly where you want the reviews to appear:

<div data-maria-ratings data-product-key="your-product-id"></div>
<script src="https://yourwebsite.com/maria-ratings/embed.js" defer></script>

Note: Change your-product-id to a unique identifier for the specific product, service, or page being reviewed. This ensures reviews are kept separate for different items across your site.

5. Admin Dashboard & Moderation

Log into your admin dashboard (/admin/index.php) to manage your reviews. From here, you can:

Moderate Reviews: Approve, reject, or delete pending reviews.
Reply to Customers (Pro): Post public owner replies directly underneath customer reviews.
Export Data: Download a CSV file of all your reviews for backups or external analysis.
Configure Settings: Adjust rate limiting, blocked words, required form fields, and allowed origins.

6. Detailed Settings Guide

The Maria Ratings admin panel is divided into several configuration tabs. Here is a comprehensive breakdown of what you can control in each section:

General Settings

Auto-Approve Reviews: Choose whether reviews are published immediately or held in the dashboard for manual moderation. You can also configure it to automatically approve only 4 and 5-star reviews.
Reviews Per Page: Control how many reviews load initially before the user has to click the "Load More" button.
Sort Order: Set the default sorting behavior (Latest, Oldest, Highest Rating, or Lowest Rating).
Theme: Switch between default widget themes (such as Classic or Dark mode) to best match your website's aesthetic.
Allowed Origins: A critical security setting. Enter the exact domains (e.g., https://yourwebsite.com) where your widget is embedded to prevent attackers from submitting reviews from unauthorized websites.

Form Fields & Messages

Field Visibility & Requirements: Take full control over the Name, Email, and Website fields. For each field, you can decide if it is shown on the form, if it is mandatory to fill out, and whether the data is displayed publicly on the published review.
Custom Text & Translations: Customize the text for buttons, form labels, and success messages. This is the perfect place to translate the widget into your local language.

Spam & Security (Free & Pro)

IP Rate Limiting: Restrict how many reviews can be submitted from the exact same IP address within a specific timeframe (e.g., limit to 3 reviews per 24 hours) to stop flooding.
One Review Per Email: Prevent users from artificially inflating ratings by submitting multiple reviews for the same product using the same email address.
Blocked Words: Create a comma-separated list of prohibited words (such as profanity, competitor names, or "http://"). Reviews containing these words will be automatically blocked.

Pro Features & Integrations

If you are using Maria Ratings Pro, you have access to a dedicated suite of premium configurations:

Media Uploads: Toggle customer photo and video uploads on or off. You can strictly set the maximum number of files allowed per review and restrict the maximum file size (in MB) to save your server's storage space.
Multi-Criteria Ratings: Instead of just a single overall star rating, you can define custom metrics (e.g., Quality, Value, and Shipping Speed) and require customers to rate each one individually.
Rich Text Editor: Replaces the standard plain-text box with a beautiful WYSIWYG editor, allowing your reviewers to use bold, italics, and formatted text.
Helpful Voting: Enable community engagement by allowing site visitors to vote if a review was helpful or unhelpful.
Verified Badges: Display an official "Verified" checkmark badge next to reviewers who have completed double opt-in verification.
SEO Schema (JSON-LD): Automatically inject structured data into your web pages so Google and other search engines can display aggregate star ratings directly in search results, boosting your click-through rate.
CAPTCHA Configuration: Select Google reCAPTCHA v3 or Cloudflare Turnstile to block bots silently without annoying picture puzzles. Enter your Site Key and Secret Key provided by the service to activate it.
SMTP Email Settings: Enter your SMTP credentials (Host, Port, Username, Password, Encryption) to reliably send Double Opt-in verification emails to users.
Admin Notifications: Automatically send an email alert to your inbox the moment a new review is submitted so you can moderate it quickly.
Double Opt-in Email Verification: To prevent fake reviews, you can force users to verify their email addresses. Users will receive an automated email link they must click before their review is marked for moderation.

7. Security Best Practices

Before launching your review system to the public, please ensure the following security measures are in place:

Allowed Origins: In your admin settings, explicitly define the domain names (e.g., https://yourwebsite.com) that are allowed to submit reviews. Do not use the wildcard * in a production environment.
Protect JSON Storage: If you are using JSON storage instead of MySQL, you must block direct web access to the storage/ directory to prevent data leaks. Apache users are protected by default via the included .htaccess file. If you use Nginx or IIS, you must configure your server rules to explicitly deny access to this folder.

Maria Ratings: Complete Installation and User Guide