Skip to content

wp-plugin-guidelines.md

Latest commit

 

History

History
354 lines (293 loc) · 9.44 KB

wp-plugin-guidelines.md

File metadata and controls

354 lines (293 loc) · 9.44 KB

WordPress Plugin Development Guidelines

Last Updated: July 10, 2025

Overview

This document outlines comprehensive WordPress plugin development guidelines for Super Forms, covering WordPress.org requirements, security best practices, code quality standards, and automated validation processes.

WordPress.org Directory Requirements

Essential Requirements

  • GPL Compatible License: Plugin must be GPL-compatible (recommended: "GPLv2 or later")
  • Human Readable Code: No obfuscation, minification, or encryption of PHP code
  • Complete Functionality: Plugin must be fully functional at submission
  • Proper Versioning: Use semantic versioning (e.g., 1.2.3)
  • Text Domain: Must match plugin directory name
  • Translation Ready: All strings must be translatable

Code Transparency Standards

  • Source code must be publicly accessible
  • No executable code loading from external sources
  • Use WordPress default libraries when possible
  • Avoid tracking users without explicit consent

Security Best Practices

Input Sanitization & Validation

// Always sanitize user input
$user_input = sanitize_text_field( $_POST['user_field'] );
$email = sanitize_email( $_POST['email'] );
$url = esc_url_raw( $_POST['url'] );

// Validate data types
$number = intval( $_POST['number'] );
$bool = (bool) $_POST['checkbox'];

Nonce Verification

// Create nonce
wp_nonce_field( 'super_forms_action', 'super_forms_nonce' );

// Verify nonce
if ( ! wp_verify_nonce( $_POST['super_forms_nonce'], 'super_forms_action' ) ) {
    wp_die( 'Security check failed' );
}

Output Escaping

// Escape output based on context
echo esc_html( $user_data );
echo esc_attr( $attribute_value );
echo esc_url( $url );
echo wp_kses_post( $content );

Capability Checks

// Always check user capabilities
if ( ! current_user_can( 'manage_options' ) ) {
    wp_die( 'Insufficient permissions' );
}

Database Security

// Use prepared statements
$wpdb->prepare( 
    "SELECT * FROM {$wpdb->prefix}super_forms WHERE id = %d", 
    $form_id 
);

Code Quality Standards

WordPress Coding Standards

  • Follow WordPress PHP Coding Standards
  • Use WordPress VIP coding standards for performance
  • Implement proper error handling
  • Use WordPress APIs instead of native PHP functions where available

File Organization

super-forms/
├── super-forms.php (main plugin file)
├── includes/
│   ├── class-super-forms.php
│   ├── class-forms-admin.php
│   └── class-forms-frontend.php
├── admin/
│   ├── css/
│   ├── js/
│   └── views/
├── public/
│   ├── css/
│   ├── js/
│   └── assets/
└── languages/

Naming Conventions

  • Functions: super_forms_function_name()
  • Classes: class Super_Forms_Class_Name
  • Constants: SUPER_FORMS_CONSTANT
  • Variables: $super_forms_variable
  • Hooks: super_forms_hook_name

Documentation Standards

/**
 * Process form submission
 *
 * @since 1.0.0
 * @param int    $form_id Form ID
 * @param array  $data    Form data
 * @return bool|WP_Error  True on success, WP_Error on failure
 */
function super_forms_process_submission( $form_id, $data ) {
    // Function implementation
}

Performance Optimization

Database Optimization

  • Use WordPress query functions (WP_Query, get_posts(), etc.)
  • Implement proper caching with transients
  • Minimize database queries
  • Use indexed database columns

Asset Loading

// Conditional asset loading
if ( is_admin() ) {
    wp_enqueue_script( 'super-forms-admin', plugin_dir_url( __FILE__ ) . 'admin/js/admin.js' );
}

// Frontend only when needed
if ( has_shortcode( $post->post_content, 'super_form' ) ) {
    wp_enqueue_script( 'super-forms-frontend', plugin_dir_url( __FILE__ ) . 'public/js/frontend.js' );
}

Caching Implementation

// Use transients for expensive operations
$cache_key = 'super_forms_' . $form_id;
$form_data = get_transient( $cache_key );

if ( false === $form_data ) {
    $form_data = expensive_form_operation( $form_id );
    set_transient( $cache_key, $form_data, 12 * HOUR_IN_SECONDS );
}

Accessibility Standards

Form Accessibility

  • Use proper ARIA labels and descriptions
  • Ensure keyboard navigation support
  • Provide error messages for screen readers
  • Use semantic HTML elements

