Installation
- Install WpStarter in the WordPress root
- Load WpStarter as a must-use plugin
- Initial configuration
- Try the supplied examples
WpStarter runs an application inside WordPress. Its framework uses Laravel-style APIs under the WpStarter namespace and integrates routing, views, authentication, database access, and mail with WordPress. These docs focus on that integration. For shared framework concepts, use the Laravel 12.x documentation.
Install WpStarter in the WordPress root
The recommended setup is to install WpStarter in a wpstarter directory at the root of your existing WordPress installation, beside wp-load.php, and load it through a must-use plugin loader.
cd /path/to/wordpress
composer create-project "wpstarter/wpstarter:2.*" wpstarterThis installs the plugin skeleton together with wpstarter/framework and its dependencies.
Use PHP 8.2 or later with the extensions required by Composer. The install scripts create .env and generate APP_KEY.
The application entrypoint is now /path/to/wordpress/wpstarter/main.php. Its CLI bootstrap searches for wp-load.php relative to the project.
Load WpStarter as a must-use plugin
Create the wp-content/mu-plugins directory if it does not exist, then create wp-content/mu-plugins/wpstarter.php with this loader:
<?php
/**
* Plugin Name: WpStarter
*/
require_once ABSPATH . 'wpstarter/main.php';WordPress automatically loads this file as a must-use plugin; no activation in the WordPress admin is needed. Keep the loader directly inside mu-plugins so WordPress discovers it. The application itself stays in the WordPress-root wpstarter directory.
The entrypoint guards against loading another copy through __WS_FILE__; plan for one WpStarter application entrypoint per WordPress installation with this skeleton.
Run application commands from the wpstarter directory:
cd /path/to/wordpress/wpstarter
php artisan listThe plugin bootstrap loads WordPress before Composer's autoloader and the application. This is different from a standalone Laravel project; do not configure the web server to use this skeleton as an independent Laravel public/index.php application.
Installing in wp-content/plugins/wpstarter and activating main.php as a regular plugin is also possible, but is not recommended. In particular, conditional plugin loading needs the must-use setup to filter regular plugins before they load.
Initial configuration
The skeleton supplies Vite configuration. See asset bundling for the entry files, Blade directive, and production build. Laravel Mix remains supported in 2.x.
Review WordPress configuration, especially:
APP_URLfor the site's URL andAPP_KEYfor encrypted cookies.APP_DEBUG=falseandAPP_DEBUG_EXTERNAL=falsefor production.- Writable
storageandbootstrap/cachedirectories. - The default
wpdbconnection, WordPress authentication guard, andwp_mailmailer. - Web-server access rules for the application directory.
The skeleton supplies Apache .htaccess files and an Nginx sample, but their protection depends on the active web-server configuration. Nginx needs explicit server rules that also account for PHP/static regex locations. Follow Security and Private Configuration for Apache and Nginx examples, deployment checks, and alternatives to .env. Requests to the WordPress site still enter through WordPress.
Try the supplied examples
The skeleton contains examples that demonstrate the three request flows:
| Example | What it demonstrates |
|---|---|
Visit /welcome relative to the WordPress site | URL action returning ws_view(); also creates the shortcode demo page if absent |
Visit the created welcome-shortcode-page | [welcome-shortcode] dispatches a shortcode route and preserves the theme |
Visit /welcome-page | URL action creates a matching WordPress page if needed and returns content_view() |
| Open the WpStarter sample admin menu | Class-based admin action dispatch, Blade layout, validation, notices, and redirects |
Add [sample-shortcode] to content | Registered shortcode component from AppServiceProvider |
The welcome controllers create published demo pages on GET requests. Remove or adapt these examples before shipping your own plugin. The sample admin page demonstrates the mechanics; review its capabilities and middleware before using it for privileged operations.
Continue with plugin structure, routing, and admin development.