From a624dee4e437f59032cf4e16b9690d6c15f006fb Mon Sep 17 00:00:00 2001 From: Alexandre Froger Date: Fri, 12 Jan 2024 14:56:16 +0800 Subject: [PATCH] doc MVP --- README.md | 29 ++- css/admin/main.css | 19 ++ inc/templates/admin/plugin-help-page.php | 257 ++++++++++++++--------- 3 files changed, 204 insertions(+), 101 deletions(-) diff --git a/README.md b/README.md index 1a312dc..545b0b4 100644 --- a/README.md +++ b/README.md @@ -330,11 +330,36 @@ The following can also be found under the "Help" tab of the WP Packages Update S ### Provide updates with WP Packages Update Server - packages requirements -To link your packages to WP Packages Update Server, and optionally to prevent webmasters from getting updates of your plugins and themes without a license, your plugins and themes need to include some extra code. It is a simple matter of adding a few lines in the main plugin file (for plugins) or in the `functions.php` file (for themes), and provide the necessary libraries in a lib directory at the root of the package. +To link your packages to WP Packages Update Server, and optionally to prevent webmasters from getting updates of your ppackages without a license, your packages need to include some extra code. + +For plugins, and themes, it is fairly straightforward: +- Add a `lib` directory with the `plugin-update-checker` and `wp-update-checker` libraries to the root of the package (provided in `dummy-[plugin|theme]` ; `wp-update-checker` can be customized as you see fit, but `plugin-update-checker` should be left untouched). +- Add the following code to the main plugin file (for plugins) or in the `functions.php` file (for themes) : +```php +/** Enable updates - note the `$prefix_updater` variable: change `prefix` to a unique string for your package **/ +require_once __DIR__ . '/lib/wp-package-updater/class-wp-package-updater.php'; + +$prefix_updater = new WP_Package_Updater( + wp_normalize_path( __FILE__ ), + strpos( __DIR__, WP_PLUGIN_DIR ) === 0 ? wp_normalize_path( __DIR__ ) : get_stylesheet_directory() +); +``` +- Add a `wppus.json` file at the root of the package with the following content - change the value of `"server"` to your own (required), and select a value for `"requireLicense"` (optional): +```json +{ + "server": "https://server.domain.tld/", + "requireLicense": true|false +} +``` +- Connect WPPUS with your repository and prime your package, or manually upload your package to WPPUS. + +For generic packages, the steps involved entirely depend on the language used to write the package and the update process of the target platform. +You may refer to the documentation found [here](https://github.com/froger-me/wp-packages-update-server/blob/main/integration/docs/generic.md) +___ See `wp-content/plugins/wp-packages-update-server/integration/dummy-plugin` for an example of plugin, and `wp-content/plugins/wp-packages-update-server/integration/dummy-theme` for an example of theme. They are fully functionnal and can be used to test all the features of the server with a test client installation of WordPress. -'See `wp-content/plugins/wp-packages-update-server/integration/dummy-generic` for examples of a generic package written in Bash, NodeJS, PHP with Curl, and Python. The API calls made by generic packages to the license API and Update API are the same as the WordPress packages. Unlike the upgrade library provided with plugins & themes, the code found in `wppwus-api.[sh|php|js|py]` files is **NOT ready for production environment and MUST be adapted**. You may refer to the documentation found [here](https://github.com/froger-me/wp-packages-update-server/blob/main/integration/docs/generic.md). +See `wp-content/plugins/wp-packages-update-server/integration/dummy-generic` for examples of a generic package written in Bash, NodeJS, PHP with Curl, and Python. The API calls made by generic packages to the license API and Update API are the same as the WordPress packages. Unlike the upgrade library provided with plugins & themes, the code found in `wppwus-api.[sh|php|js|py]` files is **NOT ready for production environment and MUST be adapted**. Unless "Use Remote Repository Service" is checked in "Remote Sources", you need to manually upload the packages zip archives (and subsequent updates) in `wp-content/wppus/packages` or `CloudStorageUnit://wppus-packages/`. Packages need to be valid WordPress plugin or theme packages, and in the case of a plugin the main plugin file must have the same name as the zip archive. For example, the main plugin file in `package-slug.zip` would be `package-slug.php`. diff --git a/css/admin/main.css b/css/admin/main.css index 07697a0..6eeac4d 100644 --- a/css/admin/main.css +++ b/css/admin/main.css @@ -32,4 +32,23 @@ width: 20px; -webkit-font-smoothing: antialiased; -moz-osx-font-smoothing: grayscale; +} + +.wppus-wrap .help-content ul { + display: block; + list-style-type: disc; + margin-block-start: 1em; + margin-block-end: 1em; + margin-inline-start: 0px; + margin-inline-end: 0px; + padding-inline-start: 40px; +} + +.wppus-wrap .help-content pre { + background: rgba(0,0,0,.07); + direction: ltr; + overflow: auto; + padding: 1em; + display: inline-block; + tab-size: 4; } \ No newline at end of file diff --git a/inc/templates/admin/plugin-help-page.php b/inc/templates/admin/plugin-help-page.php index 0a787fd..6f55140 100644 --- a/inc/templates/admin/plugin-help-page.php +++ b/inc/templates/admin/plugin-help-page.php @@ -3,103 +3,162 @@ } ?>
display_settings_header( '' ); ?> -

