Basic Plugin Generation and Publishing Process

Principle

  1. 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 is Install.php, which is automatically generated by the command.
  2. We use the command to package these three files and publish them to Composer.
  3. 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.
  4. 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

  1. The plugin name consists of two parts: vendor and plugin name, for example, webman/push, which corresponds to the Composer package name.
  2. 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.
  3. 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, and thinkorm.php for ThinkORM configuration. These configurations will be automatically recognized by Webman.
  4. 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').
  5. If the plugin has its own database configuration, it should be accessed using the following way. For illuminate/database, use Db::connection('plugin.vendor.plugin_name.specific_connection'), for thinkorm, use Db::connct('plugin.vendor.plugin_name.specific_connection').
  6. 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.
  7. 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.
  8. 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, and thinkorm.php for ThinkORM configuration. The configuration format is the same as Webman, and these configurations will be automatically recognized and merged by Webman.
Access with plugin 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, the config/plugin/foo/admin directory will be copied to vendor/foo/admin/src, and an Install.php will be automatically generated. The Install.php is used to perform operations during automatic installation and uninstallation.
The default operation upon installation is to copy the configurations from vendor/foo/admin/src to the current project's config/plugin directory.
The default operation upon removal is to delete the configuration files from the current project's config/plugin directory.
You can modify Install.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 as v1.0.0.
  • Go to Packagist, click on Submit in the navigation, and submit your GitHub project address https://github.com/your_username/admin. This completes the plugin release.

Tip
If submitting the plugin in Packagist shows a name conflict, you can choose a different vendor name, for example, changing foo/admin to myfoo/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 be vendor-plugin_name:specific_command. For example, all commands for the foo/admin plugin should have the prefix foo-admin:, such as foo-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
The command.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's command.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.