API Reference – Plain Classes Gutenberg

Plain Classes Gutenberg provides extensive APIs for developers to integrate with and extend the plugin’s functionality. This documentation covers REST endpoints, PHP hooks, JavaScript APIs, and customization options.

Table of Contents

🌐 REST API Endpoints

Authentication

All REST API endpoints require proper authentication:

WordPress nonce: X-WP-Nonce header
User capability: manage_options or appropriate permissions
License validation: Active license required for full functionality

Base URL

https://yoursite.com/wp-json/pcguten/v1/

📊 Class Management Endpoints

Get All Classes

GET /pcguten/v1/classes

Response:

{
  "success": true,
  "data": [
    {
      "id": 1,
      "name": "bg-blue-500",
      "type": "imported",
      "created_at": "2024-01-15T10:30:00Z"
    },
    {
      "id": 2,
      "name": "text-white",
      "type": "scanned",
      "created_at": "2024-01-15T11:15:00Z"
    }
  ],
  "total": 150
}

Add Classes

POST /pcguten/v1/classes
Content-Type: application/json

{
  "classes": ["new-class-1", "new-class-2"],
  "type": "imported"
}

Response:

{
  "success": true,
  "message": "2 classes added successfully",
  "data": {
    "added": 2,
    "duplicates": 0
  }
}

Delete Class

DELETE /pcguten/v1/classes/{id}

Response:

{
  "success": true,
  "message": "Class deleted successfully"
}

Delete All Classes

DELETE /pcguten/v1/classes/all

Response:

{
  "success": true,
  "message": "All classes deleted successfully",
  "deleted_count": 150
}

🔍 File Scanning Endpoints

Get Scan Paths

GET /pcguten/v1/scan-classes/paths

Response:

{
  "success": true,
  "data": {
    "paths": [
      {
        "id": 1,
        "path": "/wp-content/themes/my-theme/style.css",
        "type": "file",
        "enabled": true
      },
      {
        "id": 2,
        "path": "/wp-content/themes/my-theme/assets/",
        "type": "directory",
        "enabled": true
      }
    ]
  }
}

Add Scan Path

POST /pcguten/v1/scan-classes/paths
Content-Type: application/json

{
  "path": "/wp-content/themes/my-theme/css/",
  "type": "directory"
}

Clear Scan Paths

POST /pcguten/v1/scan-classes/paths/clear

Start File Scan

POST /pcguten/v1/scan-classes/scan

Response:

{
  "success": true,
  "message": "Scan completed successfully",
  "data": {
    "files_scanned": 15,
    "classes_found": 234,
    "new_classes": 45,
    "duration": "2.3s"
  }
}

🎛️ Settings Endpoints

Get Assistant Settings

GET /pcguten/v1/settings/assistant

Response:

{
  "success": true,
  "data": {
    "assistant_enabled": true,
    "breakpoints_enabled": true,
    "position": "top-left"
  }
}

Update Settings

POST /pcguten/v1/settings/assistant
Content-Type: application/json

{
  "assistant_enabled": true,
  "breakpoints_enabled": false
}

🔧 PHP Hooks & Filters

Action Hooks

Plugin Initialization

/**
 * Fired when Plain Classes Gutenberg is fully loaded
 */
do_action('pcguten_loaded');

/**
 * Fired before plugin initialization
 */
do_action('pcguten_before_init');

/**
 * Fired after plugin initialization
 */
do_action('pcguten_after_init');

Class Management

/**
 * Fired before classes are added to database
 * 
 * @param array $classes Array of class names
 * @param string $type Class type ('imported', 'scanned', 'gutenberg')
 */
do_action('pcguten_before_add_classes', $classes, $type);

/**
 * Fired after classes are added
 * 
 * @param array $classes Added classes
 * @param string $type Class type
 * @param array $result Addition result
 */
do_action('pcguten_after_add_classes', $classes, $type, $result);

/**
 * Fired before class deletion
 * 
 * @param int $class_id Class ID to delete
 */
do_action('pcguten_before_delete_class', $class_id);

/**
 * Fired after class deletion
 * 
 * @param int $class_id Deleted class ID
 */
do_action('pcguten_after_delete_class', $class_id);

File Scanning

/**
 * Fired before file scanning starts
 * 
 * @param array $file_paths Paths to scan
 */
do_action('pcguten_before_scan', $file_paths);

/**
 * Fired after scanning completes
 * 
 * @param array $found_classes Classes found during scan
 * @param array $file_paths Scanned paths
 */
do_action('pcguten_after_scan', $found_classes, $file_paths);

/**
 * Fired when async scan is triggered
 * 
 * @param int $post_id Post ID that triggered scan
 * @param string $post_title Post title
 */
do_action('pcguten_async_css_scan', $post_id, $post_title);

Filter Hooks

Core Configuration

/**
 * Enable/disable automatic scanning
 * 
 * @param bool $enabled Default: true
 * @return bool
 */
apply_filters('pcguten_enable_auto_scan', true);