-

- functions.php, %2$s is lib, %3$s is main file - esc_html__( 'To link your packages, whether they are WordPress plugins, WordPress themes, or generic packages, to the WP Packages Update Server, and optionally to prevent users from getting updates of your packages without a license, your packages need to include some extra code. For WordPress packages, it is a simple matter of adding a few lines in the main plugin file (for plugins), or in the %1$s file (for themes), and provide the necessary libraries in a %2$s directory at the root of the package.', 'wppus' ), - 'functions.php', - 'lib', - ); - ?> -

-

- integration/dummy-plugin, %2$s is integration/dummy-theme - esc_html__( 'See %1$s for an example of plugin, and %2$ss for an example of theme. They are fully functionnal and can be used to test all the features of the server with a test client installation of WordPress.', 'wppus' ), - '' . esc_html( WPPUS_PLUGIN_PATH ) . 'integration/dummy-plugin', - '' . esc_html( WPPUS_PLUGIN_PATH ) . 'integration/dummy-plugin', - ); - ?> -

-

- integration/dummy-generic, %2$s is `wppus-api.[sh|php|js|py]`, %3$s is is a "here" link to the documentation - esc_html__( 'See %1$s for examples of a generic package written in Bash, NodeJS, PHP with Curl, and Python. The API calls made by generic packages to the license API and Update API are the same as the WordPress packages. Unlike the upgrade library provided with plugins & themes, the code found in %2$s files is NOT ready for production environment and MUST be adapted. You may refer to the documentation found %3$s.', 'wppus' ), - '' . esc_html( WPPUS_PLUGIN_PATH ) . 'integration/dummy-generic', - 'wppwus-api.[sh|php|js|py]', - '' . esc_html__( 'here', 'wppus' ) . '' - ); - ?> -

-

- packages_dir, %2$s is package-slug.zip, %3$s is package-slug.php - esc_html__( 'Unless "Use Remote Repository Service" is checked in "Remote Sources", you need to manually upload the packages zip archives (and subsequent updates) in %1$s. A packages need to a valid generic package, or a valid WordPress plugin or theme package, and in the case of a plugin the main plugin file must have the same name as the zip archive. For example, the main plugin file in %2$s would be %3$s.', 'wppus' ), - '' . esc_html( $packages_dir ) . '', - 'package-slug.zip', - 'package-slug.php', - ); - ?> -

-
-

-

- parse_request - esc_html__( "When the remote clients where your plugins, themes, or generic packages are installed send a request to check for updates, download a package or check or change license status, the current server's WordPress installation is loaded, with its own plugins and themes. This is not optimised if left untouched because unnecessary action and filter hooks that execute before %s action hook are also triggered, even though the request is not designed to produce any on-screen output or further computation.", 'wppus' ), - 'parse_request', - ); - ?> -

-

- optimisation/wppus-endpoint-optimiser.php, %2$s is the MU Plugin's path - esc_html__( 'To solve this, the file %1$s has been automatically copied to %2$s. This effectively creates a Must Use Plugin running before everything else and preventing themes and other plugins from being executed when an update request or a license API request is received by WP Packages Update Server.', 'wppus' ), - '' . esc_html( WPPUS_PLUGIN_PATH . 'optimisation/wppus-endpoint-optimiser.php' ) . '', - '' . esc_html( dirname( dirname( WPPUS_PLUGIN_PATH ) ) . '/mu-plugins/wppus-endpoint-optimiser.php' ) . '', - ); - ?> -

-

- $wppus_doing_update_api_request, %2$s is $wppus_doing_license_api_request, %3$s is $wppus_always_active_plugins, %4$s is functions.php, %5$s is $wppus_bypass_themes, %5$s is false - esc_html__( 'The MU Plugin also provides the global variable %1$s and %2$s that can be tested when adding hooks and filters would you choose to keep some plugins active with %3$s or keep %4$s from themes included with %5$s set to %6$s.', 'wppus' ), - '$wppus_doing_update_api_request', - '$wppus_doing_license_api_request', - '$wppus_always_active_plugins', - 'functions.php', - '$wppus_bypass_themes', - 'false', - ); - ?> -

-
-

-

- ' . esc_html__( 'here', 'wppus' ) . '', - ); - ?> -

-

- ' . esc_html__( 'open an issue on Github', 'wppus' ) . '', - 'wppus-help@anyape.com', - ); - ?> -

+
+

+

+

+ +

