Download the PHP package kynetcode/wpzylos-scaffold without Composer

WPZylos Scaffold

Template repository for creating production-ready WordPress plugins with MVC architecture and PHP-Scoper namespace isolation.

📖 Full Documentation | 🐛 Report Issues

✨ Features

• Complete MVC Structure — Controllers, Services, Views, Routes
• PSR-4 Autoloading — Modern PHP namespace organization
• PHP-Scoper Ready — Pre-configured namespace isolation for multi-plugin compatibility
• Service Providers — Modular dependency injection
• Database Migrations — Version-controlled schema changes
• WordPress Compliant — Proper headers, MIT license, readme.txt
• Intelligent CLI — Version prompting, smart file discovery, auto-versioning
• Build Pipeline — Scaffold CLI with QA checks and ZIP creation
• Security First — Nonce verification, capability checks, input sanitization
• DaisyUI v5 + Tailwind v4 — Modern CSS framework with scoped prefix
• Vue.js 3 (Options API) — Reactive admin UI components out of the box
• React 19 (Opt-in) — Swap to React with a single config change
• Vite Build System — npm run dev (HMR) / npm run build (production)
• Dark Mode Toggle — DaisyUI theme switching ready
• Shortcode Support — Example shortcode with Vue/React mount point

📋 Requirements

🚀 Quick Start

Option 1: Use as GitHub Template

Click "Use this template" on GitHub to create a new repository.

Option 2: Composer Create Project

Option 3: Clone and Customize

Initialize Your Plugin (Recommended)

After creating your project, run the Scaffold CLI to customize and manage your plugin.

Option 1: PowerShell (Windows 10/11)

Open Windows PowerShell (search "PowerShell" in Start menu):

Option 2: Command Prompt (Windows)

Open Command Prompt (cmd.exe). Since .ps1 files don't run directly in cmd, use:

Option 3: Bash (Linux/Mac/Git Bash)

For Linux, macOS, or Git Bash on Windows (install Git for Windows):

Git Bash alternative: If ./scaffold.sh doesn't work, try bash scaffold.sh

The intelligent init script handles all scenarios:

Features:

• Version Prompting: Sets initial version and updates plugin header + PluginContext
• Namespace support: Supports nested namespaces like WPDigger\WPBraCalculator
• Config-aware defaults: Reuses existing .plugin-config.json values for identity, build include lists, CSS prefix, and integrity update settings.
• Canonical bootstrap: Main plugin and uninstall entrypoints use PluginContext::forPluginFile(__FILE__) and delegate lifecycle work to app/Core/Plugin.php.

📁 Project Structure

🔧 Customization

Automated (Recommended)

Run the Scaffold CLI for automated setup:

PowerShell:

Command Prompt:

Linux/Mac/Git Bash:

Manual

If you prefer manual customization, perform search and replace:

Files to Update

1. your-plugin.php — Plugin headers, PluginContext configuration
2. composer.json — Package name, namespace in autoload
3. scoper.inc.php — Scoper prefix variable
4. .plugin-config.json — Created by init, used by build
5. uninstall.php — Context configuration

🏗️ Core Components

PluginContext

The PluginContext class (app/Core/PluginContext.php) is the single source of truth for plugin identity. All framework components use this for prefixing.

Available Methods:

Helper Functions

Global helpers available after bootstrap (app/Support/helpers.php):

⚙️ Configuration

config/app.php

Service Providers

The bootstrap (bootstrap/app.php) registers framework service providers in dependency order:

1. ConfigServiceProvider — Configuration and .env loading
2. I18nServiceProvider — Internationalization
3. HookServiceProvider — WordPress hook management
4. SecurityServiceProvider — Nonce, Gate, Sanitizer
5. HttpServiceProvider — Request, Response, Pipeline
6. ValidationServiceProvider — Input validation
7. ViewsServiceProvider — Template rendering
8. DatabaseServiceProvider — Database connection
9. MigrationsServiceProvider — Schema migrations
10. RoutingServiceProvider — URL routing
11. WpCliServiceProvider — WP-CLI commands (when available)

🛤️ Routing

Define routes in routes/web.php:

🎨 Frontend Build Pipeline

The scaffold includes a modern frontend stack powered by Vite, DaisyUI v5, and Tailwind CSS v4.

Install Dependencies

Development (HMR)

Starts Vite dev server with Hot Module Replacement. Define WPZYLOS_VITE_DEV in wp-config.php to load dev assets:

Production Build

Outputs optimized assets to dist/ with a manifest for ViteAssetResolver.

Switching Between Vue and React

The scaffold ships with Vue.js 3 (Options API) by default. To switch to React 19:

1. In vite.config.js, comment out vue() and uncomment react()
2. Update your admin entry point to import AdminApp.jsx instead of AdminApp.vue

CSS Prefix Derivation

The init scripts automatically derive a DaisyUI CSS prefix from your plugin slug (e.g., my-plugin → mp-). This prevents CSS collisions when multiple WPZylos plugins run on the same site.

The scaffold ships with PHP/Twig view support through wpzylos-views. Blade template examples are intentionally not included because the views package does not provide a Blade engine.

Shortcode Example

The scaffold includes a shortcode example that mounts a Vue/React component on the frontend via JsMount::shortcodeMount().

🔨 Build & Release

Development

Production Build

Use the Scaffold CLI for production builds:

Windows (PowerShell):

Windows (Command Prompt):

Linux/Mac (or Git Bash):

The build script will:

1. Clean previous build artifacts
2. Run phpcbf --standard=PSR12 (code style fix)
3. Run phpstan analyze (static analysis)
4. Install production dependencies
5. Run PHP-Scoper for namespace isolation
6. Copy required files & rebuild autoloader
7. Remove development files
8. Create versioned ZIP in dist/

Note: The build script reads configuration from .plugin-config.json (created by scaffold init).

Intelligent Features:

• Smart File Discovery: Automatically detects project files/folders and prompts for unknown items
• Preference Persistence: Saves your include/exclude choices for future builds
• Auto-Versioning: Suggests next patch version based on existing ZIP files in dist/
• Artifact Preservation: Preserves the dist/ directory with previous builds

The production build creates a zip file at dist/your-plugin-1.0.0.zip ready for deployment.

PHP-Scoper

The scaffold includes pre-configured PHP-Scoper (scoper.inc.php) that:

• Prefixes all vendor namespaces for multi-plugin isolation
• Excludes WordPress core functions, classes, and constants
• Excludes your plugin's namespace
• Generates unique build prefixes using git hash

🧪 Testing

Tests are located in tests/Unit/. The test bootstrap is at tests/bootstrap.php.

🔒 Security

The scaffold implements WordPress security best practices:

• Nonce verification in form submissions
• Capability checks for user permissions
• Prepared statements for database queries
• Output escaping with proper functions
• Input sanitization before processing

See the Security Package for detailed security utilities.

🐛 Troubleshooting

Composer create-project fails

Namespace/autoloader issues

Verify composer.json PSR-4 namespace matches your class namespace.

PHP-Scoper errors

Check scoper.inc.php and ensure WordPress functions are excluded.

Built plugin crashes

Verify WordPress symbols are excluded in scoper configuration.

📦 Related Packages

📖 Documentation

For comprehensive documentation, tutorials, and API reference, visit wpzylos.com.

☕ Support the Project

If you find this scaffold helpful, consider supporting the WPZylos ecosystem!

• GitHub Sponsors
• PayPal Donate

📄 License

This project is licensed under the MIT License. See LICENSE for details.

🤝 Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

Made with ❤️ by KYNetCode