CORE 2.2 / PRO PREVIEW

From first install
to the full experience.

Practical integration guides for the open-source engine and every Pro workflow. Choose your starting point, copy the examples, and keep your application in control.

01CORE · FREE / MITInstall Core by itself →Use the open-source engine and build your own interface. 02NEW PRO APPLICATIONInstall Pro directly →Composer installs the compatible Core package automatically. 03EXISTING CORE 2.2+Add Pro without starting over →Keep your configuration, migrations, and existing review data. 04PRO · INCLUDED MODULESEnable only what you use →Every Pro feature is included; its extra migrations remain opt-in.

One Pro command installs Core automatically in a new application.

Existing Core data stays put when adding Pro to a compatible 2.2+ installation.

Optional means opt-in, not extra cost. Both paid plans include every Pro module.

Installation

Core is the free, MIT-licensed package. These instructions target the 2.2 series, which includes optional review images. Pro is a separate commercial companion. Its ^1.0 installation steps apply after the first tagged release is available through CodebyRay.

Requirements

Core supports Laravel 10–13 and PHP 8.1+, subject to the PHP version required by your Laravel release.
Pro requires Core ^2.2, which Composer installs automatically. Livewire 3.6+ or 4 is needed only when using Pro's Livewire interface; React and Vue installations do not require Livewire.
Reviewable models and users need compatible numeric IDs. UUID-based identity is not supported by the current core schema.
Use a supported, patched framework release in production. Historical compatibility is not a reason to deploy an unpatched framework.

Install Core by itself

Use this path when installing only the free Core package. If you purchased Pro for a new application, skip this command and follow Install Pro in a new application below—Composer will install Core automatically.

composer require codebyray/laravel-review-rateable:^2.2

php artisan vendor:publish --provider="Codebyray\ReviewRateable\ReviewRateableServiceProvider" --tag=config
php artisan vendor:publish --provider="Codebyray\ReviewRateable\ReviewRateableServiceProvider" --tag=migrations

php artisan migrate

Laravel discovers the provider automatically. The default migrations create reviews and ratings; they do not install an image table. Publish each migration once, inspect it, then run it. Re-publishing timestamped migrations can create duplicates.

Upgrading from 1.x is not an in-place upgrade. Version 2 is a rewrite; plan a data migration and update your integration before changing versions.

Model

Add the trait to a saved Eloquent model. The package uses a polymorphic review relationship, so products, posts, services, and bookings can share the same review engine.

namespace App\Models;

use Codebyray\ReviewRateable\Traits\ReviewRateable;
use Illuminate\Database\Eloquent\Model;

class Product extends Model
{
    use ReviewRateable;
}

Your application still owns the product model, authentication, authorization, routes, and front end. Do not submit reviews against an unsaved model. When using multiple databases, reviews, ratings, images, and compatible user tables must be available on the target model's connection.

Configuration

Core's settings live in config/review-rateable.php. This example replaces the department map with two application-specific review contexts:

'user_model' => \App\Models\User::class,

'min_rating_value' => 1,
'max_rating_value' => 5,
'approved_review' => false,

'departments' => [
    'default' => [
        'ratings' => [
            'overall' => 'Overall',
            'quality' => 'Quality',
            'price' => 'Value for money',
        ],
    ],
    'support' => [
        'ratings' => [
            'overall' => 'Overall',
            'speed' => 'Response speed',
            'knowledge' => 'Knowledge',
        ],
    ],
],

Rating keys are stored identifiers; labels are display text. Keep keys stable when changing labels. The selected department determines which criteria are processed. Pro's form requires every displayed criterion.

Set user_model to the model behind your authentication provider. Pro's selected guard and core's user model must use the same numeric identity namespace; overlapping user IDs from unrelated providers are not supported.

approved_review defaults to false. Turn it on only if your application intentionally publishes immediately. Approval is a visibility decision, not a purchase-verification check.

After changing cached production configuration, rebuild your configuration cache using your deployment's normal process.

Review

Create a review safely

Use an authenticated endpoint and authorize the target before calling core. Core is a persistence API, not a replacement for your request validation or policies. For example, inside your application's controller action:

use Illuminate\Http\Request;

public function store(Request $request, Product $product)
{
    $this->authorize('review', $product);

    $validated = $request->validate([
        'review' => ['required', 'string', 'min:10', 'max:5000'],
        'recommend' => ['sometimes', 'boolean'],
        'ratings' => ['required', 'array:overall,quality,price'],
        'ratings.overall' => ['required', 'integer', 'between:1,5'],
        'ratings.quality' => ['required', 'integer', 'between:1,5'],
        'ratings.price' => ['required', 'integer', 'between:1,5'],
    ]);

    $review = $product->addReview([
        'review' => $validated['review'],
        'recommend' => $request->boolean('recommend'),
        'department' => 'default',
        'ratings' => $validated['ratings'],
    ], $request->user()->getKey());

    return response()->json(['review_id' => $review->id], 201);
}

Import your own Product class and define the review policy/Gate. If your base controller does not use Laravel's AuthorizesRequests trait, use Gate::authorize('review', $product) instead. Match the validation keys and boundaries to your configured department.

The author ID must come from the authenticated server context. Do not accept approved, author IDs, verification flags, or arbitrary departments from an untrusted payload. Trusted internal writers may explicitly pass approved to override core's default.

Core can also store a review without an author by passing null; Pro's customer submission and author-editing workflows require authentication.

Update, approve, and delete

Authorize each operation and ensure the review belongs to the intended target. These core methods are available on the reviewable model:

$product->updateReview($reviewId, [
    'review' => 'My updated experience.',
    'recommend' => true,
    'ratings' => [
        'overall' => 4,
        'quality' => 4,
        'price' => 5,
    ],
]);

$product->approveReview($reviewId);
$product->deleteReview($reviewId);

These methods do not apply Pro's author editing, duplicate-submission policy, verification, or content-filter workflows. Route author-facing Pro edits through ReviewEditingManager instead. Deletion is permanent; use approval controls to hide content you want to retain.

Use the service contract

The injectable service provides a decoupled alternative to the trait API. Set the saved target before using it:

use Codebyray\ReviewRateable\Contracts\ReviewRateableContract;

public function store(Product $product, ReviewRateableContract $reviews)
{
    // Authorize and validate before this point.
    $reviews->setModel($product);

    return $reviews->addReview([
        'review' => 'A thoughtful, validated review.',
        'ratings' => ['overall' => 5],
    ], auth()->id());
}

Adapt the payload to your configured criteria. Do not reuse a service instance across targets without setting its model again.

Queries and statistics

Core returns approved reviews by default. Request pending reviews only from an authorized private workflow.

$published = $product->getReviews();
$pending = $product->getReviews(false);
$withoutRatings = $product->getReviews(true, false);

$supportReviews = $product->getReviewsByDepartment('support');
$fiveStarReviews = $product->getReviewsByRating(
    5, department: 'support'
);

$total = $product->totalReviews();
$supportTotal = $product->totalDepartmentReviews('support');

$overall = $product->averageRating('overall');
$averages = $product->averageRatings();
$supportAverage = $product->averageRatingByDepartment('support', 'overall');

$allCriteriaAverage = $product->overallAverageRating();
$distribution = $product->ratingCounts('default');
$stats = $product->ratingStats('default');

ratingStats() returns counts, percentages, and total. Core's distribution/statistics APIs count rating rows across criteria, not one overall score per review. Likewise, getReviewsByRating() matches a review with any criterion at the requested value. For an overall-only breakdown or filter, scope the ratings relationship to your chosen key. Pro's summary and filters do this using listing.summary_rating_key.

Use the relationship for pagination, eager loading, or custom criteria:

$reviews = $product->reviews()
    ->where('department', 'default')
    ->where('approved', true)
    ->whereHas('ratings', fn ($query) => $query
        ->where('key', 'overall')
        ->where('value', 5))
    ->with(['ratings', 'user'])
    ->latest()
    ->paginate(10);

Only eager-load optional relationships after installing their tables. Avoid unapproved content in public JSON, caches, or summaries.

