WP Social Ninja Developer Guide

Welcome to the complete developer guide for WP Social Ninja — the all-in-one WordPress plugin for social feeds, business reviews, testimonials, and chat widgets. This guide takes you from understanding the fundamentals to building sophisticated integrations and custom functionality across the whole plugin family.

What is WP Social Ninja?

WP Social Ninja aggregates social media feeds, business reviews, chat widgets, testimonials, and shoppable content from 12+ platforms — Google, Facebook, Instagram, TikTok, YouTube, Airbnb, Yelp, TripAdvisor, Amazon, AliExpress, Booking.com, and WooCommerce — and displays them anywhere on a WordPress site.

Under the hood it runs on WPFluent, a Laravel-inspired mini-framework with a service container, REST routing, policies, an Eloquent-like ORM, and migrations. If you have used Laravel, extending WP Social Ninja will feel familiar.

Why Extend WP Social Ninja?

WP Social Ninja is designed to be highly extensible. Whether you are customizing a client site or building a commercial add-on, the plugin exposes clean, well-defined extension points instead of forcing you to modify core files.

🔧 Built for Customization

• Extensive hook system — dozens of action and filter hooks across reviews, feeds, chat, and templates.
• Template override seam — every rendered element (avatar, rating, content, media…) is an action hook you can replace.
• RESTful API — a policy-authorized REST namespace you can extend with your own endpoints.
• WordPress-native — follows WordPress coding standards and the plugin's own wpsr_ conventions.

🏗️ Flexible Extension Points

• New platforms — subclass BaseReview / BaseFeed and register via the dynamic per-platform settings hooks.
• Custom output — override any template element hook to change how a review or feed item renders.
• Data integrations — react to review/template/widget lifecycle hooks to sync data elsewhere.
• Custom endpoints — register REST routes for external apps or mobile clients.

💼 The Plugin Family

• No lock-in — your customizations live in your own plugin, hooking a stable API.
• Pro-aware — the same hook seam that powers the free templates is where Pro layers its premium features.
• Complete control — modify any aspect of the output to match your design.

The Three Plugins

WP Social Ninja ships as a family of plugins. This documentation covers all three.

WP Social Ninja (Free Core)

The foundation. Slug: wp-social-reviews. Provides the WPFluent framework, REST API, admin Vue SPA, migrations, and most platforms.

• ✅ Social Feeds — Facebook, Instagram, Twitter/X, YouTube
• ✅ Business Reviews — Google, Facebook, Yelp, and more
• ✅ Testimonials & Chat Widgets
• ✅ Shortcode & template system
• ✅ Full developer API — hooks and REST endpoints

WP Social Ninja Pro

Slug: wp-social-ninja-pro. A premium add-on that boots off the free core and layers in advanced features by hooking the same wpsocialreviews/ seam.

• 🚀 Premium platforms & templates
• 🚀 Native review-collection forms ([wpsr_review_form])
• 🚀 AI review summaries (OpenAI / OpenRouter)
• 🚀 WooCommerce & FluentCart product reviews, custom sources, managers
• 🚀 Licensing & updates

Pro refuses to boot unless a compatible core version is active — see Core ↔ Pro Coupling.

Custom Feed for TikTok

Slug: custom-feed-for-tiktok. A standalone free TikTok feed plugin that versions independently (1.x.x) and renders through the core shortcode. See Custom Feed for TikTok.

Core Development Concepts

📊 Data Architecture

WP Social Ninja stores its data in a small set of custom wpsr_ tables plus WordPress postmeta and options:

• ⭐ Reviews (wpsr_reviews) — every review, testimonial, and custom review.
• 🗃️ Caches (wpsr_caches) — feed/API response cache with expiration.
• 📝 Review Forms (wpsr_review_forms) — native review-collection form definitions.
• 🖼️ Optimized Images (wpsr_optimize_images) — locally optimized media records.
• Templates & widgets — stored as WordPress posts with _wpsr_* post meta.

See the Database Schema for the full column-by-column reference and an interactive ER diagram.

🔄 How a Request Flows

plugins_loaded → Application boots → wp_social_reviews_loaded(_v2)
rest_api_init  → routes.php → api.php → Router registers routes
HTTP request   → Policy → Controller → Service → Model → Cache/DB → JSON

Read the full walkthrough in Request Lifecycle.

🔌 Extension Points

There are several ways to extend WP Social Ninja:

• WordPress hooks — actions and filters for events and output.
• REST API — register your own endpoints.
• Platform services — add a platform by subclassing a base class.
• Shortcodes — render templates programmatically with [wp_social_ninja].

Directory Structure

Understanding the core plugin (wp-social-reviews) layout:

wp-social-reviews/
├── wp-social-reviews.php     # Entry point — defines constants, requires boot/app.php
├── boot/
│   ├── app.php               # Creates the Application, fires bootstrap hooks
│   └── globals.php           # Framework-independent global helpers (loaded first)
├── config/
│   ├── app.php               # App config incl. rest_namespace / rest_version
│   └── database.php          # Database config
├── app/
│   ├── Http/
│   │   ├── Controllers/      # REST controllers
│   │   ├── Routes/api.php    # All REST endpoints (policy-authorized)
│   │   └── Policies/         # Authorization policies
│   ├── Services/Platforms/   # Reviews / Feeds / Chats integrations
│   ├── Models/               # Eloquent-like models (wpsr_ tables)
│   ├── Hooks/Handlers/       # WordPress hook handlers
│   └── Views/                # PHP template files
├── database/Migrations/      # Schema migrations (classmap autoloaded)
├── resources/                # Vue admin SPA, public JS, SCSS
└── vendor/wpfluent/          # The WPFluent framework

A deeper tour is in Directory Structure.

Development Environment Setup

Prerequisites

• WordPress 5.0+ — a modern WordPress installation
• PHP 7.4+ — the plugin's minimum (PHP 7.0 is explicitly blocked)
• Node.js + npm — for the front-end build
• Composer — for PHP dependencies
• Basic WordPress development — hooks, plugins, and the REST API

Install & Build

# Install dependencies
npm install
composer install

# Development watch mode
npx mix watch

# Production build
npx mix --production

# Full release build (free + pro)
sh ./build.sh --node-build --with-pro

The front end is compiled with Laravel Mix 6 (webpack.mix.js) — Vue 3 + Element Plus for the admin SPA, React for Gutenberg blocks.

PHP Quality Gate

A pre-push hook runs PHPStan (level 2) and PHPCS (PHPCompatibility 7.4–8.4) on every push that touches PHP files. See dev/README.md in the core plugin for setup and manual run commands. Run it before pushing to catch issues early.

Coding Conventions

These conventions are mandatory and keep contributions consistent.

Naming Prefixes

Layer	Prefix	Example
CSS/HTML classes & IDs	wpsr-	wpsr-card-title
PHP variables/functions	wpsr_	wpsr_process_order()
JS variables/functions	wpsr camelCase	wpsrProductIds
Database tables	wpsr_	wpsr_reviews
WordPress options	wpsr_	wpsr_reviews_google_settings
Hook / filter namespace	wpsocialreviews/	wpsocialreviews/backend_sanitized_values

Validation & Sanitization

• Never assume an ID has a value — continue on empty in loops, early return in functions, validate before DB queries and API calls. Use empty() in PHP, !value in JS.
• Sanitize backend input with wpsr_backend_sanitizer() and a sanitize map.
• Persist options with autoload disabled: update_option($key, $value, 'no').
• Sanitize style/CSS config with the wpsr_sanitize_* helpers — see Sanitizers.

PHP Patterns

• Namespaces: WPSocialReviews\App\ (application), WPSocialReviews\Framework\ (framework).
• Helper aliases: GlobalHelper and ServicesHelper both map to App\Services\Helper.
• Platform services extend base classes — see Platform Services.
• boot/globals.php loads before the framework, so never call framework services from it.

Getting Started Checklist

📖 Read the fundamentals

• [ ] Understand the architecture and request lifecycle
• [ ] Review the database schema and models
• [ ] Skim the global helpers

🔍 Explore the hooks

• [ ] Browse action hooks
• [ ] Study filter hooks
• [ ] Try overriding a template element hook

🏗️ Build your first extension

• [ ] React to wpsocialreviews/custom_review_created
• [ ] Register a REST endpoint
• [ ] Scaffold a platform service

Community & Support

• User Documentation — the site-owner guide
• WP Social Ninja Website — product & support

Versions at time of writing

Core, Pro, WPSOCIALREVIEWS_CORE_MIN_VERSION, and WPSOCIALREVIEWS_PRO_MIN_VERSION are all 4.4.0; the database schema version (WPSOCIALREVIEWS_DB_VERSION) is 122; Custom Feed for TikTok is 1.2.5. Always check the plugin headers for the versions you target.