Architecture

How Styble Pro is put together: a dual JavaScript + PHP block system with auto-registration, dynamic rendering, and server-side CSS generation.

Styble Pro is a WordPress Gutenberg blocks plugin built on a hybrid architecture. Every block is defined twice — once in JavaScript (for the editor experience) and once in PHP (for registration and, when needed, server-side rendering). This page gives you the mental model and points you to the deeper developer guides.

Two sides of every block

Side	Lives in	Responsibility
JavaScript	src/blocks/<block-name>/	Editor UI (edit.jsx), save markup (save.jsx), block registration (index.js), inspector controls, and dynamic editor CSS.
PHP	blocks/Types/<Block_Name>/	Server-side registration, attribute definitions (attributes.php), and render_block() for dynamic blocks.

Static blocks save their own markup in save.jsx and need no PHP rendering. Dynamic blocks return null from save.jsx and produce their HTML in PHP via render_block().

Directory map

styble-pro/
├── styble-pro.php                 # Main plugin file, defines constants, boots Block_Init
├── composer.json                  # PSR-4 autoload: ShapedPlugin\StyblePro\ → blocks/
├── webpack.config.js              # Build config + JS path aliases
├── gulpfile.js                    # Standalone SCSS compilation
│
├── src/                           # JavaScript source (built with @wordpress/scripts)
│   ├── blocks/                    # One folder per block (index.js, edit.jsx, save.jsx, …)
│   │   └── index.js               # Imports + registers every block for the editor
│   ├── admin/                     # React admin dashboard
│   ├── components/                # Shared React components
│   ├── controls/                  # Inspector controls + constants
│   ├── hooks/                     # Reusable hooks (e.g. useApiData)
│   ├── global-settings/           # Global settings store + sidebar
│   └── icons/                     # Block + category icons
│
└── blocks/                        # PHP root — PSR-4 base (ShapedPlugin\StyblePro\)
    ├── Block_Init.php             # Core bootstrap class
    ├── Types/                     # One folder per PHP block (class + attributes.php)
    ├── Includes/                  # Core engine
    │   ├── AbstractBlock.php      # Base class for every PHP block
    │   ├── Blocks_Register.php    # Auto-registers blocks by scanning Types/
    │   ├── Blocks_Query.php       # AJAX query endpoints
    │   ├── PostQueryHandler.php   # WP_Query construction
    │   ├── AssetManager.php       # Script/style registration & enqueueing
    │   ├── Styles/                # Per-block dynamic CSS classes
    │   └── Utils/                 # DynamicCssGenerator, Css_Helpers, Transient_Registry…
    ├── Attributes/
    │   └── CommonAttributes.php   # Attributes shared by all blocks
    ├── assets/                    # Compiled frontend JS/CSS for blocks
    └── languages/                 # Translation files (.pot/.po/.mo)

PSR-4 autoloading

The blocks/ directory is the root of the ShapedPlugin\StyblePro\ namespace (see composer.json). A class such as ShapedPlugin\StyblePro\Includes\AbstractBlock maps to blocks/Includes/AbstractBlock.php. The constant SP_STYBLE_PATH (defined in styble-pro.php) also points to blocks/.

Registration flow

Everything starts in styble-pro.php, which defines plugin constants and instantiates Block_Init.

styble-pro.php
   └─ Block_Init::instance()              blocks/Block_Init.php
        └─ init_styble_blocks()
             ├─ Blocks_Register::instance()    blocks/Includes/Blocks_Register.php
             │     └─ scans blocks/Types/ → instantiates each block class
             │            └─ new <Block> extends AbstractBlock
             │                   ├─ set_block_properties()   (block sets its slug etc.)
             │                   ├─ load_attributes()        (merges Common + per-block)
             │                   └─ register_block()         → register_block_type()
             ├─ Blocks_Query::instance()       (AJAX endpoints)
             ├─ Block_Dynamic_Style::instance()(dynamic CSS engine)
             └─ AssetManager::instance()       (editor/frontend/dashboard assets)

The key moving parts:

1. Block_Init (blocks/Block_Init.php) wires up registration, queries, dynamic styles, assets, the text domain, and cache clearing on save_post / deleted_post.
2. Blocks_Register (blocks/Includes/Blocks_Register.php) scans the blocks/Types/ directory, converts each folder name to StudlyCase, and instantiates the matching class \ShapedPlugin\StyblePro\Types\<Name>\<Name>.
3. AbstractBlock (blocks/Includes/AbstractBlock.php) is the base class. Its constructor calls set_block_properties(), load_attributes(), and register_block() in sequence, ending with a call to WordPress' register_block_type().

On the JavaScript side, src/blocks/index.js imports each block folder, which in turn calls a small wrapper (registerStybleBlock) around registerBlockType() to register the block in the editor.

Where to go next

Guide	What it covers
Creating a Custom Block	Building a block end to end — JS files and the PHP class.
Attributes System	CommonAttributes, per-block attributes.php, and the merge flow.
Dynamic CSS Generation	DynamicCssGenerator, Css_Helpers, per-block style classes, and caching.
Query & AJAX	Blocks_Query, PostQueryHandler, transient caching, and the useApiData hook.
Hooks & Internationalization	Filters, actions, and the styble-pro text domain.
Build & Assets	npm/gulp/webpack workflow and AssetManager.

For the end-user perspective on individual blocks, see the User Docs.