Color and Contrast

  • Ensure sufficient color contrast ratios
  • Don't rely solely on color for information
  • Test with colorblind simulators

Internationalization (i18n)

Text Domain Implementation

// Register text domain
function super_forms_load_textdomain() {
    load_plugin_textdomain( 'super-forms', false, dirname( plugin_basename( __FILE__ ) ) . '/languages/' );
}
add_action( 'plugins_loaded', 'super_forms_load_textdomain' );

// Translatable strings
__( 'Submit Form', 'super-forms' );
_e( 'Form submitted successfully', 'super-forms' );
_n( '%s form', '%s forms', $count, 'super-forms' );

JavaScript Internationalization

// Make strings available to JavaScript
wp_localize_script( 'super-forms-js', 'superFormsL10n', array(
    'ajaxurl' => admin_url( 'admin-ajax.php' ),
    'nonce' => wp_create_nonce( 'super_forms_nonce' ),
    'strings' => array(
        'loading' => __( 'Loading...', 'super-forms' ),
        'error' => __( 'An error occurred', 'super-forms' ),
    ),
) );

Automated Validation Tools

PHPCS Integration

composer.json

{
    "require-dev": {
        "wp-coding-standards/wpcs": "^3.0",
        "phpcompatibility/php-compatibility": "^9.0",
        "phpcompatibility/phpcompatibility-wp": "^2.0"
    }
}

phpcs.xml

<?xml version="1.0"?>
<ruleset name="Super Forms">
    <description>WordPress Coding Standards for Super Forms</description>
    
    <file>.</file>
    <exclude-pattern>*/node_modules/*</exclude-pattern>
    <exclude-pattern>*/vendor/*</exclude-pattern>
    
    <rule ref="WordPress">
        <exclude name="WordPress.Files.FileName"/>
    </rule>
    
    <rule ref="WordPress.NamingConventions.PrefixAllGlobals">
        <properties>
            <property name="prefixes" type="array" value="super_forms,SUPER_FORMS"/>
        </properties>
    </rule>
</ruleset>

Plugin Check Integration

# Install Plugin Check
wp plugin install plugin-check --activate

# Run checks
wp plugin check super-forms

# Run specific checks
wp plugin check super-forms --checks=security,performance

Security Scanning

# WPScan installation
gem install wpscan

# Scan for vulnerabilities
wpscan --url http://localhost/wordpress --enumerate p --plugins-detection aggressive

Testing Requirements

Pre-Release Checklist

  • All PHP files pass PHPCS validation
  • Plugin Check returns no errors
  • Security scan shows no vulnerabilities
  • All forms render correctly on frontend
  • Admin functionality works without errors
  • JavaScript console shows no errors
  • Plugin activates/deactivates cleanly
  • Database operations complete successfully
  • Translations load correctly
  • Performance impact is minimal

Manual Testing Protocol

  1. Frontend Testing

    • Load forms on different page types
    • Test form submission process
    • Verify validation messages
    • Check responsive design

  2. Admin Testing

    • Test form creation workflow
    • Verify settings save correctly
    • Check admin notices display
    • Test import/export functionality

  3. Integration Testing

    • Test with common themes
    • Verify plugin compatibility
    • Check third-party integrations
    • Test with different PHP versions

Deployment Guidelines

Version Control

  • Use semantic versioning
  • Tag releases in Git
  • Maintain changelog
  • Document breaking changes

Release Process

  1. Run automated validation tools
  2. Complete manual testing checklist
  3. Update version numbers
  4. Generate translation files
  5. Create release package
  6. Deploy to staging environment
  7. Final testing verification
  8. Release to production

Compliance Monitoring

Regular Audits

  • Monthly security scans
  • Quarterly code quality reviews
  • Annual accessibility audits
  • Continuous performance monitoring

Documentation Updates

  • Update guidelines after WordPress core updates
  • Review security practices quarterly
  • Monitor WordPress.org policy changes
  • Update tools and dependencies regularly

Resources and Tools

Essential Tools

  • PHPCS: Code quality validation
  • Plugin Check: WordPress.org compliance
  • WPScan: Security vulnerability scanning
  • Query Monitor: Performance debugging
  • Debug Bar: Development debugging

Documentation

Emergency Procedures

Security Incident Response

  1. Immediately assess the vulnerability
  2. Develop and test a fix
  3. Notify affected users
  4. Release emergency update
  5. Document incident for future prevention

Plugin Rejection Response

  1. Review WordPress.org feedback
  2. Address all listed issues
  3. Test fixes thoroughly
  4. Resubmit with detailed changelog
  5. Monitor for approval status

This document is a living guide and should be updated as WordPress standards evolve and new tools become available.