Photos

Image persistence is included in Core, not reserved for Pro. Install the separate table only when you need it:

php artisan vendor:publish --provider="Codebyray\ReviewRateable\ReviewRateableServiceProvider" --tag=review-images-migrations
php artisan migrate

# Only when using Laravel's public disk:
php artisan storage:link

Configure storage and limits in Core's config:

'images' => [
    'disk' => 'public',
    'directory' => 'review-images',
    'thumbnail_directory' => 'review-images/thumbnails',
    'max_count' => 10,
    'max_file_size' => 5120,
    'allowed_mime_types' => [
        'image/jpeg',
        'image/png',
        'image/webp',
        'image/gif',
    ],
    'delete_files_on_delete' => true,
],

File size is in kilobytes, for each original or supplied thumbnail. Files are stored beneath review-specific directories. Use a configured Laravel disk whose URL behavior suits your application. SVG uploads are excluded by default because active image formats need additional safeguards.

Add originals and thumbnails

Authorize uploads and validate the request before attachment. Core also enforces its configured count, size, and MIME limits.

$review->addImages($request->file('photos', []));

$image = $review->addImage(
    image: $request->file('front'),
    altText: 'Front of the product',
    thumbnail: $generatedThumbnail,
);

$originalUrl = $image->url();
$thumbnailUrl = $image->thumbnailUrl();

The thumbnail argument is optional. Core does not generate or resize thumbnails; thumbnailUrl() falls back to the original when none was supplied. Create thumbnails and strip EXIF/GPS metadata in your own image-processing workflow.

Remove, reorder, and eager-load

$review->removeImage($imageId);

// Include every attached image ID exactly once.
$review->reorderImages([$thirdImageId, $firstImageId, $secondImageId]);

$reviews = $product->reviews()
    ->where('approved', true)
    ->with(['ratings', 'images', 'user'])
    ->paginate(10);

images() returns ordered attachments. Images expose their original/thumbnail helpers and alt text for your own gallery. Core intentionally does not mandate Blade components, a JavaScript slideshow, or a CSS framework.

File cleanup and privacy

Deleting an image or review model schedules file deletion only after successful database deletion/commit. Cleanup failures are reported without undoing committed database work. Disable delete_files_on_delete if your application owns retention.

Bulk query deletions bypass Eloquent model events and therefore automatic cleanup. Delete model instances or use the package's deleteReview() method.

Database rollback cannot undo filesystem writes. In custom core integrations, track and clean newly stored files if a larger transaction rolls back. Pro's submission/editing workflows manage their own new-upload cleanup.

Pending does not mean private storage. A public disk URL remains accessible even when its review is unapproved. If images need confidentiality, design a private disk and authorized delivery strategy; do not rely on approval alone.

Pro

Pro adds the customer experience and team workflows without replacing Core's tables or models. The public demo runs the real components. Pro is distributed through CodebyRay's authenticated Composer repository rather than Packagist or direct access to its private GitHub repository.

Purchase and private installation

Choose and purchase a Pro license. General CBR registration remains closed; a successful purchase creates your customer account and sends its password-setup email.
Sign in and open My Licenses under Software.
Create one Composer credential named for the project. Save it immediately—the secret is shown only once. Use that same project credential locally, in staging, CI, and production.
Add the private repository to the application's root composer.json:

{
    "repositories": [
        {
            "type": "composer",
            "url": "https://app.cbrapps.com/packages"
        }
    ]
}

Create auth.json beside composer.json, using the secret displayed by the license portal:

{
    "bearer": {
        "app.cbrapps.com": "YOUR_PROJECT_CREDENTIAL"
    }
}

Add /auth.json to .gitignore. Never commit the credential, paste it into a support request, or place it in composer.json.

Choose the installation path that matches your application. A new Pro customer does not need to install Core separately.

Install Pro in a new application

Install Pro directly:

composer require codebyray/laravel-review-rateable-pro:^1.0

Composer authenticates with CBR, downloads the entitled Pro release, and automatically installs the compatible Core ^2.2 dependency from Packagist. Do not run a separate composer require for Core.

