Spaces:

Daviddolor
/

instatic-cms

Sleeping

File size: 10,682 Bytes

407171a

# WordPress Developer Markdown Brain
> Used by AI pipeline to plan, generate, and validate WordPress themes, plugins, REST API integrations.

---

## WordPress REST API

### Base URL
```
https://yoursite.com/wp-json/wp/v2/
```

### Core Endpoints
| Resource | GET | POST | PUT | DELETE |
|----------|-----|------|-----|--------|
| Posts | `/posts` | `/posts` | `/posts/{id}` | `/posts/{id}` |
| Pages | `/pages` | `/pages` | `/pages/{id}` | `/pages/{id}` |
| Media | `/media` | `/media` | `/media/{id}` | `/media/{id}` |
| Users | `/users` | `/users` | `/users/{id}` | `/users/{id}` |
| Categories | `/categories` | `/categories` | — | — |
| Tags | `/tags` | `/tags` | — | — |
| Comments | `/comments` | `/comments` | `/comments/{id}` | `/comments/{id}` |
| Menus | `/menus` | — | — | — |

### Authentication
```http
# Application Password (WP 5.6+)
Authorization: Basic base64(username:app_password)

# JWT Plugin
Authorization: Bearer <jwt_token>

# Cookie + Nonce (frontend)
X-WP-Nonce: {nonce}
```

### Query Parameters
```
?per_page=10        # items per page (max 100)
?page=2             # pagination
?search=keyword     # full-text search
?status=publish     # draft | publish | pending | private
?categories=1,2     # filter by category IDs
?tags=3,4           # filter by tag IDs
?author=1           # filter by author ID
?orderby=date       # date | title | id | slug | modified
?order=desc         # asc | desc
?_embed=true        # include embedded resources
?_fields=id,title   # return only specific fields
```

### Create Post (POST /posts)
```json
{
  "title": "My Post Title",
  "content": "<p>HTML content here</p>",
  "excerpt": "Short summary",
  "status": "publish",
  "categories": [1, 2],
  "tags": [3],
  "featured_media": 42,
  "slug": "my-post-title",
  "meta": {
    "custom_field": "value"
  }
}
```

### Response Shape
```json
{
  "id": 1,
  "date": "2024-01-01T00:00:00",
  "slug": "post-slug",
  "status": "publish",
  "title": { "rendered": "Post Title" },
  "content": { "rendered": "<p>...</p>", "protected": false },
  "excerpt": { "rendered": "<p>...</p>" },
  "author": 1,
  "featured_media": 0,
  "categories": [1],
  "tags": [],
  "_links": { "self": [{"href": "..."}] }
}
```

---

## WordPress Theme Structure

```
my-theme/
├── style.css              # Theme header + base styles
├── index.php              # Main template fallback
├── functions.php          # Theme setup, hooks, enqueue scripts
├── header.php             # <head> + nav
├── footer.php             # closing tags + scripts
├── sidebar.php            # widget areas
├── single.php             # single post
├── page.php               # static page
├── archive.php            # archive (category/tag/date)
├── search.php             # search results
├── 404.php                # not found
├── front-page.php         # homepage (if static front page)
├── home.php               # blog index
├── functions/
│   ├── enqueue.php        # wp_enqueue_scripts
│   ├── setup.php          # add_theme_support
│   ├── widgets.php        # register_sidebar
│   └── custom-post-types.php
├── template-parts/
│   ├── content.php
│   ├── content-single.php
│   └── content-none.php
├── inc/
│   └── customizer.php
├── assets/
│   ├── css/
│   ├── js/
│   └── images/
└── screenshot.png         # 1200x900 theme preview
```

### style.css Header (Required)
```css
/*
Theme Name: My Theme
Theme URI: https://example.com
Author: Dolor David Prince
Author URI: https://dolor3v.com
Description: A custom WordPress theme
Version: 1.0.0
License: GNU GPL v2
License URI: https://www.gnu.org/licenses/gpl-2.0.html
Text Domain: my-theme
Tags: custom, responsive, blog
*/
```

### functions.php Essential Pattern
```php
<?php
// Theme setup
function mytheme_setup() {
    add_theme_support('title-tag');
    add_theme_support('post-thumbnails');
    add_theme_support('html5', ['search-form', 'comment-form', 'gallery']);
    add_theme_support('custom-logo');
    add_theme_support('customize-selective-refresh-widgets');
    
    register_nav_menus([
        'primary' => __('Primary Menu', 'my-theme'),
        'footer'  => __('Footer Menu', 'my-theme'),
    ]);
    
    load_theme_textdomain('my-theme', get_template_directory() . '/languages');
}
add_action('after_setup_theme', 'mytheme_setup');

// Enqueue scripts and styles
function mytheme_scripts() {
    wp_enqueue_style('mytheme-style', get_stylesheet_uri(), [], '1.0.0');
    wp_enqueue_style('mytheme-main', get_template_directory_uri() . '/assets/css/main.css', [], '1.0.0');
    wp_enqueue_script('mytheme-main', get_template_directory_uri() . '/assets/js/main.js', ['jquery'], '1.0.0', true);
    
    // Pass data to JS
    wp_localize_script('mytheme-main', 'mythemeData', [
        'ajaxUrl' => admin_url('admin-ajax.php'),
        'nonce'   => wp_create_nonce('mytheme_nonce'),
        'siteUrl' => get_site_url(),
    ]);
}
add_action('wp_enqueue_scripts', 'mytheme_scripts');

// Register widget areas
function mytheme_widgets_init() {
    register_sidebar([
        'name'          => __('Main Sidebar', 'my-theme'),
        'id'            => 'sidebar-1',
        'description'   => '',
        'before_widget' => '<section id="%1$s" class="widget %2$s">',
        'after_widget'  => '</section>',
        'before_title'  => '<h2 class="widget-title">',
        'after_title'   => '</h2>',
    ]);
}
add_action('widgets_init', 'mytheme_widgets_init');
```

