Skip to content

Commit dd48ed7

Browse files
robincornettrobincornett
committed
Update doc blocks, readme
#14
1 parent 77a7a65 commit dd48ed7

File tree

2 files changed

+51
-167
lines changed

2 files changed

+51
-167
lines changed

‎readme.md‎

Lines changed: 49 additions & 164 deletions
Original file line numberDiff line numberDiff line change
@@ -1,180 +1,65 @@
11
# EDD Software Licensing SDK
22

3-
## Example Usage
4-
5-
```php
6-
use EDD_SL_SDK\SDK;
7-
8-
require_once 'edd-sl-sdk-main/src/Loader.php';
9-
10-
add_action( 'edd_sl_sdk_loaded', function ( SDK $sdk ) {
11-
try {
12-
$sdk->registerStore( array(
13-
'id' => 'sandhillsdev.com',
14-
'api_url' => 'https://sandhillsdev.com/wp-json/edd-sl/v2',
15-
'author' => 'Sandhills Development, LLC',
16-
'products' => array(
17-
/* Plugin Example */
18-
[
19-
'type' => 'plugin',
20-
'product_id' => 123,
21-
'file' => __FILE__,
22-
'version' => '1.0',
23-
'beta' => false,
3+
You can run the SDK as a standalone plugin on your site, or install it as a Composer package in your theme or plugin:
244

25-
/*
26-
* Optionally have an admin menu managed for you.
27-
* Accepts all the same arguments as `add_submenu_page()`
28-
* @link https://developer.wordpress.org/reference/functions/add_submenu_page/
29-
*/
30-
'menu' => [
31-
'parent_slug' => 'options-general.php',
32-
'page_title' => 'My Plugin License',
33-
'menu_title' => 'My Plugin License',
34-
'menu_slug' => 'my-plugin-license',
35-
],
36-
],
37-
/* Theme Example */
38-
[
39-
'type' => 'theme',
40-
'product_id' => 125,
41-
'beta' => false
42-
]
43-
)
44-
) );
45-
} catch ( \Exception $e ) {
46-
// Optionally do something error messages.
47-
}
48-
} );
495
```
50-
51-
## Store Arguments
52-
53-
- `id` - Optional. Unique ID for your store. If omitted, it's generated from your API URL.
54-
- `api_url` - **Required.** API endpoint. Should be `https://yoursite.com/wp-json/edd-sl/v2`
55-
- `author` - Optional. Plugin author name.
56-
- `products` - Optional. Array of product registrations.
57-
- `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.
58-
59-
## Product Arguments
60-
61-
- `type` - **Required.** Either `plugin` or `theme`
62-
- `product_id` - **Required.** ID of the product in your Software Licensing store.
63-
- `file` - **Required for plugins.** Path to the main plugin file.
64-
- `version` - **Required for plugins.** Current version number. If omitted for a theme, the version will be parsed from the stylesheet.
65-
- `slug` - Optional. Name of the theme or plugin directory.
66-
- `beta` - Optional. Whether to receive beta versions.
67-
- `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/).
68-
- `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`.
69-
- `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`.
70-
- `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).
71-
- `license_setter` - Optional. Closure used for setting the license key.
72-
- `i18n` - Optional. Array of translation-ready strings. See transaction section for available strings.
73-
74-
### Custom getter & setter
75-
76-
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.
77-
78-
```php
79-
[
80-
'license_getter' => static function() {
81-
return edd_get_option( 'my_license_key' );
82-
},
83-
'license_setter' => static function ( $newLicense, $previousLicense ) {
84-
edd_update_option( 'my_license_key', sanitize_text_field( $newLicense ) );
6+
{
7+
"name": "edd/edd-sample-plugin",
8+
"license": "GPL-2.0-or-later",
9+
"repositories": {
10+
"edd-sl-sdk": {
11+
"type": "vcs",
12+
"url": "[email protected]:awesomemotive/edd-sl-sdk.git"
8513
}
86-
]
87-
```
88-
89-
### Main plugin with add-ons example
90-
91-
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.
92-
93-
The benefit of this is that you only need to declare your API URL once in the "parent plugin".
14+
},
15+
"require": {
16+
"easy-digital-downloads/edd-sl-sdk": "1.0.0"
17+
}
18+
}
9419
95-
Here's how that would look:
96-
97-
The parent plugin would register the store like this:
20+
## Example Usage
9821
22+
Plugin:
9923
```php
100-
add_action( 'edd_sl_sdk_loaded', function ( \EDD_SL_SDK\SDK $sdk ) {
101-
try {
102-
$sdk->registerStore( [
103-
// ID: Replace `yoursite.com` with the domain name of the site that has Software Licensing installed.
104-
'id' => 'yoursite.com',
105-
// API URL: Replace `yoursite.com` with the domain of the site that has Software Licensing installed.
106-
'api_url' => 'https://yoursite.com/wp-json/edd-sl/v2',
107-
// Author: Your company's name.
108-
'author' => 'Sandhills Development, LLC',
109-
] );
110-
} catch ( \Exception $e ) {
111-
24+
add_action(
25+
'edd_sl_sdk_registry',
26+
function ( $init ) {
27+
$init->register(
28+
array(
29+
'id' => 'edd-sample-plugin', // The plugin slug.
30+
'url' => 'https://edd.test', // The URL of the site with EDD installed.
31+
'item_id' => 83, // The download ID of the product in Easy Digital Downloads.
32+
'version' => '1.0.0', // The version of the product.
33+
'file' => __FILE__, // The path to the main plugin file.
34+
)
35+
);
11236
}
113-
} );
37+
);
11438
```
11539

116-
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:
117-
118-
```php
119-
add_action( 'edd_sl_sdk_loaded', function ( \EDD_SL_SDK\SDK $sdk ) {
120-
try {
121-
$sdk->registerStore( [
122-
// ID: Replace `yoursite.com` with the domain name of the site that has Software Licensing installed.
123-
'id' => 'yoursite.com',
124-
// API URL: Replace `yoursite.com` with the domain of the site that has Software Licensing installed.
125-
'api_url' => 'https://yoursite.com/wp-json/edd-sl/v2',
126-
// Author: Your company's name.
127-
'author' => 'Sandhills Development, LLC',
128-
'products' => [
129-
[
130-
'type' => 'plugin',
131-
'product_id' => 123, // @todo replace
132-
'file' => __FILE__,
133-
'version' => '1.0', // @todo replace
134-
]
135-
]
136-
] );
137-
} catch ( \Exception $e ) {
138-
139-
}
140-
} );
40+
Theme:
14141
```
142-
143-
Then, each add-on can skip the store registration and piggyback off the parent, like this:
144-
145-
```php
146-
add_action( 'edd_sl_after_store_registered', function ( \EDD_SL_SDK\Models\Store $store ) {
147-
if ( 'yoursite.com' === $store->id ) {
148-
try {
149-
$store->addProduct( [
150-
'type' => 'plugin',
151-
'product_id' => 123, // @todo replace
152-
'file' => __FILE__,
153-
'version' => '1.0', // @todo replace
154-
] );
155-
} catch ( \Exception $e ) {
156-
157-
}
42+
add_action(
43+
'edd_sl_sdk_registry',
44+
function ( $init ) {
45+
$init->register(
46+
array(
47+
'id' => 'edd-sample-theme',
48+
'url' => 'https://easydigitaldownloads.com',
49+
'item_id' => 123,
50+
'version' => '1.0.0',
51+
'type' => 'theme',
52+
)
53+
);
15854
}
159-
} );
55+
);
16056
```
16157

162-
This product will be registered to the store that was created in the parent plugin and use the same API URL.
163-
164-
## Strings
165-
166-
If using an admin menu, all the strings used for displaying statuses and response messages can be customized or made translation-ready.
58+
## Arguments
16759

168-
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.
169-
170-
Example:
171-
172-
```php
173-
[
174-
// Other options here.
175-
'i18n' => [
176-
'activate_license' => __( 'Activate License', 'my-plugin-text-domain' ),
177-
// More strings below, if desired.
178-
]
179-
];
180-
```
60+
- `id` - Plugin/theme slug.
61+
- `url` - The store URL.
62+
- `item_id` - The item ID (on your store).
63+
- `version` - The current version number.
64+
- `file` - The main plugin file. Not needed for themes.
65+
- `type` - `plugin` or `theme`. Not needed for plugins.

‎src/Licensing/License.php‎

Lines changed: 2 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -62,7 +62,7 @@ public function get_license_key() {
6262
* Gets the license key option name.
6363
*
6464
* @since <next-version>
65-
* @return void
65+
* @return string
6666
*/
6767
public function get_key_option_name() {
6868
return ! empty( $this->args['option_name'] ) ? $this->args['option_name'] : "{$this->slug}_license_key";
@@ -72,8 +72,7 @@ public function get_key_option_name() {
7272
* Gets the button for the pass field.
7373
*
7474
* @since <next-version>
75-
* @param string $status The pass status.
76-
* @param bool $echo Whether to echo the button.
75+
* @param bool $should_echo Whether to echo the button.
7776
* @return string
7877
*/
7978
public function get_actions( $should_echo = false ) {

0 commit comments

Comments
 (0)