{eac}SoftwareRegistry Distribution SDK

{eac}SoftwareRegistry Distribution SDK is an extension plugin to {eac}SoftwareRegistry Software Registration Server.

The Software Registry Distribution SDK is used to generate a custom PHP package that you can include in your software project to register your product with your registration server and manage that registration.

A custom version of this document is included in the generated SDK package.

The SDK provides most of the PHP code you will need to implement the Application Program Interface with your Software Registration Server.

Included with the Software Registration SDK package…

• (your_productid)_registration.(wordpress_or_filebased).trait.php

• (your_productid)_registration.includes.php

• (your_productid)_registration.interface.php

• (your_productid)_registration.interface.trait.php

• (your_productid)_registration.refresh.php

• (your_productid)_registration.readme.md

Software Registry Implementation

zip file, move the (your_productid)_registration folder to your project.

php to load the required interface and traits.

Your class file must then:

• implement \(your_namespace)\Interfaces\(your_productid)_registration

• use \(your_namespace)\Traits\(your_productid)_registration_(wordpress_or_filebased)

Example:

php";

class <your_classname> implements \(your_namespace)\Interfaces\(your_productid)_registration { use \(your_namespace)\Traits\(your_productid)_registration_(wordpress_or_filebased); ... }

php will have your product and registration server API constants.

const SOFTWARE_REGISTRY_PRODUCTID = '{your_software_registry_productid}'; const SOFTWARE_REGISTRY_HOST_URL = '{your_software_registry_host_url}'; const SOFTWARE_REGISTRY_CREATE_KEY = '{your_software_registry_create_key}'; const SOFTWARE_REGISTRY_UPDATE_KEY = '{your_software_registry_update_key}'; const SOFTWARE_REGISTRY_READ_KEY = '{your_software_registry_read_key}';

Using The API

API Parameters

API parameters are passed as an array:

), // array of valid/registered sites/uris 'registry_transid' => '', // external transaction id 'registry_timezone' => '', // standard timezone string (client timezone) 'registry_locale' => '', // standard locale/language code ];

* Required values (registry_key not required when creating a new registration).

>

If setting registry_transid, the recommended (not required) format is {id}|{source}|{suffix} where {id} is the transaction id, {source} indicates the source of the transaction, and {suffix} may be used as needed.

Any additional fields passed wil be saved as custom fields.

Although typically set by the Software Registry server, with the proper option setting, the API may override:

[ 'registry_status' => 'status', // 'pending', 'trial', 'active', 'inactive', 'expired', 'terminated' 'registry_effective' => 'DD-MMM-YYYY', // Effective date 'registry_expires' => 'DD-MMM-YYYY', // Expiration date or term ('30 days', '1 year',... added to effective date) ];

Payment information may be posted with:

[ 'registry_paydue' => float, // amount to be paid/billed, 'registry_payamount' => float, // amount paid, 'registry_paydate' => 'DD-MMM-YYYY', // date paid 'registry_payid' => 'payment id' // transaction id/check #, etc. 'registry_nextpay' => 'DD-MMM-YYYY', // next payment/renewal date ];

API Requests

Create/request a new registration…

$response = $this->registryApiRequest('create',$apiParams);

Activate an existing registration…

$response = $this->registryApiRequest('activate',['registry_key' => '<registrationKeyValue>']);

Activate and Update an existing registration…

$response = $this->registryApiRequest('activate',$apiParams);

Deactivate an existing registration…

$response = $this->registryApiRequest('deactivate',['registry_key' => '<registrationKeyValue>']);

Verify or Refresh an existing registration…

$response = $this->registryApiRequest('verify',['registry_key' => '<registrationKeyValue>']); $response = $this->registryApiRequest('refresh',$apiParams);

Revise an existing registration…

$response = $this->registryApiRequest('revise',$apiParams);

API Response

The API response is a standard object. status->code is an http status, 200 indicating success.

) 'allow_set_key', 'allow_set_status', 'allow_set_effective', 'allow_set_expiration', 'allow_activation_update' ), licenseCodes -> object( // may be changed by filter on registration server L1 -> 'Lite' L2 -> 'Basic' L3 -> 'Standard' L4 -> 'Professional' L5 -> 'Enterprise' LD -> 'Developer' LU -> 'Unlimited' ), notices -> object( info -> string, // information message text warning -> string, // warning message text error -> string, // error message text success -> string, // success message text ), message -> string, // html message ), registryHtml -> string, // html (table) of human-readable registration values supplemental -> mixed, // supplemental data/html assigned via filters (developer's discretion).

On a successful response (status->code = 200), the SDK will automatically cache the registration data and schedule the next refresh event (you do not have to do this).

notices may be set (according to severity) to indicate an expiration or pending expiration and should be displayed to the user. Typically, only one notice will be set but they can be set via the eacSoftwareRegistry_api_registration_notices filter.

message is set via the eacSoftwareRegistry_api_registration_message filter.

supplemental is set via the eacSoftwareRegistry_api_registration_supplemental filter.

On an error response, an additional element is included:

error -> ( code -> 'error_code', message -> 'error message' ),

error->message may be more informative than status->message.

Errors may be handled with something like:

"</h4></div>"; }

