Merge pull request #19 from awesomemotive/issue/14

Update documentation

Author: cklosowski

readme.md

@@ -1,180 +1,102 @@
 # EDD Software Licensing SDK
 
-## Example Usage
+A drop-in solution for WordPress plugin and theme developers to quickly integrate Easy Digital Downloads Software Licensing into their products without complex setup or custom admin interfaces.
 
-```php
-use EDD_SL_SDK\SDK;
-
-require_once 'edd-sl-sdk-main/src/Loader.php';
-
-add_action( 'edd_sl_sdk_loaded', function ( SDK $sdk ) {
-	try {
-		$sdk->registerStore( array(
-			'id'       => 'sandhillsdev.com',
-			'api_url'  => 'https://sandhillsdev.com/wp-json/edd-sl/v2',
-			'author'   => 'Sandhills Development, LLC',
-			'products' => array(
-				/* Plugin Example */
-				[
-					'type'       => 'plugin',
-					'product_id' => 123,
-					'file'       => __FILE__,
-					'version'    => '1.0',
-					'beta'       => false,
-
-					/*
-					 * Optionally have an admin menu managed for you. 
-					 * Accepts all the same arguments as `add_submenu_page()`
-					 * @link https://developer.wordpress.org/reference/functions/add_submenu_page/
-					 */
-					'menu'       => [
-						'parent_slug' => 'options-general.php',
-						'page_title'  => 'My Plugin License',
-						'menu_title'  => 'My Plugin License',
-						'menu_slug'   => 'my-plugin-license',
-					],
-				],
-				/* Theme Example */
-				[
-					'type'       => 'theme',
-					'product_id' => 125,
-					'beta'       => false
-				]
-			)
-		) );
-	} catch ( \Exception $e ) {
-		// Optionally do something error messages.
-	}
-} );
-```
+## Overview
 
