Kaiso provides a barebones structure for building controller/view-powered WordPress themes.
It attempts to automatically route a WordPress request to a controller named to match the template you'd like to load. In effect, Kaiso turns the template hierarchy into a router.
You might be interested in the example project, demonstrating how Kaiso works in context.
Kaiso is intended for use within an "app-style" WordPress instance. Our TomodomoCo/starter-wp framework is a good starting point. It's assumed you're using Composer.
Step 1
Add this GitHub repo to your repositories
block in Composer, add "tomodomoco/kaiso": "dev-master"
to your require block, and hit composer update
. The example setup also requires Twig, so install that too ("twig/twig": "^2.0"
if you're on PHP7+) if you want to use the examples.
Step 2
Copy the theme in the example/theme
folder to your wp-content/themes
directory (or wherever you place themes in your install).
Step 3
Update the settings in the theme's index.php
file, so the controllerPath
matches your namespaced path to your controllers. (If you aren't autoloading your controllers, you should do that.)
Step 4
Copy (and maybe modify) the controllers in example/controllers/
and the views in example/views/
; an app/
folder in your project root is a good spot for them!
Step 5
Activate the theme.
Step 6
Load your site. You should see "Hello world!"
Wait, what?
That's an excellent question! Kaiso makes it easier to structure a WordPress project with real controllers and views via a modern template engine. It's probably not a solution for self-contained themes: it's best for projects where the theme and the functionality are intrinsically tied (for contexts where your WordPress site starts to look more like a powerful web app).
I don't understand.
That's okay! If you are confused, Kaiso might not be right for you. There's nothing wrong with the way things work within WordPress; this just offers another option.
Is it compatible with Plugin X?
Probably not. I mean, maybe. Yes?
Kaiso is sort of agnostic to plugins and themes. As far as I can tell, if you still output the right functions in the right places in your template layer, you should still have full compatibility with most plugins. I haven't tested it in detail with any plugins, but you're probably okay if you do everything else right.
Should I use it in production?
Probably not.
Does Kaiso let me add arbitrary routes?
Not at this point, and possibly never. If that's a critical need for your project, our starter-slimwp approach might be a good option.
Can I use custom page templates with your implicit "routing" system?
Yes, although it requires a hacky static method approach that we're generally uncomfortable with. So it goes.
\Tomodomo\Kaiso::registerTemplates([
[
'name' => 'Wide Page',
'slug' => 'wide',
'postTypes' => [
'page',
],
],
]);
The above code would register a custom page template, which would map to the controller \Your\Controller\Path\WideTemplateController
.
Some tips:
Template
to the controller name; don't do it yourself.page
, post
, any custom-post-type
, archive
, etc.) or the load order might get confusing.Kaiso is essentially a router that uses the WordPress Template Hierarchy to determine which controller to load.
Instead of a full WordPress theme, we have a single index.php
file (the final fallback in the hierarchy). That file loads up a small app, which:
global $wp_query;
to the container$wp_query
index.php
file)$controller->any()
If this is available in the controller class, it will always be run$controller->get()
, ->post()
, ->put()
, etc. If ->any()
isn't available, it will load a method corresponding to the value of $_SERVER['REQUEST']
In the future, the method names may be customisable and/or mappable.
Kaiso is designed to be intentionally lightweight, and can be built into most configurations. Here's what's not current possible, or isn't in Kaiso's mission:
return
your string and set headers with header()
.
method(Request $request, $response, $args)
. $request
is a PSR7 compatible Request object, $response
is null (for purposes of forward compatibility; this will eventually be a real PSR7 Response object), and $args
consists of parsed query parameters.Tomodomo is a creative agency for magazine publishers. We use custom design and technology to speed up your editorial workflow, engage your readers, and build sustainable subscription revenue for your business.
Learn more at tomodomo.co or email us: hello@tomodomo.co
This project is licensed under the terms of the MIT License, included in LICENSE.md
.
All open source Tomodomo projects follow a strict code of conduct, included in CODEOFCONDUCT.md
. We ask that all contributors adhere to the standards and guidelines in that document.
Thank you!