Composer never runs package migrations automatically. Publish and migrate Core's core schema first, then publish Pro's configuration:

php artisan vendor:publish --provider="Codebyray\ReviewRateable\ReviewRateableServiceProvider" --tag=config
php artisan vendor:publish --provider="Codebyray\ReviewRateable\ReviewRateableServiceProvider" --tag=migrations

php artisan migrate

php artisan vendor:publish --tag=review-rateable-pro-config

Core's base migrations create the reviews and ratings tables required by Pro. Publish only the optional Pro module migrations your application will use, then run php artisan migrate again.

Add Pro to an existing Core 2.2+ application

Keep the application's existing Core configuration, migrations, and review data. Add Pro directly:

composer require codebyray/laravel-review-rateable-pro:^1.0
php artisan vendor:publish --tag=review-rateable-pro-config

Composer reuses the installed compatible Core release or updates it within the allowed ^2.2 constraint. Do not republish migrations that the application has already published. Confirm Core's base migrations have run before publishing any Pro module migrations.

Core 1.x is not compatible with Pro 1.x. Complete the application's migration to Core 2.2+ before adding Pro; do not force Composer past the version conflict.

Customers do not receive the private GitHub URL or GitHub access. In both installation paths, Core continues to own core reviews, ratings, configuration, and image storage while Pro adds interfaces and optional workflows.

For CI and deployments, store the complete authentication object as a protected secret named COMPOSER_AUTH rather than creating a committed file:

{"bearer":{"app.cbrapps.com":"YOUR_PROJECT_CREDENTIAL"}}

Composer reads COMPOSER_AUTH automatically. Mask the value in logs and restrict it to the project licensed to use it.

Normal composer update includes Pro when its constraints permit a newer entitled release. To update it explicitly with its dependencies, run:

composer update codebyray/laravel-review-rateable-pro --with-dependencies

Coverage expiry does not disable installed code. It limits repository access to releases published during the covered update period; renewing extends access to newer releases. If a credential is lost or exposed, revoke it in My Licenses and create a replacement for the same project.

An authentication error from packages.json usually means the bearer host does not exactly match app.cbrapps.com, the credential was copied incorrectly, or it has been revoked. A package/version not found error can mean no entitled release matches the requested Composer constraint. Confirm the repository entry, credential, license status, and available releases before retrying with composer clear-cache.

Pro interfaces

Every Pro license includes all three interface families. Choose the one that matches the consuming application; there is no interface add-on or separate purchase.

Interface	Best fit	What Pro supplies
Livewire 3.6+/4	Blade-first Laravel applications	Six server-rendered components, Tailwind and Bootstrap templates, and Alpine-powered galleries
React 18/19	React applications and Inertia/custom SPA screens	Publishable JSX components, shared browser client, and base CSS
Vue 3	Vue applications and Inertia/custom SPA screens	Publishable single-file components, shared browser client, and base CSS
Vue 2.7 legacy	Existing applications during migration	The same Options API source compiled with the Vue 2 Vite plugin

The Livewire demo, React demo, and Vue demo read and write the same Laravel records. The UI runtime changes; validation, identity, permissions, throttling, moderation, and storage remain server-side.

The same REVIEW_RATEABLE_PRO_THEME value applies to all three. Livewire selects a complete Tailwind or Bootstrap Blade template set. React and Vue use framework-neutral markup and receive the theme key from the context API, then the published shared stylesheet applies its matching Tailwind-like or Bootstrap-like preset. The JavaScript components therefore do not require Tailwind or Bootstrap themselves. Custom JavaScript themes can override CSS beneath .rrp-client[data-rrp-theme="custom"].

Livewire setup

Livewire is an optional Composer dependency. Install it only when using the Blade components:

composer require livewire/livewire

Set up Tailwind (the default) or Bootstrap CSS using the customization instructions. The complete Livewire templates work directly from Pro without publishing. If you want to edit their Blade markup, publish only the theme you use:

php artisan vendor:publish --tag=review-rateable-pro-tailwind-views
# Or, for Bootstrap:
php artisan vendor:publish --tag=review-rateable-pro-bootstrap-views

