Maintained by: The Code Company
Important
WPMVC is currently in alpha, as such there may be breaking changes introduced on our path to beta/v1.0. While we hope you will find the package useful in its current state you're using it at your own risk.
- WPMVC Example Plugin
This is an example mu-plugin demonstrating the usage of WPMVC. It's designed to be downloaded as a zip and used as the basis for your own plugin, rather than cloned or forked (especially while in alpha).
The example plugin comes with some predefined models and controllers that demonstrate some common uses for WPMVC including registering custom post types and taxonomies. Additionally, there are examples of using controllers as the basis for configuration, REST and routing.
- PHP 8.1+
- WordPress 6.4+
Please refer to requirements for WPMVC.
As mentioned above, download this project as a zip rather than cloning.
Extract the contents of the zip file into your wp-content/mu-plugins directory, for our example we will rename the extraced directory example-corp - you can use any name you'd like however you'll need to ensure the boot loader path is updated in Step 4.
Move the mu-boot-example.php file into your wp-content/mu-plugins directory, ensure the path in this file is accurate as mentioned in Step 2. You can rename mu-boot-example.php to anything you'd like.
Open the plugin directory in your terminal and run composer install, this will install WPMVC as a dependency and allow the example application to function.
composer install --ignore-platform-reqs
At this point you can log into wp-admin and verify that the mu-plugin is active and the example post type and taxonomy have been registered.
You can use these example controllers/models as the basis for your own, in the future we will be introducing a scaffolding system to generate these via the cli.
Warning
If you can't see the example post type (Movies) or taxonomy (Genres) or are receiving an error when registering the mu-plugin, ensure that the path in your boot file is accurate and that you've run composer install from Step 4.
Assuming you'll want to customise the mu-plugin and provide your own package names, namespaces etc. the first step is to perform a search/replace within the mu-plugin directory, you'll want to update all occurances of ExampleCorp with your own name e.g. MyApp.
Once you've performed this replacement, which will also update the PSR-4 autoload namespace in your composer.json file, you will need to run the following command:
composer dump-autoload
Lastly you can modify the composer.json name and description to your liking, as well as the plugin declaration comment in the boot.php file.
Controllers in WPMVC are very flexible and serve multiple purposes, from more traditional use cases such as regiering routes or REST endpoints to more WordPress-specific uses such as mounting application code into WordPress via hooks using the set_up() method. There are a number of examples provided with this plugin that you can use as the basis for your controllers which are detailed below:
ExampleConfigController.php
This example demonstrates the usage of WPMVC's configuration system. It registers a custom route that maps to a method route_example_config() which demonstrates retrieving environment-specific configuration variables.
WPMVC uses a constant WP_ENV which you can define in your wp-config.php file, you may use this to handle loading environment-specific configuration. The environment constant options the example plugin uses are local, staging and production. E.g.
define( 'WP_ENV', 'local' );
ExampleRESTController.php
The example REST controller demonstrates how to create a custom REST endpoint using the WordPress REST system. This is a simple system that mounts on the plugins_loaded hook via the set_up() method that all controllers inherit. You may use the same arguments when registering your endpoint as can be found in the WordPress codex.
ExampleRouteController.php
The example Route controller demonstrates two pieces of functionality, first the ability to register custom routes within WPMVC that you can bind to a method within your controller. The second is WPMVC's lightweight theme/templating system which can be used to create and render templates. Routes are registered within WPMVC, not as rewrite rules, this happens during the do_parse_request action.
Controllers do nothing on their own, you will need to register them within the WPMVC application via the boot.php file in your plugin root. This example plugin has a handful of pre-registered controllers that take care of the registration of the example Movie post type and Genre taxonomy - you can intialiase your new controllers within the array pictured below.
Any class instance you provide within this array will have its set_up() method called when WordPress initiliases, this is a required method and how your controller "hooks in" to WordPress.
Creating custom post types with WPMVC requires three steps, first creating a model that represents the custom post type and then creating a controller to register it with WordPress.
Custom post type models are extended from the GenericPost model, this provides some post-specific methods that can be quite useful when creating, modifying or iterating over posts within WPMVC. You can simply provide the post type name as pictured below and the rest of the configuration happens within the registration controller.
Using the RegisterMovieController example, we can see that we're using the post model from the previous step as a reference on line 23 and defining our labeling with get_label_singular(), get_label_plural() and get_post_type_args_labels() methods. This is a fairly manual process, as best practices dictate to not use variables within translation functions.
The registration itself happens within the get_register_post_type_args() method, you may use the register_post_type() docs as a reference for the arguments that get passed to WordPress via this method.
As per the "Registering a controller" section above, you must include and initialise your controller in the boot.php file.
Similarly to custom post types, creating a custom taxonomy requires three steps.
As opposed to post models, taxonomy models are extended from TaxonomyTermModel. They also require a single constant, the name of the taxonomy
This process is very similar to registering a custom post type, with two primary differences.
The get_taxonomy_object_types() method is used to define which post types this taxonomy is related to, in our example you can see the inverse relationship between Movies and Genres is defined here. You may add as many post type references to this method as you'd like.
The arguments used in the get_taxonomy_args() method are the same as the arguments used for the register_taxonomy() function.
As per the "Registering a controller" section above, you must include and initialise your controller in the boot.php file.
WPMVC is maintained by The Code Company, while we appreciate feedback and will endeavour to action requests for features/bug fixes this repository is not open to outside contribution at this time. You are, however, free to fork and use WPMVC in any way you see fit as per the ISC license.