There are 3 helpers for generating the certificates:
{shopGiftcertificatesPluginHelper::generateCertificate($params)}
- returns array of the certificate data.
You have to process the certificate data.{shopGiftcertificatesPluginHelper::generateCertificateTemplate($params)}
- returns HTML-code of the certificate template.{shopGiftcertificatesPluginHelper::generateOneCertificate($params, $validation_types, $return_template)}
- creates only one certificate depending on the validations. Returns array of data or the HTML-template. Read about the features of that helper.
The first 2 helpers create certificates on each call.
Params
In order for the certificate to be generated, you must pass the correct parameters to the helper.
Consider the array $params
:
/** * Data of the certificate to create * * array['to'] string Field "To" * array['from'] string Field "From" * array['message'] string Field "Message" * array['amount'] float Field "Amount" * array['currency'] string Field with currency * array['send'] string Field "Method of sending the certificate". Available values: email, post, user, not * array['email'] string Field "Email". Required, if parameter send = email or the email address is being checked * array['post'] array Shipping address. Required, if parameter send = post * array['post']['country'] string Country iso3letter format * array['post']['region'] int Region ID * array['post']['city'] int City name * array['post']['street'] int Street field * array['post']['postcode'] int Postcode * array['post']['phone'] string Phone * array['contact_id'] int Contact ID that the certificate is intended for. Required, if parameter send = user or the contact is being checked * array['state_id'] int Certificate state ID * array['use_limitations'] int Use the limitations or not. Available values: 1 or 0 * array['limitations'] array Limitations data * array['limitations']['expired'] string Expired date of the certificate in format: Y-m-d * array['limitations']['lifetime'] int Lifetime of the certificate in days. * array['limitations']['max'] float The maximum amount that can be spent in %. Specify values from 0 to 100 * array['limitations']['min'] array Information about the minimum order amount * array['limitations']['min']['value'] float Minimal order sum * array['limitations']['min']['currency'] string Currency of the minimal order sum * array['usage'] array Data about the usage of the certificate * array['usage']['type'] string Certificate type: disposable or multiple * array['send_notification'] int Send notifications to customer or not. Available values: 1 or 0 * array['default_template'] string Symbolic code of the default template. For example, template1 or template3 * array['template_type'] string Type of the certificate template. Available values: default or custom * If you set "custom", then the below template will be used for the certificate * array['template'] string Individual certificate template. If you use that parameter, then "template_type" automatically will be "custom". * array['free_products'] array Free products * array['free_products']['products'][] array IDs of the free products * array['free_products']['skus'][] array IDs of the free skus * * @param array $params (See the parameters above) * @return array **/ $params = [ 'to' => 'Best customer', 'from' => 'Favourite store', 'message' => '', 'amount' => '50', 'currency' => 'USD', 'send' => 'email', 'email' => 'test@test.com', 'post' => [ 'country' => 'rus', 'region' => '77', 'city' => 'Moscow', 'street' => 'street, building, apt', 'postcode' => '353535', 'phone' => '89999999999' ], 'contact_id' => 5, 'state_id' => 5, 'use_limitations' => 1, 'limitations' => [ 'expired' => '2040-10-28', 'lifetime' => 30, 'max' => 100, 'min' => [ 'value' => 20, 'currency' => 'USD' ] ], 'usage' => [ 'type' => 'disposable' ], 'send_notification' => 0, 'default_template' => 'template3', 'template_type' => 'default', 'free_products' => [ 'products' => [25, 5], 'skus' => [345, 415] ]
Consider the array $validation_types
:
/** * Types of checks to determine whether to create a certificate or not * * @param string[] $validation_types - By default the value is 'user' * Available values: * 'user' - Checks whether the user is authorized and whether a certificate has ever been generated through this helper * 'session' - Checks whether the user has a special record in the session that the certificate was generated through this helper * 'cookie' - Checks whether the user has a special record in the cookie that the certificate was generated through this helper * 'ip' - Checks whether a certificate was generated for the IP through this helper * @return array **/ $validation_types = ['user']
Consider the parameter $return_template
:
/** * Return an array of data or a certificate template * * @param bool $return_template - By default the value is false * Available values: * true - Returns certificate HTML-template * false - Returns array with the certificate data * @return bool **/ $return_template = false;
Examples
If you cannot understand why state_id
has value 19, read the article about the states.
Simple certificate with a discount $50.
{shopGiftcertificatesPluginHelper::generateCertificateTemplate([ 'amount' => '50', 'currency' => 'USD', 'state_id' => 19 ])}
Private user certificate
{shopGiftcertificatesPluginHelper::generateCertificateTemplate([ 'amount' => '50', 'currency' => 'USD', 'state_id' => 19, 'send' => 'user', 'contact_id' => $wa->user()->getId() ])}
Will only be generated for an authorized user.
Email certificate
{shopGiftcertificatesPluginHelper::generateCertificateTemplate([ 'amount' => '50', 'currency' => 'USD', 'state_id' => 19, 'send' => 'email', 'email' => $wa->user()->get('email', 'default') ])}
It will be attached to the email address.
Certificate with a lifetime of 10 days and $100.
Get an array of data and output only the certificate code.
{$certificate = shopGiftcertificatesPluginHelper::generateCertificate([ 'amount' => '50', 'currency' => 'USD', 'state_id' => 19, 'use_limitations' => 1, 'limitations' => [ 'lifetime' => 10, 'min' => [ 'value' => 100, 'currency' => 'USD' ] ] ])} {if $certificate} <p>To activate the certificate, enter the code on the checkout page: <b>{$certificate.code}</b></p> {/if}
Free products with a minimum order amount of $500 and lifetime for 10 days
{shopGiftcertificatesPluginHelper::generateCertificateTemplate([ 'state_id' => 19, 'use_limitations' => 1, 'limitations' => [ 'lifetime' => 10, 'min' => [ 'value' => 500, 'currency' => 'USD' ] ], 'free_products' => [ 'products' => [25, 5], 'skus' => [30, 45, 52] ] ])}
In this example, 5 free products are attached: 2 products, 3 skus.
A certificate that will only be generated once for the user
{shopGiftcertificatesPluginHelper::generateOneCertificate([ 'amount' => '50', 'currency' => 'USD', 'contact_id' => $wa->user()->getId(), 'state_id' => 19 ], ['user'], true)}
A certificate that will only be generated once. Checking session or cookies
Get an array of data and output only the certificate code.
{$certificate = shopGiftcertificatesPluginHelper::generateOneCertificate([ 'amount' => '50', 'currency' => 'USD', 'state_id' => 19 ], ['session', 'cookie'])} {if $certificate} <p>To activate the certificate, enter the code on the checkout page: <b>{$certificate.code}</b></p> {/if}
Certificate with custom code
Create the certificate with the code "Black friday!".
{shopGiftcertificatesPluginHelper::generateOneCertificate([ 'amount' => '50', 'code' => 'Black friday!', 'currency' => 'USD', 'contact_id' => $wa->user()->getId(), 'state_id' => 19 ], ['user'], true)}
Where it can be used?
Certificates can be generated in notifications, mailings, after successful checkout, and so on. Read more in the article examples of certificate's generating.