The published files live under resources/views/vendor/review-rateable-pro/themes/. See Styles & publishable views for theme selection, CSS setup, and override details. With the selected framework's CSS and Livewire assets installed in your layout, render the two main components:

<livewire:review-rateable-pro-review-form
    :reviewable="$product"
    :key="'review-form-'.$product->getKey()" />

<livewire:review-rateable-pro-review-list
    :reviewable="$product"
    :key="'review-list-'.$product->getKey()" />

For another department, pass department="support" to both. The model must use the core trait and be saved. Do not load a second Alpine instance alongside Livewire.

The form includes configured star criteria, recommendation, validation, loading states, and submission throttling. The list includes approved-review summaries, sorting, filters, and pagination. By default, authors may see their own pending reviews; other visitors cannot.

React setup

Enable the API with a safe alias for each reviewable model. Do not accept a PHP class name from the browser:

'api' => [
    'enabled' => true,
    'prefix' => 'review-rateable-pro/api/v1',
    'middleware' => ['web'],
    'reviewables' => [
        'products' => App\Models\Product::class,
    ],
    'author_name_attribute' => 'name',
],

Publish the React source and install React in the application:

php artisan vendor:publish --tag=review-rateable-pro-react
npm install react react-dom
npm install --save-dev @vitejs/plugin-react

Create a Vite entry such as resources/js/reviews-react.jsx:

import React from 'react';
import { createRoot } from 'react-dom/client';
import { createReviewRateableClient } from './vendor/review-rateable-pro/core/client.js';
import './vendor/review-rateable-pro/core/review-rateable.css';
import { ReviewRateable } from './vendor/review-rateable-pro/react/index.jsx';

const element = document.querySelector('[data-review-rateable]');
const client = createReviewRateableClient({
    contextUrl: element.dataset.contextUrl,
});

createRoot(element).render(<ReviewRateable client={client} />);

Mount it from Blade and include the entry in the application's Vite inputs:

<meta name="csrf-token" content="{{ csrf_token() }}">

<div data-review-rateable
     data-context-url="{{ route('review-rateable-pro.api.context', [
         'reviewable' => 'products',
         'reviewableId' => $product->getRouteKey(),
     ]) }}"></div>

@viteReactRefresh
@vite('resources/js/reviews-react.jsx')

Keep @viteReactRefresh before the React entry. It installs Vite's development refresh preamble; omitting it can leave the mount element empty while the browser reports that the React preamble was not detected. Production builds do not emit the refresh runtime.

React's renderReview prop replaces individual review cards without forking the form, query, or pagination behavior.

Vue setup

Use the same API configuration shown above, publish the Vue source, and install Vue 3 plus its Vite plugin:

php artisan vendor:publish --tag=review-rateable-pro-vue
npm install vue
npm install --save-dev @vitejs/plugin-vue

import { createApp } from 'vue';
import { createReviewRateableClient } from './vendor/review-rateable-pro/core/client.js';
import './vendor/review-rateable-pro/core/review-rateable.css';
import { ReviewRateable } from './vendor/review-rateable-pro/vue/index.js';

const element = document.querySelector('[data-review-rateable]');
const client = createReviewRateableClient({
    contextUrl: element.dataset.contextUrl,
});

createApp(ReviewRateable, { client }).mount(element);

Use the same Blade mount element as React. Vue exposes a scoped review slot for application-owned cards. For an existing Vue 2.7 application, install @vitejs/plugin-vue2 instead and mount with new Vue({ render: h => h(ReviewRateable, { props: { client } }) }). Vue 2.7 is end-of-life compatibility for migrations, not the recommended choice for a new application.

API security and customization

The default web middleware makes the API same-origin, session-authenticated, and CSRF-protected. For a separate first-party SPA, replace it with the application's established Sanctum/API middleware and CORS policy. Configure view_ability and create_ability for private or purchase-gated models. In a tenant application, bind Codebyray\ReviewRateablePro\Contracts\ReviewableResolver to an implementation that establishes tenant context before resolving the mapped model.