/**
 * Post types that trigger automatic scanning
 * 
 * @param array $post_types Default: ['scorg']
 * @return array
 */
apply_filters('pcguten_auto_scan_post_types', ['scorg']);

/**
 * Modify plugin capabilities
 * 
 * @param string $capability Default: 'manage_options'
 * @return string
 */
apply_filters('pcguten_required_capability', 'manage_options');

Class Processing

/**
 * Filter classes before adding to database
 * 
 * @param array $classes Array of class names
 * @param string $type Class type
 * @return array
 */
apply_filters('pcguten_filter_classes', $classes, $type);

/**
 * Filter scanned classes from specific files
 * 
 * @param array $classes Found classes
 * @param string $file_path File being scanned
 * @return array
 */
apply_filters('pcguten_scanned_classes', $classes, $file_path);

/**
 * Filter gutenberg classes from post content
 * 
 * @param array $classes Extracted classes
 * @param int $post_id Post ID
 * @return array
 */
apply_filters('pcguten_gutenberg_classes', $classes, $post_id);

File Scanning

/**
 * Supported file extensions for scanning
 * 
 * @param array $extensions Default: ['.css', '.scss', '.js', '.php']
 * @return array
 */
apply_filters('pcguten_scan_file_extensions', ['.css', '.scss', '.js', '.php']);

/**
 * Regex patterns for class detection
 * 
 * @param array $patterns Array of regex patterns
 * @return array
 */
apply_filters('pcguten_scan_class_patterns', $patterns);

/**
 * Scan timeout in seconds
 * 
 * @param int $timeout Default: 180
 * @return int
 */
apply_filters('pcguten_scan_timeout', 180);

/**
 * Memory limit for scanning
 * 
 * @param string $limit Default: '256M'
 * @return string
 */
apply_filters('pcguten_scan_memory_limit', '256M');

UI Customization

/**
 * Customize frontend assistant position
 * 
 * @param string $position Default: 'top-left'
 * @return string Options: 'top-left', 'top-right', 'bottom-left', 'bottom-right'
 */
apply_filters('pcguten_assistant_position', 'top-left');

/**
 * Assistant keyboard shortcuts
 * 
 * @param array $shortcuts Default shortcuts array
 * @return array
 */
apply_filters('pcguten_assistant_shortcuts', $shortcuts);

/**
 * Autocomplete suggestions limit
 * 
 * @param int $limit Default: 50
 * @return int
 */
apply_filters('pcguten_autocomplete_limit', 50);

🎯 JavaScript APIs

Global Objects

Window.PlainClasses

// Access class data
window.plain_classes = {
  winden_classes: "...", // JSON string of classes
  // Other class sources
};

// Debug autocomplete data
console.log('Plain Classes:', window.plain_classes);

PCGUTEN_assistant

// Assistant configuration
window.PCGUTEN_assistant = {
  breakpoints: {...},
  breakpoints_html: "...",
  // Assistant settings
};

Frontend Assistant API

Element Selection

// Get currently selected element
const selectedElement = PCGUTEN.getSelectedElement();

// Select element programmatically
PCGUTEN.selectElement(document.querySelector('.my-element'));

// Element navigation
PCGUTEN.navigateToParent();
PCGUTEN.navigateToChild();
PCGUTEN.navigateToNext();
PCGUTEN.navigateToPrevious();

Class Management

// Get element classes
const classes = PCGUTEN.getElementClasses(element);

// Set element classes
PCGUTEN.setElementClasses(element, 'bg-blue-500 text-white p-4');

// Add classes to element
PCGUTEN.addClasses(element, ['new-class-1', 'new-class-2']);

// Remove classes from element
PCGUTEN.removeClasses(element, ['old-class']);

Assistant Control

// Show/hide assistant
PCGUTEN.showAssistant();
PCGUTEN.hideAssistant();

// Move assistant position
PCGUTEN.setPosition('top-right');

// Toggle breakpoint mode
PCGUTEN.toggleBreakpoints(true);

Block Editor Integration

Autocomplete API

// Access autocomplete data in block editor
const classes = wp.data.select('pcguten/classes').getClasses();

// Filter classes by type
const importedClasses = classes.filter(c => c.type === 'imported');

// Add classes programmatically
wp.data.dispatch('pcguten/classes').addClasses(['new-class'], 'imported');

Block Enhancement

// Enhance existing blocks with Plain Classes
import { addFilter } from '@wordpress/hooks';

addFilter(
  'editor.BlockEdit',
  'pcguten/add-plain-classes',
  (BlockEdit) => {
    return (props) => {
      // Add Plain Classes functionality
      return <BlockEdit {...props} />;
    };
  }
);

🛠️ Custom Development

Creating Extensions

Plugin Structure

<?php
/**
 * Plugin Name: Plain Classes Extension
 * Description: Custom extension for Plain Classes Gutenberg
 */

class PCG_Extension {
    public function __construct() {
        add_action('pcguten_loaded', [$this, 'init']);
    }

