The Themosis framework application structure is now following most of the Laravel framework one, at least on its root directory.
WordPress is defined as a dependency and installed on its own
htdocs/cms public sub-directory.
Just like previous versions of the Themosis framework, you can still develop your custom theme for the front-end/user facing content and custom plugins in order to extend WordPress and its administration.
However we have brought a new central
app directory to the stack to help you better manage your code.
On this guide, we'd like to give you some details about the choices made for the directory structure and give you some development recommendations for your custom WordPress application. But of course, you're free to organize your application however you like.
When opening your application in your code editor or IDE, you should find the following files and directories:
+-- app/ | +-- Console | +-- Exceptions | +-- Forms | +-- Hooks | +-- Http | +-- Controllers | +-- Mail | +-- Providers | +-- Widgets +-- bootstrap/ +-- config/ | +-- app.php | +-- ... | +-- wordpress.php +-- database/ +-- htdocs/ | +-- cms/ | +-- content/ | +-- index.php | +-- wp-config.php +-- resources/ | +-- languages/ | +-- views/ +-- routes/ | +-- console.php | +-- web.php +-- storage/ +-- tests/ +-- vendor/ +-- .env +-- composer.json +-- console +-- wp-cli.yml
The biggest change to the directory structure is the adoption of the
app directory in order to develop your application.
app directory stores all your classes in order to extend or customize your application. More about the app folder below.
bootstrap directory contains the
app.php file which bootstraps the application. It also holds a
cache directory containing generated files by the framework and Laravel packages.
config directory contains all the global or shared configurations for your application.
database directory stores your migration and seeder files.
htdocs directory is your web server public directory.
resources directory stores your shared views as well as language translations files.
routes directory holds your application routes.
storage directory stores framework temporary files, logs, sessions, and any custom files your application need to handle out of the public folder.
tests directory stores all your unit tests.
vendor directory is created by Composer and holds all your application dependencies.
This is not a "best practice" chapter but some explanations on the changes made to the structure of the Themosis framework.
Like for every modern framework, it starts by defining routes. On the previous versions of the Themosis framework, a
routes.php file was defined into the
resources directory of the theme. From that file, you list all routes for your application.
Since release 2.0 of the Themosis framework, we decided to move the routes file, just like in Laravel, to the application
routes directory instead. This change avoid the mix of routes definitions between the file stored in your theme and any other routes file stored in your custom plugin.
From now on, all routes for your application should be defined into the
routes/web.php file stored at project root.
The new plugin structure provides a
routes.php file at plugin root in order to let you define custom routes. This is still useful, especially if your intention is to share code across multiple projects.
The new theme structure mainly handles front-end assets and views of your application.
Just like any classic WordPress theme is doing, the new theme provided by the Themosis framework, is to simply render the content of your application - the HTML. For this, we have moved the
views directory at theme root and provided default view files based on the Underscore - _S theme.
If you feel like you need to customize your application by changing something into the WordPress administration, providing some shared utilities or simply adding some logic, we suggest you to put it into the new
app directory located at project root, or develop a custom plugin or a custom PHP package.
Please read the theme guide for more details.
You could provide views for your entire application through the
resources/views directory located at application root. However we recommend to use it for shared views or views used to customize the WordPress administration.
In order to extend WordPress, the Themosis framework provides a new mechanism based on Hookable classes. Those classes allow you to extend WordPress and provides a
register() method, just like Service Providers.
When using Hookable classes, you have access to all WordPress functions and APIs. Those classes are stored in the
By default, the framework contains 3 Hookable classes responsible to modify the behavior of WordPress, load core assets to the WordPress administration and register WordPress widgets:
If you provide features that do not need WordPress functions or classes, please use a Service Provider. Read the Service Provider guide for more information.
Please read the Hook guide to learn more about the new Hookable API.
As mentioned earlier, the Themosis framework now provides a unique and central
app directory where you can store your application code.
app directory is where you store your application controllers, models, commands, forms, hooks, widgets and any other classes your application might need to work. The directory is namespaced under
App and is autoloaded by Composer using the PSR-4 autoloading standard.
app directory contains many sub-directories that are added when you're using the
make command from the Console CLI tool provided by the framework.
However here is a list of the default subdirectories you may find under the
Console directory contains all of the custom Console commands for your application. These commands may be generated using the
make:command command. This directory also houses your console kernel, which is where your custom Console commands are registered and your scheduled tasks are defined.
Exceptions directory contains your application's exception handler and is also a good place to place any exceptions thrown by your application. If you would like to customize how your exceptions are logged or rendered, you should modify the
Handler class in this directory.
Forms directory contains the custom forms of your application. Please read the form guide for more information.
Hooks directory contains all hookable classes used to customize or extend WordPress. Please read the hook guide for more information.
Http directory contains your controllers, middleware (and form requests). Almost all of the logic to handle requests entering your application will be placed in this directory.
This directory does not exist by default, but will be created for you if you execute the
make:mail Console command. The
Providers directory contains all of the service providers for your application. Service providers bootstrap your application by binding services in the service container, registering events, or performing any other tasks to prepare your application for incoming requests.
In a fresh Themosis application, this directory will already contain several providers. You are free to add your own providers to this directory as needed.
Widgets directory contains all of your WordPress widgets. You can create a new widget by using the
make:widget Console command and then register it within the
Widgets hookable class.
Read the routing guide
Made in Belgium