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.php
in 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.php
will 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:
vendor
andplugin 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.php
as the main plugin configuration,bootstrap.php
for process startup configuration,route.php
for routing configuration,middleware.php
for middleware configuration,process.php
for custom process configuration,database.php
for database configuration,redis.php
for Redis configuration, andthinkorm.php
for 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/src
and 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/admin
supports the following configurations:app.php
as the main plugin configuration,bootstrap.php
for process startup configuration,route.php
for routing configuration,middleware.php
for middleware configuration,process.php
for custom process configuration,database.php
for database configuration,redis.php
for Redis configuration, andthinkorm.php
for ThinkORM configuration. The configuration format is the same as Webman, and these configurations will be automatically recognized and merged by Webman.
Access withplugin
as 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/admin
directory will be copied tovendor/foo/admin/src
, and anInstall.php
will be automatically generated. TheInstall.php
is used to perform operations during automatic installation and uninstallation.
The default operation upon installation is to copy the configurations fromvendor/foo/admin/src
to the current project'sconfig/plugin
directory.
The default operation upon removal is to delete the configuration files from the current project'sconfig/plugin
directory.
You can modifyInstall.php
to 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/new
to publish a release, such asv1.0.0
. - Go to Packagist, click on
Submit
in the navigation, and submit your GitHub project addresshttps://github.com/your_username/admin
. This completes the plugin release.
Tip
If submitting the plugin inPackagist
shows a name conflict, you can choose a different vendor name, for example, changingfoo/admin
tomyfoo/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/admin
plugin 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.php
is 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/console
will 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
.