Moved to GitLab

This project has moved to GitLab: https://gitlab.com/samcns/perl6-Magento

Magento

Perl 6 Magento 2 API client module.

• Features
• Getting started
• Module usage
  • Response format
  • Error messages
  • Search critera
  • Custom API endpoints
  • Custom API endpoints
• CLI usage
• Config
  • Config variables
• Installation
• Todo
• Requirements
• Troubleshooting
• Authors
• License
• See also

Features

• Magento 2 compatable: Works with the latest Magento 2 API
• Integration token support: Can utilize Integration tokens for authentication
• Admin & Customer token support: Supports username / password authentication for access token generation
• Use Perl 6 hash for search critera: Write complex search criteria queries as Perl 6 Hash

Getting started

For long-use Integration Access Token usage use the 6mag init command:

6mag init

Enter your Magento installation base URL (e.g. https://my.magento), store identifier (e.g. default), and Integration Access Token (generated in Magento > System > Integrations).

By default this will generate the file ~/.6mag/config.yml:

---
host: "https://my.magento"
store: default
access_token: ********************************

Module Usage

All subroutines are documented in docs/Subroutines.md.

Using long-use Integration Access Token from ~/.6mag/config.yml:

use Magento::Config;
use Magento::Customer;

my %config = Magento::Config::from-file;

#GET    /V1/customers/:customerId
say customers %config, id => 1;

Using pre-generated Access Token without ~/.6mag/config.yml:

use Magento::Customer;

my $host   = 'https://my.magento';
my %config = %{
    host         => $host,
    access_token => '********************************',
    store        => 'default'
}

#GET    /V1/customers/:customerId
say customers %config, id => 1;

Using password authentication as Admin:

use Magento::Auth;
use Magento::Customer;

my $host   = 'https://my.magento';
my %config = %{
    host         => $host,
    access_token => request-access-token(username => 'admin', password => '****', :$host),
    store        => 'default'
}

#GET    /V1/customers/:customerId
say customers %config, id => 1;

Using password authentication as Customer:

use Magento::Auth;
use Magento::Customer;

my $host         = 'https://my.magento';
my $access_token = 
    request-access-token(
        :$host,
        username  => '[email protected]',
        password  => '****',
        user_type => 'customer');

my %config = %{:$host, :$access_key, store => 'default'};

#GET    /V1/customers/me
say customers-me %config;

Response format

By default, all responses are returned as Perl 6 variables. To return the raw json or xml body add the following to your config Hash:

my %config = %{
    host         => $host,
    access_token => '********************************',
    store        => 'default',
    format       => 'json',
    # or
    format       => 'xml'
}

Error messages

For a successful request only the relevant data will be returned from the server response. For example, only the cart_id value will be returned when a new cart is successfully created on the server.

When an error occurs, the response will return a Perl 6 Hash with a message and status pair, like this:

%{
    message => 'Cannot assign customer to the given cart. Customer already has active cart.',
    status  => 400
}

Search criteria

Use a Perl 6 Hash to define search criteria:

use Magento::Config;
use Magento::Customer;

my %config = Magento::Config::from-file;

my %customer_search_criteria = %{
    searchCriteria => %{
        filterGroups => [
            {
                filters => [
                    {
                        field => 'email',
                        value => '[email protected]',
                        condition_type => 'eq'
                    },
                ]
            },
        ],
        current_page => 1,
        page_size    => 10
    }
}

# Do a customer search using the search criteria hash
say customers-search %config, search_criteria => %customer_search_criteria;

search-criteria Helper routine

In addition to the Hash approach above, you can also use the search-critera helper routine from Magento::Utils. This creates a search criteria Hash using more condensed notation.

Only the initial Array is required. The conditions named argument is optional.

use Magento::Utils;

# Single filter
my %critera = search-critera
    # field   value                      condition_type
    ['email', '[email protected]', 'eq'],
    conditions => %{
        current_page => 1,
        page_size    => 10
    }

# Logical AND filter
my %criteria = search-critera
    [
        ['email', '[email protected]', 'eq'],
        ['email', '[email protected]', 'eq'],
    ],
    conditions => %{
        current_page => 1,
        page_size    => 10
    }

# Logical OR
my %criteria = search-critera
    [
        [
            ['email', '[email protected]', 'eq'],
            ['email', '[email protected]', 'eq'],
        ],
        [
            ['email', '[email protected]', 'eq'],
            ['email', '[email protected]', 'eq'],
        ],
    ],
    conditions => %{
        current_page => 1,
        page_size    => 10
    }

Custom API endpoints

You can use the request subroutine directly to make requests against custom API endpoints:

use Magento::HTTP;
use JSON::Fast;

# GET
Magento::HTTP::request
    method  => 'GET',
    config  => %config,
    uri     => "myCustom/endpoint/123";

# POST/PUT/DELETE
Magento::HTTP::request
    method  => 'POST', # or PUT / DELETE
    config  => %config,
    uri     => "myCustom/endpoint",
    content => to-json %content-hash;

CLI Usage

Usage:
  6mag init         - Generate Integration token based config
  6mag print-config - Print Integration token config
  6mag version      - Print 6mag version and exit

Optional arguments:
  
  --config=         - Specify a custom config file location
                      Default is `~/.6mag/config.yml`

  e.g. 6mag --config=path/to/config.yml init 

Config

Each project has its own config.yml which uses the following format:

---
host: "https://my.magento"
store: default
access_token: ********************************
format: json
version: V1

Config variables

Config variables are defined in config.yml:

Required

• host: Magento base URL
• access_token: Magento access token. For long-use configurations, integrations, use an Integration Access Token.

Optional

• format: By default all results are returned as Perl 6 variables. You can specify json or xml with this variable to return the raw response body in either format.
• store: Store identifier, defaults to default.
• version: Magento API version, defaults to V1.

Installation

git clone https://github.com/scmorrison/perl6-Magento.git
cd perl6-Magento/
zef install .

Installation issue? See Troubleshooting.

Todo

• More tests
• More API endpoints

Requirements

• Perl 6

Troubleshooting

• Errors installing from previous version:

  Remove the zef tmp / store perl6-Magento.git directories:

  # Delete these folders from your zef install 
  # directory.
  rm -rf ~/.zef/store/perl6-Magento.git ~/.zef/tmp/perl6-Magento.git 
  

  In some instances it might help to delete your local ~/.perl6/precomp directory.

Authors

• Sam Morrison

License

This Perl 6 Magento module is free software; you can redistribute it and/or modify it under the terms of the Artistic License 2.0. (Note that, unlike the Artistic License 1.0, version 2.0 is GPL compatible by itself, hence there is no benefit to having an Artistic 2.0 / GPL disjunction.) See the file LICENSE for details.

See also

• Magento