The shared browser client exposes reviews, submit, update, addUpdate, setHelpful, report, reply, and moderate. Server-side Gates remain mandatory even when the application hides a button. The JSON resource intentionally excludes verification evidence and private content-filter records.

Published JavaScript becomes application-owned source under resources/js/vendor/review-rateable-pro. Re-publishing with --force overwrites changes. Keep customized components outside that directory or review and commit the diff before upgrading.

'images' => ['enabled' => true],

'form' => [
    'min_length' => 10,
    'max_length' => 5000,
    'submissions_per_minute' => 3,
    'one_review_per_user' => true,
],

'listing' => [
    'per_page' => 10,
    'show_own_pending' => true,
    'summary_rating_key' => 'overall',
],

Enable images only after installing Core's image migration. Pro uses core's storage limits and adds upload previews, ordering controls, thumbnails, and a full-review image dialog. Keep summary_rating_key valid for the selected department.

Optional modules

All Pro modules are included in both paid plans at no additional charge. In these instructions, "optional" means a feature is enabled through configuration and its migrations only when your application needs it—not that it is a separately priced add-on. Core's photo support is also included free.

Each setup below follows the same order: publish the migration, inspect and run it, then edit the published configuration. Turning a feature off hides its functionality without dropping its data. Core's base reviews/ratings migrations must already be installed.

Publish configuration once

If you have not already published the configuration files, run:

php artisan vendor:publish --provider="Codebyray\ReviewRateable\ReviewRateableServiceProvider" --tag=config
php artisan vendor:publish --tag=review-rateable-pro-config

Core's settings live in config/review-rateable.php; Pro's settings live in config/review-rateable-pro.php. The PHP snippets below are entries inside those files' existing return [...] arrays, not complete replacement files. Replace the matching entry and keep the other settings intact. Do not append a second entry with the same key or use --force to overwrite a customized file.

Module setup index

Feature and setup	Publish tag	Schema
Photos	`review-images-migrations` (Core provider)	`review_images`
Titles	`review-rateable-pro-titles-migrations`	Nullable title on `reviews`
Author editing	`review-rateable-pro-editing-migrations`	`review_edit_states`, `review_updates`
Official replies	`review-rateable-pro-replies-migrations`	`review_replies`
Helpful votes	`review-rateable-pro-helpful-votes-migrations`	`review_helpful_votes`
Verified badges	`review-rateable-pro-verification-migrations`	`review_verifications`
Reader reports	`review-rateable-pro-reports-migrations`	`review_reports`
Invitations	`review-rateable-pro-invitations-migrations`	`review_invitations`
Content filtering	`review-rateable-pro-content-moderation-migrations`	`review_content_flags`

Moderation, basic forms/listing, and the one-review-per-user form setting do not require separate Pro tables. Base reviews/ratings are always required. Optional features are independently disabled by default.

Enabling a feature without its migration causes database errors. Rolling back an optional migration permanently deletes its saved metadata; disable the feature rather than rolling it back in a populated application.

Module: photos

Publish Core's image migration and run it. The storage-link command is needed only when serving Laravel's public disk through its usual symlink:

php artisan vendor:publish --provider="Codebyray\ReviewRateable\ReviewRateableServiceProvider" --tag=review-images-migrations
php artisan migrate
php artisan storage:link

In config/review-rateable.php, configure image storage and limits:

'images' => [
    'disk' => 'public',
    'directory' => 'review-images',
    'thumbnail_directory' => 'review-images/thumbnails',
    'max_count' => 5,
    'max_file_size' => 5120,
    'allowed_mime_types' => [
        'image/jpeg',
        'image/png',
        'image/webp',
        'image/gif',
    ],
    'delete_files_on_delete' => true,
],

max_file_size is kilobytes per image (5120 = 5 MB). Core's image API works after the table is installed; it has no separate enable flag. If using Pro's upload form and gallery, also set this in config/review-rateable-pro.php:

'images' => ['enabled' => true],

The disk must exist in config/filesystems.php. Public URLs are not protected by review approval, and thumbnails are not generated automatically. See image APIs, eager loading, cleanup, and private-storage considerations.