+
    +
  • + lib, %2$s is plugin-update-checker, %3$s is wp-update-checker, %4$s is dummy-[plugin|theme], %5$s is wp-update-checker, %6$s is plugin-update-checker + esc_html__( 'Add a %1$s directory with the %2$s and %3$s libraries to the root of the package (provided in %4$s ; %5$s can be customized as you see fit, but %6$s should be left untouched).', 'wppus' ), + 'lib', + 'plugin-update-checker', + 'wp-update-checker', + 'dummy-[plugin|theme]', + 'wp-update-checker', + 'plugin-update-checker', + ); + ?> +
    • +
  • + functions.php + esc_html__( 'Add the following code to the main plugin file (for plugins) or in the %s file (for themes) :', 'wppus' ), + 'functions.php' + ); + ?> +
    /** Enable updates - note the  `$prefix_updater` variable: change `prefix` to a unique string for your package **/
+require_once __DIR__ . '/lib/wp-package-updater/class-wp-package-updater.php';
+
+$prefix_updater = new WP_Package_Updater(
+	wp_normalize_path( __FILE__ ),
+	strpos( __DIR__, WP_PLUGIN_DIR ) === 0 ? wp_normalize_path( __DIR__ ) : get_stylesheet_directory()
+);
    +
    • +
  • + wppus.json, %2$s is "server" + esc_html__( 'Add a %1$s file at the root of the package with the following content - change the value of %2$s to your own (required), and select a value for %3$s (optional):', 'wppus' ), + 'wppus.json', + '"server"', + '"requireLicense"' + ); + ?> + 
    {
+	"server": "https://server.domain.tld/",
+	"requireLicense": true|false
+}
    +
    • +
  • + +
    • +
+

+ +
+ ' . esc_html__( 'here', 'wppus' ) . '' + ); + ?> +

+
+

+ integration/dummy-plugin, %2$s is integration/dummy-theme + esc_html__( 'See %1$s for an example of plugin, and %2$ss for an example of theme. They are fully functionnal and can be used to test all the features of the server with a test client installation of WordPress.', 'wppus' ), + '' . esc_html( WPPUS_PLUGIN_PATH ) . 'integration/dummy-plugin', + '' . esc_html( WPPUS_PLUGIN_PATH ) . 'integration/dummy-plugin', + ); + ?> +

+

+ integration/dummy-generic, %2$s is `wppus-api.[sh|php|js|py]` + esc_html__( 'See %1$s for examples of a generic package written in Bash, NodeJS, PHP with Curl, and Python. The API calls made by generic packages to the license API and Update API are the same as the WordPress packages. Unlike the upgrade library provided with plugins & themes, the code found in %2$s files is NOT ready for production environment and MUST be adapted.', 'wppus' ), + '' . esc_html( WPPUS_PLUGIN_PATH ) . 'integration/dummy-generic', + 'wppus-api.[sh|php|js|py]' + ); + ?> +

+

+ packages_dir, %2$s is package-slug.zip, %3$s is package-slug.php + esc_html__( 'Unless "Use Remote Repository Service" is checked in "Remote Sources", you need to manually upload the packages zip archives (and subsequent updates) in %1$s. A packages need to a valid generic package, or a valid WordPress plugin or theme package, and in the case of a plugin the main plugin file must have the same name as the zip archive. For example, the main plugin file in %2$s would be %3$s.', 'wppus' ), + '' . esc_html( $packages_dir ) . '', + 'package-slug.zip', + 'package-slug.php', + ); + ?> +

+
+

+

+ parse_request + esc_html__( "When the remote clients where your plugins, themes, or generic packages are installed send a request to check for updates, download a package or check or change license status, the current server's WordPress installation is loaded, with its own plugins and themes. This is not optimised if left untouched because unnecessary action and filter hooks that execute before %s action hook are also triggered, even though the request is not designed to produce any on-screen output or further computation.", 'wppus' ), + 'parse_request', + ); + ?> +

+

+ optimisation/wppus-endpoint-optimiser.php, %2$s is the MU Plugin's path + esc_html__( 'To solve this, the file %1$s has been automatically copied to %2$s. This effectively creates a Must Use Plugin running before everything else and preventing themes and other plugins from being executed when an update request or a license API request is received by WP Packages Update Server.', 'wppus' ), + '' . esc_html( WPPUS_PLUGIN_PATH . 'optimisation/wppus-endpoint-optimiser.php' ) . '', + '' . esc_html( dirname( dirname( WPPUS_PLUGIN_PATH ) ) . '/mu-plugins/wppus-endpoint-optimiser.php' ) . '', + ); + ?> +

+

+ $wppus_doing_update_api_request, %2$s is $wppus_doing_license_api_request, %3$s is $wppus_always_active_plugins, %4$s is functions.php, %5$s is $wppus_bypass_themes, %5$s is false + esc_html__( 'The MU Plugin also provides the global variable %1$s and %2$s that can be tested when adding hooks and filters would you choose to keep some plugins active with %3$s or keep %4$s from themes included with %5$s set to %6$s.', 'wppus' ), + '$wppus_doing_update_api_request', + '$wppus_doing_license_api_request', + '$wppus_always_active_plugins', + 'functions.php', + '$wppus_bypass_themes', + 'false', + ); + ?> +

+
+

+

+ ' . esc_html__( 'here', 'wppus' ) . '', + ); + ?> +

+

+ ' . esc_html__( 'open an issue on Github', 'wppus' ) . '', + 'wppus-help@anyape.com', + ); + ?> +

+