Basic Plugin Generation and Publishing Process
Principle
- Taking the cross-domain plugin as an example, the plugin consists of three parts: one is the cross-domain middleware program file, one is the middleware configuration file
middleware.php, and the other isInstall.php, which is automatically generated by the command. - We use the command to package these three files and publish them to Composer.
- When users install the cross-domain plugin using Composer, the
Install.phpin the plugin will copy the cross-domain middleware program file and configuration file to{main_project}/config/plugin, allowing Webman to load them. This achieves the automatic configuration activation of the cross-domain middleware file. - When users remove the plugin using Composer,
Install.phpwill delete the corresponding cross-domain middleware program file and configuration file, accomplishing automatic uninstallation of the plugin.
Specification
- The plugin name consists of two parts:
vendorandplugin name, for example,webman/push, which corresponds to the Composer package name. - Plugin configuration files are uniformly placed under
config/plugin/vendor/plugin_name/(the console command will automatically create the configuration directory). If the plugin does not require configuration, the automatically created configuration directory should be deleted. - The plugin configuration directory only supports
app.phpas the main plugin configuration,bootstrap.phpfor process startup configuration,route.phpfor routing configuration,middleware.phpfor middleware configuration,process.phpfor custom process configuration,database.phpfor database configuration,redis.phpfor Redis configuration, andthinkorm.phpfor ThinkORM configuration. These configurations will be automatically recognized by Webman. - Plugins obtain configurations using the following method:
config('plugin.vendor.plugin_name.configuration_file.specific_configuration_item');, for example,config('plugin.webman.push.app.app_key'). - If the plugin has its own database configuration, it should be accessed using the following way. For
illuminate/database, useDb::connection('plugin.vendor.plugin_name.specific_connection'), forthinkorm, useDb::connct('plugin.vendor.plugin_name.specific_connection'). - If the plugin needs to place business files under the
app/directory, it must ensure there is no conflict with the user project and other plugins. - Plugins should avoid copying files or directories to the main project as much as possible. For example, the cross-domain plugin only needs to copy the configuration file to the main project; the middleware file should be placed under
vendor/webman/cros/srcand does not need to be copied to the main project. - It is recommended to use uppercase letters for the plugin namespace, for example,
Webman/Console.
Example
Install webman/console Command Line
composer require webman/console
Create Plugin
Assuming the created plugin is called foo/admin (the name is also the project name to be published later via Composer, and the name needs to be lowercase).
Run the command
php webman plugin:create --name=foo/admin
After creating the plugin, a directory vendor/foo/admin will be generated for storing plugin-related files and config/plugin/foo/admin for storing plugin-related configurations.
Note
config/plugin/foo/adminsupports the following configurations:app.phpas the main plugin configuration,bootstrap.phpfor process startup configuration,route.phpfor routing configuration,middleware.phpfor middleware configuration,process.phpfor custom process configuration,database.phpfor database configuration,redis.phpfor Redis configuration, andthinkorm.phpfor ThinkORM configuration. The configuration format is the same as Webman, and these configurations will be automatically recognized and merged by Webman.
Access withpluginas the prefix, for example,config('plugin.foo.admin.app');
Export Plugin
Once we have completed the plugin development, execute the following command to export the plugin:
php webman plugin:export --name=foo/admin
Exporting
Description
After exporting, theconfig/plugin/foo/admindirectory will be copied tovendor/foo/admin/src, and anInstall.phpwill be automatically generated. TheInstall.phpis used to perform operations during automatic installation and uninstallation.
The default operation upon installation is to copy the configurations fromvendor/foo/admin/srcto the current project'sconfig/plugindirectory.
The default operation upon removal is to delete the configuration files from the current project'sconfig/plugindirectory.
You can modifyInstall.phpto perform custom operations during plugin installation and uninstallation.
Submit Plugin
- Assume you already have a GitHub and Packagist account.
- Create an admin project on GitHub and upload the code; let's assume the project address is
https://github.com/your_username/admin. - Go to
https://github.com/your_username/admin/releases/newto publish a release, such asv1.0.0. - Go to Packagist, click on
Submitin the navigation, and submit your GitHub project addresshttps://github.com/your_username/admin. This completes the plugin release.
Tip
If submitting the plugin inPackagistshows a name conflict, you can choose a different vendor name, for example, changingfoo/admintomyfoo/admin.
Subsequently, when your plugin project code is updated, you need to synchronize the code to GitHub and re-enter https://github.com/your_username/admin/releases/new to publish a new release, then go to https://packagist.org/packages/foo/admin and click the Update button to update the version.
Add Commands to the Plugin
Sometimes our plugins need some custom commands to provide auxiliary functions. For example, after installing the webman/redis-queue plugin, the project will automatically add a redis-queue:consumer command. Users only need to run php webman redis-queue:consumer send-mail to generate a SendMail.php consumer class in the project, which aids in rapid development.
Assuming the foo/admin plugin needs to add the foo-admin:add command, follow the steps below.
Create Command
Create a command file vendor/foo/admin/src/FooAdminAddCommand.php
<?php
namespace Foo\Admin;
use Symfony\Component\Console\Command\Command;
use Symfony\Component\Console\Input\InputInterface;
use Symfony\Component\Console\Output\OutputInterface;
use Symfony\Component\Console\Input\InputOption;
use Symfony\Component\Console\Input\InputArgument;
class FooAdminAddCommand extends Command
{
protected static $defaultName = 'foo-admin:add';
protected static $defaultDescription = 'This is the command line description';
/**
* @return void
*/
protected function configure()
{
$this->addArgument('name', InputArgument::REQUIRED, 'Add name');
}
/**
* @param InputInterface $input
* @param OutputInterface $output
* @return int
*/
protected function execute(InputInterface $input, OutputInterface $output)
{
$name = $input->getArgument('name');
$output->writeln("Admin add $name");
return self::SUCCESS;
}
}
Note
To avoid command conflicts between plugins, it is recommended that the command-line format bevendor-plugin_name:specific_command. For example, all commands for thefoo/adminplugin should have the prefixfoo-admin:, such asfoo-admin:add.
Add Configuration
Create configuration config/plugin/foo/admin/command.php
<?php
use Foo\Admin\FooAdminAddCommand;
return [
FooAdminAddCommand::class,
// ....you can add multiple configurations...
];
Tip
Thecommand.phpis used to configure custom commands for the plugin. Each element in the array corresponds to a command line class file, and each class file corresponds to a command. When users run a command,webman/consolewill automatically load the custom commands set in each plugin'scommand.php. For more information on command line related topics, please refer to Command Line.
Execute Export
Execute the command php webman plugin:export --name=foo/admin to export the plugin and submit it to Packagist. This way, after users install the foo/admin plugin, a foo-admin:add command will be added. Executing php webman foo-admin:add jerry will print Admin add jerry.