Methods, Hooks, and Callbacks

Useful methods built into the SDK…

}

$this->getRegistrationKey(); // Returns the current registration key $registrationKey = $this->getRegistrationKey();

$this->getCurrentRegistration(); // Returns the current registration object (above response object) $currentRegistration = $this->getCurrentRegistration();

$this->isRegistryValue($keyName); // Returns the value of a specific registry key $regStatus = $this->isRegistryValue( 'status ');

}

Several hooks are available to customize or react to registration events.

In WordPresss, there are several actions and filters, for file based projects there are corresponding callback methods…

filter/callback: (your_productid)_api_remote_request( $request, $endpoint ) @param array $request ['method'=>, 'timeout'=>, 'redirection'=>, 'sslverify'=>, 'headers'=>, 'body'=>] @param string $endpoint create, activate, deactivate, verify, refresh, revise @return array request body

action/callback: (your_productid)_api_remote_response( $body, $request, $endpoint ) @param array $body response body @param array $request ['method'=>, 'timeout'=>, 'redirection'=>, 'sslverify'=>, 'headers'=>, 'body'=>] @param string $endpoint create, activate, deactivate, verify, refresh, revise

action/callback: (your_productid)_api_remote_$endpoint( $body, $request, $endpoint ) @param array $body response body @param array $request ['method'=>, 'timeout'=>, 'redirection'=>, 'sslverify'=>, 'headers'=>, 'body'=>] @param string $endpoint create, activate, deactivate, verify, refresh, revise

action/callback: (your_productid)_api_remote_error( $error, $request, $endpoint ) @param object $error {status:{}, error: {}} @param array $request ['method'=>, 'timeout'=>, 'redirection'=>, 'sslverify'=>, 'headers'=>, 'body'=>] @param string $endpoint create, activate, deactivate, verify, refresh, revise

action/callback: (your_productid)_update_registration($registration) @param array $registration registration object

action/callback: (your_productid)_purge_registration()

What You Need To Do

For WordPress Projects

php

\add_action( '(your_productid)_registry_refresh', array($this, 'refreshRegistration') );

You can add this and other hooks with:

$this->addSoftwareRegistryHooks();

The addSoftwareRegistryHooks() method adds:

\add_action( '(your_productid)_registry_refresh', array($this, 'refreshRegistration') ); \add_filter( '(your_productid)_is_registered', array($this, 'isValidRegistration') ); \add_filter( '(your_productid)_registration_key', array($this, 'getRegistrationKey') ); \add_filter( '(your_productid)_registration', array($this, 'getCurrentRegistration') ); \add_filter( '(your_productid)_registry_value', array($this, 'isRegistryValue'), 10, 4 );

Example:

php";

class <your_classname> implements \(your_namespace)\Interfaces\(your_productid)_registration { use \(your_namespace)\Traits\(your_productid)_registration_wordpress; ... public function __construct() { $this->addSoftwareRegistryHooks(); } }

Note:

tpl file and change the SOFTWARE_REGISTRY_FILENAME constant.

const SOFTWARE_REGISTRY_FILENAME = 'myPluginName';

For Other File Based Projects

php is called to schedule the next registration refresh. This method can be modified to schedule a cron event to execute the refresh at a future time. php <registrationKeyValue> from the command line to refresh the registration.

When left as is, the checkRegistryRefreshEvent() method uses the key file to check for a needed registration refresh.

In your class constructor or destructor add:

$this->checkRegistryRefreshEvent();

to trigger the refresh check.

Example:

php";

class <your_classname> implements \(your_namespace)\Interfaces\(your_productid)_registration { use \(your_namespace)\Traits\(your_productid)_registration_filebased; ...

public function __destruct() { /* if necessary, set HOME/USERPROFILE and/or TMP/TMPDIR/TEMP directories */ // putenv('HOME={your home directory}'); // where the registration key is stored, otherwise use $_SERVER['DOCUMENT_ROOT'] // putenv('TMP={your temp directory}'); // where the registration data is stored, otherwise use sys_get_temp_dir() $this->checkRegistryRefreshEvent(); } }

User Interface

Of course, the user interface is up to you, the developer, but you may look at (and maybe use) the registration UI trait included with {eac}Doojigger and used by {eac}SoftwareRegistry as an example.

see:

• …/Traits/swRegistrationUI.trait.php in the eacDoojigger folder.

• …/Extensions/class.eacSoftwareRegistry_registration.extension.php in the eacSoftwareRegistry folder.

See Also

-

{eac}SoftwareRegistry – Software Registration Server

-

{eac}SoftwareRegistry Custom Hooks

Copyright

Copyright © 2019-2026, EarthAsylum Consulting, distributed under the terms of the GNU GPL.

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should receive a copy of the GNU General Public License along with this program. org/licenses/.