Kick start your Disciple.Tools plugin project with this template!
This plugin is a modern opinionated extension starter template inspired by Laravel.
Tip: You can safely delete this README.md file and replace it with your own. You can always view this readme at github.com/thecodezone/dt-home.
At CodeZone, we recognize a developer or team might love Disciple.Tools, but miss the modern tooling found in PHP Application frameworks.
There growing community of Laravel and Symfony developers who bring exceptional expertise to the table.
Our purpose is to bridge the gap between these seasoned developers and the dynamic environment of Disciple.Tools. We strive to make Disciple.Tools plugin development not only accessible but also a delightful experience for those already well-versed in Laravel and Symfony frameworks.
Are you a WordPress developer? You may feel more at home using the Disciple Tools Starter Template.
- WordPress code style requirements.
phpcs.xml
- PHP Code Sniffer support (composer) @use
/vendor/bin/phpcs
and/vendor/bin/phpcbf
- GitHub Actions Continuous Integration
.githbub/workflows/ci.yml
- Disciple.Tools Theme presence check.
\DT\Home\plugin()->is_dt_theme();
- Remote upgrade system for ongoing updates outside the Wordpress Directory.
- Multilingual support.
/languages
&default.pot
- Composer support.
composer.json
- Scoped dependency autoloading using PHPScoper.
/composer.scoped.json
- Laravel-style service providers.
/src/Providers
- Laravel-style controllers.
/src/Controllers
- Vite build system.
/vite.config.js
&/resources/js
- Inversion of control container
using Laravel's Service Container.
/src/Container.php
- Routing system using FastRoute.
/routes/web/routes.php
- View layouts, partials, and escaping provided by the plain PHP templating engine, Plates.
- Sample admin menu and admin page with starter tabs component.
- Sample custom post type.
- Sample REST api.
- Sample magic link.
Tip: This starter plugin does not attempt to provide every component provided by the Disciple Tools Starter Template. See the Disciple Tools Starter Template for implementation examples of charts, tiles and other components.
- Clone this repository.
- Remove the .git folder and initialize a new git repository.
- Edit the
.rename.sh
updating each variable to match your plugin. - Run
./.rename.sh
- Edit
composer.json
to update thename
,description
, andauthor
fields. - Edit
package.json
to update thename
anddescription
fields. - Edit
version-control.json
with your plugin information. - Run
composer install
to install PHP dependencies. - Run
npm install
to install JS dependencies. - Run
npm run dev
to compile assets for development. - Commit and push your changes a new github repository.
- Open the WordPress admin and activate your plugin.
This plugin uses Composer to manage dependencies. The plugin's dependencies are scoped to
your plugin's namespace. This means you can use any package you want without worrying about conflicts with other
plugins. For example, if you want to use the Guzzle HTTP client, you can simply
add it to your composer.scoped.json
file, instead of the composer.json
file.
Guzzle would then be installed in the vendor-scoped
directory, instead of the vendor
directory. This allows you to
use Guzzle without worrying about conflicts with other plugins that may also use Guzzle.
See PHPScoper for more information.
WordPress's Internationalization functionality and Weblate via translate.disciple.tools are used to provide multilingual support.
Hard-coded strings should be wrapped in the __()
function. For example:
__( 'Hello World!', 'dt_home' );
Service providers are used to register services into the
plugin's inversion of control container or with
Disciple.Tools. Service providers are located in the src/Providers
directory. The register()
method is called when
the plugin is first loaded. The boot()
method is called after the theme have been loaded.
Register new service providers in /src/Providers/PluginServiceProvider.php
.
namespace DT\Home\Providers;
use DT\Home\Plugin;
class ExampleServiceProvider extends ServiceProvider
{
/**
* Called when the plugin is first loaded.
*
* @return void
*/
public function register()
{
// Register a service into the plugin's container.
$this->container->bind( 'example', function () {
return new Example();
} );
add_filter( 'some/filter', function () {
//some filter
});
}
/**
* Called when the theme is loaded.
*
* @return void
*/
public function boot()
{
add_action( 'some/action', function () {
//Some action
});
}
}
Routing is handled by FastRoute. Routes are located in the routes/web
directory.
The routes.php
file is loaded when the plugin is first loaded. Separate route files can be loaded using the Router.php
service.
Custom route files can be registered when loading routes in specific hook or in magic links. For example:
$router = app()->container->make( /DT/Plugin/Services/Router::class );
$router->from_file( 'web/custom-routes-file.php' )->make();
The query string is not used when matching routes. Do allow &action=some-page or &page=some-page to be used as a route, you can specify a query parameter to use when matching routes.
$router = app()->container->make( /DT/Plugin/Services/Router::class );
$router->from_file( 'web/custom-routes-file.php', [
'param' => 'page',
] )->make();
See fast route documentation for more information
on defining routes. To map a route to a controller, use the @
symbol after the controller class name followed by the method name.
use DT\Home\Controllers\HelloController;
$r->get( 'dt/Home/hello', HelloController::class . '@show' );
The plugin uses WP REST API to provide REST routes. Routes are located in
the routes routes/admin
directory.
{
"require": {
"guzzlehttp/guzzle": "^7.0"
}
}
Controllers are located in the src/Controllers
directory. Controllers are responsible for handling requests and
returning responses. Controllers are basic PHP classes with no parent class or base controller. Controllers are resolved
from the container using the controller's fully qualified class name. Controllers can be resolved from the container to
make use of automatic dependency injection.
Tip: Keep your controllers thin. Business logic should be moved to services. Controllers should only be responsible for handling requests and returning responses. Anything more than basic logic should be moved to a service.
Templating is provided by the plain PHP templating engine, Plates.
The template service located at src/Services/Template.php
is used to bootstrap a blank template for your plugin.
Routes are mapped to controllers which load basic PHP templates from the resources/views
directory.
Tip: Be sure to use WordPress escaping functions when outputting data in your templates. See Data Validation for more information.
use DT\Home\view;
\template( 'hello', [
'name' => 'World',
] );
use DT\Home\view;
\view( 'hello', [
'name' => 'World',
] );
A basic user-based magic link is provided. See
the DT starter plugin template
for more examples, like contact and object magic links. To utilize magic links, you must first uncomment the magic link
service provider in the providers
array in /src/Providers/PluginServiceProvider
.
protected $providers = [
RouteServiceProvider::class,
//PostTypeServiceProvider::class,
//AdminServiceProvider::class,
MagicLinkServiceProvider::class
];
A dt post type is included. To utilize post types, you must first uncomment the post type service provider in
the providers
array in /src/Providers/PluginServiceProvider
.
protected $providers = [
RouteServiceProvider::class,
PostTypeServiceProvider::class,
//AdminServiceProvider::class,
//MagicLinkServiceProvider::class
];
PHP_CodeSniffer (phpcs
) is used for static code analysis
and PHP_CodeSniffer Beautifier (phpcbf
)
for automatic code formatting. Before committing your code, run the following commands to check and fix coding
standards:
/vendor/bin/phpcs
/vendor/bin/phpcbf
PHP_CodeSniffer and Beautifier work best when integrated with your IDE. See PHPSTORM and VSCode for more information.
This plugin uses PHPUnit for testing. Tests are located in the test
directory.
Before running tests you must install a local version of WordPress to test against using tests/install-wp-tests.sh
.
Here is an example using ddev database credentials:
- Create an empty database for testing.
ddev mysql;
create database testing;
exit;
-
Run
ddev describe
to get your database credentials. -
Run the
tests/install-wp-tests.sh
script with your ddev database credentials.
tests/install-wp-tests.sh testing db db 127.0.0.1:32770
- Run the tests.
vendor/bin/phpunit
Note Phpunit 10.0.0 is not compatible with WP testing. PHPUnit 9 is installed as a dependency. If you would rather use your global PHPUnit, make sure to use version 9 or below.
- Disciple.Tools Theme installed on a local Wordpress Server DDEV or localwp.com.
Contributions welcome. You can report issues and bugs in the Issues section of the repo. You can present ideas in the Discussions section of the repo. And code contributions are welcome using the Pull Request system for git. For a more details on contribution see the contribution guidelines.