---

## WordPress Plugin Structure

```
my-plugin/
├── my-plugin.php          # Plugin header + bootstrap
├── readme.txt             # WordPress.org readme
├── uninstall.php          # Cleanup on delete
├── includes/
│   ├── class-plugin.php   # Main plugin class
│   ├── class-admin.php    # Admin functionality
│   ├── class-api.php      # REST API extensions
│   └── class-cpt.php      # Custom post types
├── admin/
│   ├── css/
│   ├── js/
│   └── views/
├── public/
│   ├── css/
│   ├── js/
│   └── views/
└── languages/
```

### Plugin Header
```php
<?php
/**
 * Plugin Name:       My Plugin
 * Plugin URI:        https://dolor3v.com/my-plugin
 * Description:       Plugin description here.
 * Version:           1.0.0
 * Requires at least: 5.8
 * Requires PHP:      7.4
 * Author:            Dolor David Prince
 * Author URI:        https://dolor3v.com
 * License:           GPL v2 or later
 * Text Domain:       my-plugin
 */

defined('ABSPATH') || exit;

define('MY_PLUGIN_VERSION', '1.0.0');
define('MY_PLUGIN_PATH', plugin_dir_path(__FILE__));
define('MY_PLUGIN_URL', plugin_dir_url(__FILE__));
```

### Custom Post Type
```php
function register_project_cpt() {
    register_post_type('project', [
        'labels' => [
            'name'               => 'Projects',
            'singular_name'      => 'Project',
            'add_new_item'       => 'Add New Project',
            'edit_item'          => 'Edit Project',
            'view_item'          => 'View Project',
            'search_items'       => 'Search Projects',
            'not_found'          => 'No projects found',
        ],
        'public'             => true,
        'publicly_queryable' => true,
        'show_ui'            => true,
        'show_in_rest'       => true,   // Enable REST API
        'rest_base'          => 'projects',
        'supports'           => ['title', 'editor', 'thumbnail', 'excerpt', 'custom-fields'],
        'has_archive'        => true,
        'rewrite'            => ['slug' => 'projects'],
        'menu_icon'          => 'dashicons-portfolio',
    ]);
}
add_action('init', 'register_project_cpt');
```

### Custom REST Endpoint
```php
add_action('rest_api_init', function() {
    register_rest_route('my-plugin/v1', '/data', [
        'methods'             => 'GET',
        'callback'            => 'my_plugin_get_data',
        'permission_callback' => '__return_true',
        'args' => [
            'id' => [
                'validate_callback' => fn($v) => is_numeric($v),
                'sanitize_callback' => 'absint',
            ],
        ],
    ]);
});

function my_plugin_get_data(WP_REST_Request $request) {
    $id = $request->get_param('id');
    // ... logic
    return new WP_REST_Response(['data' => $result], 200);
}
```

### Gutenberg Block (block.json)
```json
{
  "$schema": "https://schemas.wp.org/trunk/block.json",
  "apiVersion": 3,
  "name": "my-plugin/hero",
  "version": "1.0.0",
  "title": "Hero Block",
  "category": "layout",
  "description": "A hero section block",
  "supports": { "html": false, "align": ["wide", "full"] },
  "attributes": {
    "heading": { "type": "string", "default": "Hello World" },
    "subtext": { "type": "string", "default": "" },
    "backgroundColor": { "type": "string", "default": "#000" }
  },
  "editorScript": "file:./build/index.js",
  "editorStyle":  "file:./build/index.css",
  "style":        "file:./build/style-index.css"
}
```

---

## WordPress Hooks Reference

### Action Hooks
```php
add_action('init', $cb);                    // After WP loads
add_action('wp_head', $cb);                 // Inside <head>
add_action('wp_footer', $cb);               // Before </body>
add_action('save_post', $cb, 10, 3);        // Post saved
add_action('wp_enqueue_scripts', $cb);      // Enqueue assets
add_action('admin_init', $cb);              // Admin init
add_action('admin_menu', $cb);              // Register admin pages
add_action('rest_api_init', $cb);           // Register REST routes
add_action('wp_ajax_{action}', $cb);        // AJAX (logged in)
add_action('wp_ajax_nopriv_{action}', $cb); // AJAX (public)
```

### Filter Hooks
```php
add_filter('the_content', $cb);             // Post content
add_filter('the_title', $cb);               // Post title
add_filter('excerpt_length', $cb);          // Excerpt word count
add_filter('wp_nav_menu_items', $cb, 10, 2);// Nav menu items
add_filter('body_class', $cb);              // Body classes
add_filter('upload_mimes', $cb);            // Allowed file types
add_filter('rest_post_query', $cb, 10, 2);  // REST query args
```

---

## WP-CLI Commands
```bash
wp post create --post_title="Title" --post_status=publish
wp post list --post_type=page
wp user create user@example.com --role=editor
wp plugin install woocommerce --activate
wp theme activate my-theme
wp db export backup.sql
wp search-replace 'old-url.com' 'new-url.com'
wp cron event run --due-now
wp cache flush
```