-## Store Arguments
-
-- `id` - Optional. Unique ID for your store. If omitted, it's generated from your API URL.
-- `api_url` - **Required.** API endpoint. Should be `https://yoursite.com/wp-json/edd-sl/v2`
-- `author` - Optional. Plugin author name.
-- `products` - Optional. Array of product registrations.
-- `update_cache_duration` - Optional. Length of time, in seconds, to cache update API responses. Default is `180` (3 hours). Set to `0` to disable caching. If disabled, a fresh API request is made every time WordPress core checks for plugin/theme updates.
-
-## Product Arguments
-
-- `type` - **Required.** Either `plugin` or `theme`
-- `product_id` - **Required.** ID of the product in your Software Licensing store.
-- `file` - **Required for plugins.** Path to the main plugin file.
-- `version` - **Required for plugins.** Current version number. If omitted for a theme, the version will be parsed from the stylesheet.
-- `slug` - Optional. Name of the theme or plugin directory.
-- `beta` - Optional. Whether to receive beta versions.
-- `menu` - Optional. If set, the SDK will handle rendering an admin page UI, which does license activation and deactivation. This can be set to `true` for all default arguments, or can accept an array of any arguments used by [add_submenu_page()](https://developer.wordpress.org/reference/functions/add_submenu_page/).
-- `license_option_name` - Optional. Name of the option used for saving the license key. By default, it's built using this format: `sl_{type}_{slug}_license`.
-- `license_object_option_name` - Optional. Name of the option used for saving license data. This is the response data from the API when activating/checking a license key. By default, it's built using this format: `sl_{type}_{slug}_license_object`.
-- `license_getter` - Optional. Closure used for retrieving the license key. This can be set if you do not want to save the license key in the options table (such as if you're using a custom table).
-- `license_setter` - Optional. Closure used for setting the license key.
-- `i18n` - Optional. Array of translation-ready strings. See transaction section for available strings.
-
-### Custom getter & setter
-
-Here's an example of how to use a custom getter and setter. In this example, the reason for using a getter and setter is that we're using custom `edd_get/update_option()` functions instead of the ones from WordPress core.
-
-```php 
-[
-    'license_getter' => static function() {
-        return edd_get_option( 'my_license_key' );
-    },
-    'license_setter' => static function ( $newLicense, $previousLicense ) {
-        edd_update_option( 'my_license_key', sanitize_text_field( $newLicense ) );
-    }
-]
-```
+The EDD Software Licensing SDK streamlines the process of adding licensing functionality to your WordPress plugins and themes. Instead of building custom settings pages and handling license validation manually, this SDK provides a complete licensing solution that seamlessly integrates with existing WordPress admin interfaces.
 
-### Main plugin with add-ons example
+### Key Features
 
-If you sell "add-on" plugins to a main plugin (such as Easy Digital Downloads with its various extensions) then you can optionally only register your store in the main plugin file. Then each add-on adds a product to that existing store.
+- **Zero-configuration licensing** - Add licensing support with just a few lines of code
+- **Native WordPress integration** - License fields appear directly in plugin action links and theme admin menus
+- **Automatic updates** - Handles secure update delivery for licensed products
+- **No custom admin pages** - Uses WordPress's existing interface patterns
+- **Flexible deployment** - Works as a standalone plugin or Composer package
+- **Developer-friendly** - Minimal code required, maximum functionality provided
 
-The benefit of this is that you only need to declare your API URL once in the "parent plugin".
+### How It Works
 
-Here's how that would look:
+For **plugins**, the SDK adds a "Manage License" link directly in the plugin list on the Plugins admin screen. Clicking this link opens a modal where users can enter and activate their license key.
 
-The parent plugin would register the store like this:
+For **themes**, a "Theme License" menu item is automatically added to the Appearance menu, providing easy access to license management via the modal.
 
-```php
-add_action( 'edd_sl_sdk_loaded', function ( \EDD_SL_SDK\SDK $sdk ) {
-	try {
-		$sdk->registerStore( [
-			// ID: Replace `yoursite.com` with the domain name of the site that has Software Licensing installed.
-			'id'      => 'yoursite.com',
-			// API URL: Replace `yoursite.com` with the domain of the site that has Software Licensing installed.
-			'api_url' => 'https://yoursite.com/wp-json/edd-sl/v2',
-			// Author: Your company's name.
-			'author'  => 'Sandhills Development, LLC',
-		] );
-	} catch ( \Exception $e ) {
+The SDK handles all the complex licensing logic behind the scenes:
+- License key validation and activation
+- Automatic update notifications and delivery
+- License status tracking and renewal reminders
+- Secure communication with your EDD store
+
+### Perfect For
+
+- Plugin developers who want to focus on features, not licensing infrastructure
+- Theme authors looking for a professional licensing solution
+- Developers transitioning from other licensing systems
+- Anyone who wants licensing integration without reinventing the wheel
+
+## Installation
+
+You can run the SDK as a standalone plugin on your site, or install it as a Composer package in your theme or plugin:
 
-	}
-} );
 ```
+{
+  "name": "edd/edd-sample-plugin",
+  "license": "GPL-2.0-or-later",
+  "repositories": {
+    "edd-sl-sdk": {
+      "type": "vcs",
+      "url": "[email protected]:awesomemotive/edd-sl-sdk.git"
+    }
+  },
+  "require": {
+    "easy-digital-downloads/edd-sl-sdk": "1.0.0"
+  }
+}
 
-Note that if your parent plugin is also a product in itself and not hosted in the .org repo, you'll also need to register the parent plugin's product like so:
-
-```php 
-add_action( 'edd_sl_sdk_loaded', function ( \EDD_SL_SDK\SDK $sdk ) {
-	try {
-		$sdk->registerStore( [
-			// ID: Replace `yoursite.com` with the domain name of the site that has Software Licensing installed.
-			'id'       => 'yoursite.com',
-			// API URL: Replace `yoursite.com` with the domain of the site that has Software Licensing installed.
-			'api_url'  => 'https://yoursite.com/wp-json/edd-sl/v2',
-			// Author: Your company's name.
-			'author'   => 'Sandhills Development, LLC',
-			'products' => [
-				[
-					'type'       => 'plugin',
-					'product_id' => 123, // @todo replace
-					'file'       => __FILE__,
-					'version'    => '1.0', // @todo replace
-				]
-			]
-		] );
-	} catch ( \Exception $e ) {
+### Example Usage
 
+Plugin:
+```php
+add_action(
+	'edd_sl_sdk_registry',
+	function ( $init ) {
+		$init->register(
+			array(
+				'id'      => 'edd-sample-plugin', // The plugin slug.
+				'url'     => 'https://edd.test', // The URL of the site with EDD installed.
+				'item_id' => 83, // The download ID of the product in Easy Digital Downloads.
+				'version' => '1.0.0', // The version of the product.
+				'file'    => __FILE__, // The path to the main plugin file.
+			)
+		);
 	}
-} );
+);
 ```
 
-Then, each add-on can skip the store registration and piggyback off the parent, like this:
-
-```php 
-add_action( 'edd_sl_after_store_registered', function ( \EDD_SL_SDK\Models\Store $store ) {
-	if ( 'yoursite.com' === $store->id ) {
-		try {
-			$store->addProduct( [
-				'type'       => 'plugin',
-				'product_id' => 123, // @todo replace
-				'file'       => __FILE__,
-				'version'    => '1.0', // @todo replace
-			] );
-		} catch ( \Exception $e ) {
-
-		}
+Theme:
+```
+add_action(
+	'edd_sl_sdk_registry',
+	function ( $init ) {
+		$init->register(
+			array(
+				'id'      => 'edd-sample-theme',
+				'url'     => 'https://easydigitaldownloads.com',
+				'item_id' => 123,
+				'version' => '1.0.0',
+				'type'    => 'theme',
+			)
+		);
 	}
-} );
+);
 ```
 
-This product will be registered to the store that was created in the parent plugin and use the same API URL.
-
-## Strings
+### Arguments
 
-If using an admin menu, all the strings used for displaying statuses and response messages can be customized or made translation-ready.
-
-The list of strings can be found here: https://github.com/easydigitaldownloads/edd-sl-sdk/blob/main/src/Helpers/Strings.php#L15-L30 Any strings in the array can be overridden via the `i18n` array when you register your product.
-
-Example:
-
-```php
-[
-    // Other options here.
-    'i18n' => [
-        'activate_license' => __( 'Activate License', 'my-plugin-text-domain' ),
-        // More strings below, if desired.
-    ] 
-];
-```
+- `id` - Plugin/theme slug.
+- `url` - The store URL.
+- `item_id` - The item ID (on your store).
+- `version` - The current version number.
+- `file` - The main plugin file. Not needed for themes.
+- `type` - `plugin` or `theme`. Not needed for plugins.
+- `weekly_check` - Optional: whether to make a weekly request to confirm the license status. Defaults to true.

src/Licensing/License.php

@@ -62,7 +62,7 @@ public function get_license_key() {
 	 * Gets the license key option name.
 	 *
 	 * @since <next-version>
-	 * @return void
+	 * @return string
 	 */
 	public function get_key_option_name() {
 		return ! empty( $this->args['option_name'] ) ? $this->args['option_name'] : "{$this->slug}_license_key";
@@ -72,8 +72,7 @@ public function get_key_option_name() {
 	 * Gets the button for the pass field.
 	 *
 	 * @since <next-version>
-	 * @param string $status The pass status.
-	 * @param bool   $echo   Whether to echo the button.
+	 * @param bool $should_echo Whether to echo the button.
 	 * @return string
 	 */
 	public function get_actions( $should_echo = false ) {

src/Updaters/Updater.php

@@ -49,7 +49,7 @@ abstract class Updater {
 	 */
 	public function __construct( $api_url, $args = array() ) {
 		$this->api_url = $api_url;
-		$this->file    = $args['file'];
+		$this->file    = $args['file'] ?? '';
 		$defaults      = $this->get_api_request_defaults();
 		$this->args    = array_merge( $defaults, array_intersect_key( $args, $defaults ) );
 		$this->add_listeners();