API Reference

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.

🌐 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");
});