    public function init() {
        // Extension initialization
        add_filter('pcguten_filter_classes', [$this, 'filterClasses'], 10, 2);
    }

    public function filterClasses($classes, $type) {
        // Custom class processing
        return $classes;
    }
}

new PCG_Extension();

Custom Class Sources

/**
 * Add custom class source
 */
add_action('pcguten_after_init', function() {
    // Register custom class provider
    add_filter('pcguten_class_sources', function($sources) {
        $sources['custom'] = [
            'name' => 'Custom Framework',
            'classes' => get_custom_framework_classes(),
            'color' => '#ff6b35'
        ];
        return $sources;
    });
});

function get_custom_framework_classes() {
    // Return array of custom classes
    return ['custom-btn', 'custom-card', 'custom-grid'];
}

Database Schema

Classes Table

CREATE TABLE wp_pcguten_classes (
    id int(11) NOT NULL AUTO_INCREMENT,
    name varchar(255) NOT NULL,
    type enum('imported','scanned','gutenberg') NOT NULL,
    created_at datetime DEFAULT CURRENT_TIMESTAMP,
    updated_at datetime DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
    PRIMARY KEY (id),
    UNIQUE KEY name_type (name, type),
    KEY idx_type (type),
    KEY idx_name (name)
);

Scan Paths Table

CREATE TABLE wp_pcguten_scan_paths (
    id int(11) NOT NULL AUTO_INCREMENT,
    path text NOT NULL,
    type enum('file','directory') NOT NULL,
    enabled tinyint(1) DEFAULT 1,
    created_at datetime DEFAULT CURRENT_TIMESTAMP,
    PRIMARY KEY (id),
    KEY idx_enabled (enabled)
);

📋 Error Handling

Common Error Codes

Code	Description	Solution
`PCG_001`	Invalid license	Activate valid license
`PCG_002`	Insufficient permissions	Check user capabilities
`PCG_003`	Database error	Check database connection
`PCG_004`	File not found	Verify file paths
`PCG_005`	Scan timeout	Reduce scan scope
`PCG_006`	Memory limit exceeded	Increase PHP memory
`PCG_007`	Invalid class format	Check class name format

Error Response Format

{
  "success": false,
  "code": "PCG_003",
  "message": "Database connection failed",
  "data": {
    "error_details": "...",
    "suggested_action": "Check database configuration"
  }
}

🔐 Security Considerations

Input Validation

// Always validate and sanitize input
$class_name = sanitize_html_class($_POST['class_name']);
$file_path = sanitize_text_field($_POST['file_path']);

// Validate file paths
if (!$this->isAllowedPath($file_path)) {
    wp_die('Invalid file path');
}

Capability Checks

// Check user permissions
if (!current_user_can('manage_options')) {
    wp_die('Insufficient permissions');
}

// Check nonce for AJAX requests
check_ajax_referer('pcguten-nonce', 'nonce');

File Access Control

// Validate file access
private function isAllowedPath($path) {
    $allowed_dirs = [
        ABSPATH . 'wp-content/themes/',
        ABSPATH . 'wp-content/plugins/',
        // Add other allowed directories
    ];

    foreach ($allowed_dirs as $dir) {
        if (strpos(realpath($path), realpath($dir)) === 0) {
            return true;
        }
    }

    return false;
}

📊 Performance Guidelines

Best Practices

Batch Operations: Process multiple classes at once
Caching: Use transients for expensive operations
Async Processing: Use WordPress cron for heavy tasks
Memory Management: Monitor memory usage during scans
Database Optimization: Use proper indexes and queries

Monitoring

// Performance monitoring
add_action('pcguten_after_scan', function($classes, $paths) {
    $memory = memory_get_peak_usage(true);
    $time = microtime(true) - $start_time;

    error_log("PCG Scan: {$memory} bytes, {$time}s");
});

🌐 REST API Endpoints

Authentication

Base URL

📊 Class Management Endpoints

Get All Classes

Add Classes

Delete Class

Delete All Classes

🔍 File Scanning Endpoints

Get Scan Paths

Add Scan Path

Clear Scan Paths

Start File Scan

🎛️ Settings Endpoints

Get Assistant Settings

Update Settings

🔧 PHP Hooks & Filters

Action Hooks

Plugin Initialization

Class Management

File Scanning

Filter Hooks

Core Configuration

Class Processing

File Scanning

UI Customization

🎯 JavaScript APIs

Global Objects

Window.PlainClasses

PCGUTEN_assistant

Frontend Assistant API

Element Selection

Class Management

Assistant Control

Block Editor Integration

Autocomplete API

Block Enhancement

🛠️ Custom Development

Creating Extensions

Plugin Structure

Custom Class Sources

Database Schema

Classes Table

Scan Paths Table

📋 Error Handling

Common Error Codes

Error Response Format

🔐 Security Considerations

Input Validation

Capability Checks

File Access Control

📊 Performance Guidelines

Best Practices

Monitoring

On this page