README

Rating Petition

A Composer library for WordPress plugins that can be used to encourage plugin users to review and rate a plugin in the WordPress.org repository.

The package provides:

dismissible admin notices shown after a configured usage period,
text-based rating petitions rendered on selected admin screens,
popup rating petitions with AJAX feedback handling,
display decision strategies for WordPress admin screens,
WooCommerce shipping method watchers used to decide when a petition can be shown.

This package is a library, not a standalone WordPress plugin. It does not contain a plugin bootstrap file and should be initialized from a host plugin.

Requirements

PHP 7.4 or later.
WordPress admin context.
WooCommerce is required only when using the shipping method watchers or ShippingMethodDisplayDecision.

Runtime Composer dependencies are installed automatically:

wpdesk/wp-notice
wpdesk/wp-plugin-flow-common

No minimum WordPress or WooCommerce version is declared by this package.

Installation via Composer

In order to install the package via Composer run the following command:

composer require wpdesk/wp-wpdesk-rating-petition

The package uses the WPDesk\RepositoryRating\ PSR-4 namespace.

Admin notice usage

All hookable classes must be registered by calling hooks() from the host plugin.

Shipping zones area

<?php

use WPDesk\RepositoryRating\RatingPetitionNotice;
use WPDesk\RepositoryRating\TimeWatcher\ShippingMethodInstanceWatcher;

function init_repository_rating() {
    $time_tracker = new ShippingMethodInstanceWatcher(
        'my_shipping_method',
        'plugin_activation_my-plugin/my-plugin.php',
        '2026-01-01',
        My_Shipping_Method::class
    );
    $time_tracker->hooks();

    ( new RatingPetitionNotice(
        $time_tracker,
        'my_plugin',
        'My Plugin',
        'https://wordpress.org/support/plugin/my-plugin/reviews/#new-post'
    ) )->hooks();
}

ShippingMethodInstanceWatcher stores the time when the first watched WooCommerce shipping method instance is added. If the host plugin was activated before the provided zero date, existing matching shipping methods are treated as the starting point. The activation time option passed as the second constructor argument must be provided by the host plugin.

Shipping method settings screen

<?php

use WPDesk\RepositoryRating\RatingPetitionNotice;
use WPDesk\RepositoryRating\TimeWatcher\ShippingMethodGlobalSettingsWatcher;

function init_repository_rating() {
    $time_tracker = new ShippingMethodGlobalSettingsWatcher(
        'my_shipping_method'
    );
    $time_tracker->hooks();

    ( new RatingPetitionNotice(
        $time_tracker,
        'my_plugin',
        'My Plugin',
        'https://wordpress.org/support/plugin/my-plugin/reviews/#new-post'
    ) )->hooks();
}

ShippingMethodGlobalSettingsWatcher stores the time when a shipping method global settings section is saved for the first time.

RatingPetitionNotice shows the first notice after two weeks from the tracked creation time. If the user chooses "maybe later", the second notice is scheduled two weeks later. Notices are displayed only on supported WooCommerce admin screens: shop_order, edit-shop_order, and woocommerce_page_wc-settings.

Text petition usage

Use TextPetitionDisplayer when the rating request should be rendered as inline admin text.

<?php

use WPDesk\RepositoryRating\DisplayStrategy\GetParametersDisplayDecision;
use WPDesk\RepositoryRating\RepositoryRatingPetitionText;
use WPDesk\RepositoryRating\TextPetitionDisplayer;

( new TextPetitionDisplayer(
    'admin_footer',
    new GetParametersDisplayDecision(
        [
            [
                'page' => 'wc-settings',
                'tab'  => 'shipping',
            ],
        ]
    ),
    new RepositoryRatingPetitionText(
        'WP Desk',
        'My Plugin',
        'https://wordpress.org/support/plugin/my-plugin/reviews/#new-post',
        'center'
    )
) )->hooks();

Popup petition usage

Use PopupPetition when the user should first choose a star rating. Ratings of four stars or more open the WordPress.org rating URL. Lower ratings open a feedback form that can send the message with wp_mail().

<?php

use WPDesk\RepositoryRating\DisplayStrategy\GetParametersDisplayDecision;
use WPDesk\RepositoryRating\PopupPetition\PopupPetition;

$current_user = wp_get_current_user();

( new PopupPetition(
    'my-plugin',
    'My Plugin',
    'support@example.com',
    $current_user->user_email,
    'admin_footer',
    new GetParametersDisplayDecision(
        [
            [
                'page'    => 'wc-settings',
                'tab'     => 'shipping',
                'section' => 'my_shipping_method',
            ],
        ]
    )
) )->init()->hooks();

The popup stores the ${plugin_slug}_popup_petition_displayed WordPress option after a successful rating redirect or feedback submission. The "Later" action fires the wpdesk_rating_petition_postpone action with the plugin slug.

Display decisions

Display decisions implement WPDesk\RepositoryRating\DisplayStrategy\DisplayDecision and control whether text or popup petitions should be displayed.

AlwaysDisplayDisplayDecision always returns true.
GetParametersDisplayDecision matches $_GET conditions. Inner arrays are AND conditions, outer arrays are OR conditions.
ShippingMethodDisplayDecision matches WooCommerce shipping settings screens for a specific shipping method ID.

Assets and translations

Popup assets are built from assets-src/js/RatingPetitionPopup.jsx and assets-src/scss/RatingPetitionPopup.scss into assets/dist/RatingPetitionPopup.js and assets/dist/RatingPetitionPopup.css.

The package uses the wp-wpdesk-rating-petition text domain. Translation files are stored in lang/.

Development

Install PHP dependencies:

composer install

Useful Composer scripts:

composer phpcs
composer phpunit-unit-fast
composer phpunit-unit
composer phpunit-integration-fast
composer phpunit-integration
composer docs

The integration PHPUnit configuration expects WordPress and WooCommerce development checkouts in /tmp/wordpress-develop and /tmp/woocommerce by default.

Install Node dependencies and build popup assets:

npm install
npm run dev
npm run watch
npm run prod

License

This package is released under the MIT license.

wpdesk / wp-wpdesk-rating-petition

Maintainers

Package info

Statistics

Security