Welcome Guest

Zend Framework 3 / Laminas Mailchimp api V3 Integration Module

This module integrates with the mailchimp api.

Table of contents

Installation Return to top

With Composer Return to top

  1. In the root of your application enter:
    $ composer require krytenuk/mailchimp

Post installation Return to top

  1. Enable it in your `application.config.php` or `modules.config.php` file.
    For ZF2 add to your `application.config.php` file.
    <?php
            return array(
                'modules' => array(
                    // ...
                    'FwsMailchimp',
            ),
                // ...
            );
    For ZF3 add to your `modules.config.php` file.
    <?php
            return [
                'FwsMailchimp',
                // ...
            ];
  2. Copy `./vendor/krytenuk/mailchimp/config/fwsmailchimp.local.php.dist` to `./config/autoload/fwsmailchimp.local.php`.
  3. In `./config/autoload/fwsmailchimp.local.php` change the following.
    <?php
            return array(
                'fwsMailchimp' => array(
                    'apikey' => 'your mailchimp api key here',
                    'listId' => 'your mailchimp list id here',
            ),
        );         Your Mailchimp api key can be created/found in your Mailchimp admin area, to login goto https://login.mailchimp.com/. Once logged in goto Account (top right) and then select Extras -> API Keys.
    Your list id can be found in your members list. Goto Lists and select the list you wish to use then goto Settings -> List Name and Defaults.

Usage Return to top

As of version 0.2.0 FwsMailchimp supports the manipulation of members (subscribers to a mailing list) and interest categories (groups).
FwsMailchimp uses entities to send and receive data to and from the mailchimp api and an array collection to hold multiple entities.

Member Manipulation Return to top

To use the member functions you must retrieve the "FwsMailchimp\Members" class from the service manager. <?php
    use FwsMailchimp\Members;
    // ...
    $membersClass = $serviceManager->get(Members::class); // ideally should be injected from your factory

"FwsMailchimp\Members" has the following public methods:

listMembers() Gets all members in list.
getMember($emailAddress) Gets a member by email address.
add(MembersEntity $member) Adds a new member to the list.
subscribe($emailAddress) Sets member status to "subscribed", member will receive mailchimp emails.
unsubscribe($emailAddress) Sets member status to "unsubscribed", member will not receive mailchimp emails.
remove($emailAddress)
archive($emailAddress) 		Soft deletes a member from the list.
removePermanent($emailAddress) Permanently delete a member from the list.
update(MembersEntity $member) Changes members details.
setListId($listId) Changes the list id from that set in the config
getClientIpAddress() Gets the members ip address

Listing all members Return to top

To retrieve all the members in a list use: <?php
    // ...
    $members = $membersClass->listMembers();
    // ...

This returns either a "FwsMailchimp\Collections\ArrayCollection" of "FwsMailchimp\Entities\Members" entities on success or null if no members found. This function also returns null if an error occurred.
The "FwsMailchimp\Collections\ArrayCollection" implements the PHP "Iterator" interface and as such can be manipulated as a PHP array using functions such as foreach().

To retrieve the members use something like: <?php
    // ...
    if ($members->isEmpty() === false) {
        foreach ($members as $memberEntity) {
            // do something with the member entity
        }
    }
    // ...

Get a member by email address Return to top

To retrieve an individual member use: <?php
    // ...
    $memberEntity = $membersClass->getMember($emailAddress);
    // ...

This returns a "FwsMailchimp\Entities\Members" entity on success or null on no member found. This function also returns null if an error occurred.

Add a new member to the list Return to top

To add a new member to the list you must first create a "FwsMailchimp\Entities\Members" entity: <?php
    use FwsMailchimp\Entities\Members as MembersEntity;
    // ...
    $memberEntity = new MembersEntity();
    $memberEntity->setEmailAddress('member@emailaddress')
        ->setEmailType('html')
        ->setStatus('subscribed')
        ->setMergeFields(array(
                'FNAME' => 'Firstname',
                'LNAME' => 'Lastname',
        ))
        ->setVip(true);
    $add = $membersClass->add($memberEntity);
    // ...

This function returns true on success or false on failure, see handling errors.
You can also "subscribe" the member using the "setStatus()" in the entity, the code above shows this. "setMergeFields()" function in the entity sets the merge fields as set in your mailchimp list, to set the list merge fields goto your mailchimp list and select Settings -> List fields and *|MERGE|* tags.

Subscribe a member to the list Return to top

Subscribing a member to the list simply changes their status to "subscribed", the member must already exist on the list for this to work, see add a member to the list: <?php
    // ...
    $member = $membersClass->subscribe($emailAddress);
    // ...

This function returns a "FwsMailchimp\Entities\Members" entity on success or null on failure, see handling errors.

Unsubscribe a member from the list Return to top

Unsubscribing a member from the list simply changes their status to "unsubscribed", it does not delete the member. The member must already exist on the list for this to work, see add a member to the list: <?php
    // ...
    $member = $membersClass->unsubscribe($emailAddress);
    // ...

This function returns a "FwsMailchimp\Entities\Members" entity on success or null on failure, see handling errors.

Soft delete a member from the list Return to top

To soft delete (archive) a member from the list simply use: <?php
    // ...
    $success = $membersClass->remove($emailAddress);
    // ... or <?php
    // ...
    $success = $membersClass->archive($emailAddress);
    // ...

This function returns true on success or false on failure, see handling errors.

Permanently delete a member from the list Return to top

Warning: Members that are permanently deleted cannot be added again through the Mailchimp API

To permanently delete a member from the list simply use: <?php
    // ...
    $success = $membersClass->removePerminant($emailAddress);
    // ...

This function returns true on success or false on failure, see handling errors.

Updating a members details Return to top

To update a members details you must first retrieve a member: <?php
    // ...
    $memberEntity = $membersClass->getMember($emailAddress);
    // change the member entity as required
    $success = $membersClass->update($memberEntity);
    // ...

This function returns true on success or false on failure, see handling errors.

Get the list id Return to top

To get the list id simply use: <?php
    // ...
    $listId = $membersClass->getListId();
    // ...

This function returns a string

Set/Change the list id Return to top

To change the list id set in the config simply use: <?php
    // ...
    $membersClass->setListId($listId);
    // ...

This function accepts a string and returns the "FwsMailchimp\Members" class.

Get the members ip address Return to top

This function is useful in a signup form as the members ip address is logged by the server.
This function is not useful however, if used in an admin environment as it will contain the admins id and not the member.

To get the members ip address: <?php
    // ...
    $ipAddress = $membersClass->getClientIpAddress();
    // ...

This function returns a string

Interest manipulation Return to top

To use the interest functions you must retrieve the "FwsMailchimp\Interests" class from the service manager. <?php
    use FwsMailchimp\Interests;
    // ...
    $interestsClass = $serviceManager->get(Interests::class); // ideally should be injected from your factory

This class pre-loads the interest categories.

"FwsMailchimp\Interests" has the following public methods:

refresh() Reloads the interests list.
listInterestCategories() Lists all the interest categories
getInterestCategory($interestCategoryId) Gets interest category by category id
findInterestCategory($interestId) Gets an interest category by interest id
listCategoryInterests($interestCategoryId) Lists all interests in specified category
getInterest($interestId) Gets the specified interest
setListId($listId) Changes the list id from that set in the config

Refresh/reload the interest categories list Return to top

To refresh the list simply use: <?php
    // ...
    $interestsClass->refresh();
    // ...

This function returns true on success or false on failure, see handling errors.

List all the interest categories Return to top

To get a list of all the interest categories simply use: <?php
    // ...
    $interestCategories = $interestsClass->listInterestCategories();
    // ...

This returns either a "FwsMailchimp\Collections\ArrayCollection" of "FwsMailchimp\Entities\InterestCategories" entities on success or null if no interest categories exist in list.
The "FwsMailchimp\Collections\ArrayCollection" implements the PHP "Iterator" interface and as such can be manipulated as a PHP array using functions such as foreach().

To retrieve the interest categories and the interests use something like: <?php
    // ...
    if ($interestCategories->isEmpty() === false) {
        foreach ($interestCategories as $interestCategoryEntity) {
            // do something with the interest category entity
            $interests = $interestCategoryEntity->getInterests();
            if ($interests->isEmpty() === false) {
                foreach ($interests as $interestEntity) {
                    // do something with the interest entity
                }
            }
        }
    }
    // ...

Get an interest category by interest category id Return to top

To get a specific interest category by interest category id simply use: <?php
    // ...
    $interestCategoryEntity = $interestsClass->getInterestCategory($interestCategoryId);
    // ...

This returns either a "FwsMailchimp\Entities\InterestCategories" entity on sucess or null if no interest category found.

To retrieve the interests use something like: <?php
    // ...
    if ($interestCategoryEntity->hasInterests()) {
        foreach ($interestCategoryEntity->getInterests() as $interestEntity) {
            // do something with the interest entity
        }
    }
    // ...

Get an interest category by interest id Return to top

To get a specific interest category by interest id simply use: <?php
    // ...
    $interestCategoryEntity = $interestsClass->findInterestCategory($interestId);
    // ...

This returns either a "FwsMailchimp\Entities\InterestCategories" entity on success or null if no interest category found.

To retrieve the interests use something like: <?php
    // ...
    if ($interestCategoryEntity->hasInterests()) {
        foreach ($interestCategoryEntity->getInterests() as $interestEntity) {
            // do something with the interest entity
        }
    }
    // ...

List all interests in specified category Return to top

To get a categories interests simply use: <?php
    // ...
    $interests = $interestsClass->listCategoryInterests($interestCategoryId);
    // ...

This returns either a "FwsMailchimp\Collections\ArrayCollection" of "FwsMailchimp\Entities\Interests" entities on sucess or null if no interests found.

To retrieve the interests use something like: <?php
    // ...
    if ($interests->isEmpty() === false) {
        foreach ($interests as $interestEntity) {
            // do something with the interest entity
        }
    }
    // ...

Get the specified interest Return to top

To get specific interest simply use: <?php
    // ...
    $interestEntity = $interestsClass->getInterest($interestId);
    // ...

This returns either a "FwsMailchimp\Entities\Interests" entity on sucess or null if no interest found.

Get the list id Return to top

To get the list id simply use: <?php
    // ...
    $listId = $interestsClass->getListId();
    // ...

This function returns a string

Set/Change the list id Return to top

To change the list id set in the config simply use:: <?php
    // ...
    $interestsClass->setListId($listId);
    // ...

This function accepts a string and returns the "FwsMailchimp\Interests" class.

Entities Return to top

As mentioned earlier all data recieved from mailchimp is hydrated into entities. This creates a standardised, object oriented data structure.
An entity is a person, place, thing or concept about which data can be collected. Each entity is made up of a number of attributes which represent that entity.
Entities are classes of getters and setters to retrieve and set data.

Members entity Return to top

The "FwsMailchimp\Entities\Members" entity holds the members data to be processed.
To get a members entity you must either get an existing mailchimp member or create a new one, to get an existing member see "Get a member by email address"
To create a new member entity use: <?php
    // ...
    use FwsMailchimp\Entities\Members as MemberEntity;
    // ...
    $memberEntity = new MemberEntity();
    // ...

"FwsMailchimp\Entities\Members" entity has the following public methods:

Getters

getId() Gets the members id
getEmailAddress() Gets the members email address
getMergeFields() Gets the merge field data for the member
getUniqueEmailId() Gets the identifier for the address across all of MailChimp
getEmailType() Gets the email type
getStatus() Gets the members subscribe status
getInterestCategories() Gets the member interests sorted into categories
getInterests() Gets the member interests as array
getStats() Gets open and click rates for member
getIpSignup() Gets the IP address the member signed up from
getTimestampSignup() Gets the date and time the member signed up for the list
getIpOpt() Gets the IP address the member used to confirm their opt-in status
getTimestampOpt() Gets the date and time the member confirmed their opt-in status
getMemberRating() Gets the member rating
getLastChanged() Gets the date and time the members info was last changed
getLanguage() Gets the member language
isVip() Determine if the member is VIP
getEmailClient() Gets the members email client
getLocation() Gets the members location
getListId() Gets the list id to which member is registered
getValidSubscribeStatus() Get all valid subscribe status
getValidEmailTypes() Gets a list of all valid email types
toArray() Returns member object as an array compatible with mailchimp api

Setters

setEmailAddress($emailAddress) Sets the members email address
setMergeFields(Array $mergeFields) Sets the merge fields
setEmailType($emailType) Sets the members email type
setStatus($status) Sets the members subscribed status
setInterested($interestId) Sets a members enthusiasm in an interest
unsetInterested($interestId) Removes a members enthusiasm in an interest
setIpSignup($ipSignup) Sets the IP address the member signed up from
setTimestampSignup($timestampSignup) Sets the date and time the member signed up for the list
setIpOpt($ipOpt) Sets the IP address the member used to confirm their opt-in status
setTimestampOpt($timestampOpt) Sets the date and time the subscribe confirmed their opt-in status
setLanguage($language) Sets the members language
setVip($vip) Sets the members VIP status
setLocation(LocationEntity $location) Sets the members location

Get the members id Return to top

<?php
    // ...
    $id = $memberEntity->getId();
    // ...

This function returns a string.

Get the members email address Return to top

<?php
    // ...
    $mailAddress = $memberEntity->getEmailAddress();
    // ...

This function returns a string.

Get the members merge fields Return to top

<?php
    // ...
    $mergeFields = $memberEntity->getMergeFields();
    // ...

This function returns as array.

<?php
    array(
        'MERGEFIELDNAME' => 'value',
    );

Get the members unique email id Return to top

<?php
    // ...
    $uniqueEmailId = $memberEntity->getUniqueEmailId();
    // ...

This function returns a string.

Get the members email type Return to top

<?php
    // ...
    $emailType = $memberEntity->getEmailType();
    // ...

This function returns a string, "html" or "text".

Get the members subscribe status Return to top

<?php
    // ...
    $status = $memberEntity->getStatus();
    // ...

This function returns a string, "subscribed", "unsubscribed", "cleaned", "pending" or "transactional".

Get the members interest categories Return to top

<?php
    // ...
    $interestCategories = $memberEntity->getInterestCategories();
    // ...

This function returns the "FwsMailchimp\Collections\ArrayCollection" class of "FwsMailchimp\Entities\InterestCategories" entities.

To retrieve the interest categories and the interests use something like: <?php
    // ...
    if ($interestCategories->isEmpty() === false) {
        foreach ($interestCategories as $interestCategoryEntity) {
            // do something with the interest category entity
            if ($interestCategoryEntity->hasInterests()) {
                foreach ($interestCategoryEntity->getInterests() as $interestEntity) {
                    // do something with the interest entity
                }
            }
        }
    }
    // ...

Get the members interests Return to top

<?php
    // ...
    $interests = $memberEntity->getInterests();
    // ...

This function returns an array.

<?php
    array(
        'interestid' => true/false, // true or false depending on if the member is enthusiastic about the interest
    );

Get open and click rates for member Return to top

<?php
    // ...
    $stats = $memberEntity->getStats();
    // ...

This function returns a "FwsMailchimp\Entities\MemberStats" entity.

Get the IP address the member signed up from Return to top

<?php
    // ...
    $ipSignup = $memberEntity->getIpSignup();
    // ...

This function returns a string.

Get the date and time member signed up Return to top

<?php
    // ...
    $timestampSetup = $memberEntity->getTimestampSignup();
    // ...

This function returns a PHP "DateTime" class or null.

Get the IP address the member used to confirm their opt-in status Return to top

<?php
    // ...
    $ipOpt = $memberEntity->getIpOpt();
    // ...

This function returns a string.

Get the date and time the member confirmed their opt-in status Return to top

<?php
    // ...
    $timestampOpt = $memberEntity->getTimestampOpt();
    // ...

This function returns a PHP "DateTime" class or null.

Get the member rating Return to top

<?php
    // ...
    $rating = $memberEntity->getMemberRating();
    // ...

This function returns a integer from 1 to 5.

Get the date and time the members info was last changed Return to top

<?php
    // ...
    $lastChanged = $memberEntity->getLastChanged();
    // ...

This function returns a PHP "DateTime" class or null.

This function returns a string.

Get the members language if set Return to top

<?php
    // ...
    $language = $memberEntity->getLanguage();
    // ...

This function returns a "FwsMailchimp\Entities\Languages" entity.

Determine if the member is VIP Return to top

<?php
    // ...
    $vip = $memberEntity->isVip();
    // ...

This function returns true or false.

Gets the members email client if set Return to top

<?php
    // ...
    $emailClient = $memberEntity->getEmailClient();
    // ...

This function returns a string.

Get the members location Return to top

<?php
    // ...
    $location = $memberEntity->getLocation();
    // ...

This function returns a "FwsMailchimp\Entities\Locations" entity.

Get the list id to which member is registered Return to top

<?php
    // ...
    $listId = $memberEntity->getListId();
    // ...

This function returns a string.

Get all the valid subscribe states Return to top

<?php
    // ...
    $validSubscribeStates = $memberEntity->getValidSubscribeStates();
    // ...

This function returns an array of valid subscribe states, see getStatus() and setStatus()

Get all the valid email types Return to top

<?php
    // ...
    $validEmailTypes = $memberEntity->getValidEmailTypes();
    // ...

This function returns as array of valid subscribe states, see getEmailType() and setEmailType()

Get the members details as an array for use in the mailchimp api Return to top

<?php
    // ...
    $memberArray = $memberEntity->toArray();
    // ...

This function returns an array.

Set the members email address Return to top

<?php
    // ...
    $memberEntity->setEmailAddress($emailAddress);
    // ...

This function accepts a string.

Set the merge fields Return to top

<?php
    // ...
    $memberEntity->setMergeFields(Array $mergeFields);
    // ...

This function accepts a array.

<?php
    // ...
    $memberEntity->setMergeFields(array(
        'MERGEFIELD1' => 'value1',
        'MERGEFIELD2' => 'value2',
        // ...
    ));
    // ...

Set the members email type Return to top

<?php
    // ...
    $memberEntity->setEmailType($emailType);
    // ...

This function accepts a string, "html" or "text".
This function can also throw a "IncorrectTypeException" if an incorrect type is set.

Set the members subscribe status Return to top

<?php
    // ...
    $memberEntity->setStatus($status);
    // ...

This function accepts a string, "subscribed", "unsubscribed", "cleaned", "pending" or "transactional".
This function can also throw a "IncorrectTypeException" if an incorrect status is set.

Set the members enthusiasm for an interest Return to top

<?php
    // ...
    $memberEntity->setInterested($interestId);
    // ...

This function accepts a string. This must be a valid interest id for the list, see Interest manipulation

Unset the members enthusiasm for an interest Return to top

<?php
    // ...
    $memberEntity->unsetInterested($interestId);
    // ...

This function accepts a string. This must be a valid interest id for the list, see Interest manipulation

Set the IP address the member signed up from Return to top

<?php
    // ...
    $memberEntity->setIpSignup($ipSignup);
    // ...

This function accepts a string.

Set the date and time the member signed up for the list Return to top

<?php
    // ...
    $memberEntity->setTimestampSignup($timestampSignup);
    // ...

This function accepts either a PHP "DateTime" class or a string that can be converted to a "DateTime" class.
This function can also throw a "IncorrectTypeException" if an incorrect variable type is set.

Set the IP address the member used to confirm their opt-in status Return to top

<?php
    // ...
    $memberEntity->setIpOpt($ipOpt);
    // ...

This function accepts a string.

Set the date and time the subscribe confirmed their opt-in status Return to top

<?php
    // ...
    $memberEntity->setTimestampOpt($timestampOpt);
    // ...

This function accepts either a PHP "DateTime" class or a string that can be converted to a "DateTime" class.
This function can also throw a "IncorrectTypeException" if an incorrect variable type is set.

Set the members language Return to top

<?php
    // ...
    $memberEntity->setLanguage($language);
    // ...

This function accepts a "FwsMailchimp\Entities\Languages" entity.

Set the members VIP status Return to top

<?php
    // ...
    $memberEntity->setVip($vip);
    // ...

This function accepts a boolean value.

Sets the members location Return to top

<?php
    // ...
    $memberEntity->setLocation($location);
    // ...

This function accepts a "FwsMailchimp\Entities\Locations" entity.

Languages entity Return to top

The "FwsMailchimp\Entities\Languages" entity holds the members language data to be processed.
To get a language entity you can simply retrieve it from a members entity: <?php
    // ...
    $languageEntity = $memberEntity->getLanguage();
    // ... To get a members entity see "Members entity"

"FwsMailchimp\Entities\Languages" entity has the following public methods:

Getters

getId() Get the members language id
getLanguage() Get the members language
getValidLanguageCodes() Get all the valid language codes
toArray() Get the members language as an array

Setters

setId() Set the members language id

Get the members language id if set Return to top

<?php
    // ...
    $id = $languageEntity->getId();
    // ...

This function returns a string, the mailchimp language code

Get the members language if set Return to top

<?php
    // ...
    $language = $languageEntity->getLanguage();
    // ...

This function returns a string

Get all the valid language codes Return to top

<?php
    // ...
    $validLanguageCodes = $languageEntity->getValidLanguageCodes();
    // ...

This function returns an array of valid language codes, see getLanguage(), getId() and setId()

Get the members language as an array Return to top

<?php
    // ...
    $memberArray = $languageEntity->toArray();
    // ...

This function returns an array.

Set the members language id Return to top

<?php
    // ...
    $languageEntity->setId($languageId);
    // ...

This function accepts a string, see getValidLanguageCodes()

Member Stats entity Return to top

The "FwsMailchimp\Entities\MemberStats" entity holds the members open and click rate statistics, this entity is read only.
To get a member stats entity you can simply retrieve it from a members entity: <?php
    // ...
    $memberStatsEntity = $memberEntity->getStats();
    // ... To get a members entity see "Members entity"

"FwsMailchimp\Entities\MemberStats" entity has the following public methods:

Getters

getAvgOpenRate() Gets the members average open rate
getAvgClickRate() Get the members average click-through rate

Get the members average open rate Return to top

<?php
    // ...
    $language = $memberStatsEntity->getAvgOpenRate();
    // ...

This function returns a number

Get the members average click-through rate Return to top

<?php
    // ...
    $language = $memberStatsEntity->getAvgClickRate();
    // ...

This function returns a number

Locations entity Return to top

The "FwsMailchimp\Entities\Locations" entity holds the members location data.
To get a location entity you can simply retrieve it from a members entity: <?php
    // ...
    $locationEntity = $memberEntity->getLocation();
    // ... To get a members entity see "Members entity"

"FwsMailchimp\Entities\Locations" entity has the following public methods:

Getters

getLatitude() Gets the location latitude
getLongitude() Gets the location longitude
getGmtoff() Gets the time difference in hours from GMT
getDstoff() Gets the offset for timezones where daylight saving time is observed
getCountryCode() Gets the unique code for the location country
getTimezone() Gets the timezone for the location
toArray() Returns location object as an array compatible with mailchimp api

Setters

setLatitude($latitude) Sets the location latitude
setLongitude($longitude) Sets the location longitude

Get the location latitude Return to top

<?php
    // ...
    $latitude = $locationEntity->getLatitude();
    // ...

This function returns a number

Get the location longitude Return to top

<?php
    // ...
    $longitude = $locationEntity->getLongitude();
    // ...

This function returns a number

Get the time difference in hours from GMT Return to top

<?php
    // ...
    $gmtoff = $locationEntity->getGmtoff();
    // ...

This function returns a integer

Get the offset for timezones where daylight saving time is observed Return to top

<?php
    // ...
    $dstoff = $locationEntity->getDstoff();
    // ...

This function returns a integer

Get the unique code for the location country Return to top

<?php
    // ...
    $countryCode = $locationEntity->getCountryCode();
    // ...

This function returns a string

Get the timezone for the location Return to top

<?php
    // ...
    $timezone = $locationEntity->getTimezone();
    // ...

This function returns a string

Get location object as an array compatible with mailchimp api Return to top

<?php
    // ...
    $locationArray = $locationEntity->toArray();
    // ...

This function returns a array

Set the location latitude Return to top

<?php
    // ...
    $locationEntity->setLatitude($latitude);
    // ...

This function accepts a number

Set the location longitude Return to top

<?php
    // ...
    $locationEntity->setLongitude($longitude);
    // ...

This function accepts a number

Interest Categories entity Return to top

The "FwsMailchimp\Entities\InterestCategories" entity holds the interest category data to be processed, this entity is read only.
To get an interest category entity you must get an existing mailchimp interest category, see "List all the interest categories", "Get an interest category by interest category id" and "Get an interest category by interest id"

"FwsMailchimp\Entities\InterestCategories" entity has the following public methods:

Getters

getId() Gets the category id
getListId() Gets the mailchimp list id
getTitle() Gets the category's title
getDisplayOrder() Gets the category's display order
getType() Determines how this category's interests appear on mailchimp signup forms
getInterests() Gets the category's interests
getValidTypes() Gets all the valid category types
toArray() Returns interest category object as an array compatible with mailchimp api

Get the category id Return to top

<?php
    // ...
    $categoryId = $interestCategoryEntity->getId();
    // ...

This function returns a string

Get the mailchimp list id Return to top

<?php
    // ...
    $listId = $interestCategoryEntity->getListId();
    // ...

This function returns a string, see "Post installation" and "Set/Change the list id"

Get the category's title Return to top

<?php
    // ...
    $categoryTitle = $interestCategoryEntity->getTitle();
    // ...

This function returns a string

Get the category's display order Return to top

<?php
    // ...
    $categoryDisplayOrder = $interestCategoryEntity->getDisplayOrder();
    // ...

This function returns a integer

Determines how this category's interests appear on mailchimp signup forms Return to top

<?php
    // ...
    $categoryType = $interestCategoryEntity->getType();
    // ...

This function returns a string

Get the category's interests Return to top

<?php
    // ...
    $interests = $interestCategoryEntity->getInterests();
    // ...

This function returns an "FwsMailchimp\Collections\ArrayCollection" of "FwsMailchimp\Entities\Interests" entities

To retrieve the interests use something like:

 <?php
    // ...
    if ($interests->isEmpty() === false) {
        foreach ($interests as $interestEntity) {
            // do something with the interest entity
        }
    }
    // ...

Get all the valid category types Return to top

<?php
    // ...
    $validTypes = $interestCategoryEntity->getValidTypes();
    // ...

This function returns an array of valid category types, see getType()

Get the interest category details as an array for use in the mailchimp api Return to top

<?php
    // ...
    $categoryType = $interestCategoryEntity->toArray();
    // ...

This function returns an array

Interests entity Return to top

The "FwsMailchimp\Entities\Interests" entity holds the interests data to be processed, this entity is read only.
To get an interest entity you must get an existing mailchimp interest, see "List all the interest categories", "Get an interest category by interest category id", "Get an interest category by interest id", "List all interests in specified category" and "Get the specified interest"

"FwsMailchimp\Entities\Interests" entity has the following public methods:

Getters

getId() Gets the interest id
getCategoryId() Get the interest category id
getListId() Gets the mailchimp list id
getName() Get the interest's name
getSubscriberCount() Get the interest's subscriber count
getDisplayOrder() Get the interest's display order
toArray() Returns interest category object as an array compatible with mailchimp api

Get the interest id Return to top

<?php
    // ...
    $interestId = $interestEntity->getId();
    // ...

This function returns a string

Get the interest category id Return to top

<?php
    // ...
    $categoryId = $interestEntity->getCategoryId();
    // ...

This function returns a string

Get the mailchimp list id Return to top

<?php
    // ...
    $listId = $interestEntity->getListId();
    // ...

This function returns a string, see "Post installation" and "Set/Change the list id"

Get the interest's name Return to top

<?php
    // ...
    $name = $interestEntity->getName();
    // ...

This function returns a string

Get the interest's subscriber count Return to top

<?php
    // ...
    $subscriberCount = $interestEntity->getSubscriberCount();
    // ...

This function returns a integer

Get the interest's display order Return to top

<?php
    // ...
    $displayOrder = $interestEntity->getDisplayOrder();
    // ...

This function returns a integer

Get the interest details as an array for use in the mailchimp api Return to top

<?php
    // ...
    $interestsArray = $interestEntity->toArray();
    // ...

This function returns an array

Array Collections Return to top

The "FwsMailchimp\Collections\ArrayCollection" implements the PHP "Iterator" interface and as such can be manipulated as a PHP array using functions such as foreach().
To create a new array collection use: <?php
    // ...
    use FwsMailchimp\Collections\ArrayCollection;
    // ...
    $collection = new ArrayCollection();
    // ...

The "FwsMailchimp\Collections\ArrayCollection" is designed to handle "FwsMailchimp\Entities".

"FwsMailchimp\Collections\ArrayCollection" entity has the following public methods:

add() Add entity to collection
set() Set an entity in collection
get() Get an entity from a collection by it's id
remove() Remove entity from collection by it's key
removeElement() Remove entity from collection
count() Count entities in a collection
isEmpty() Check if collection is empty
key() Return key of current collection element
next() Increase key to next element in collection
current() Return current element in collection
rewind() Reset key in collection to first element
valid() Check current element is a valid entity
toArray() Convert collection to an array

Adding an entity to a collection Return to top

<?php
    // ...
    $collection->add($entity);
    // ...

This function returns the "FwsMailchimp\Collections\ArrayCollection" object

Setting/overwriting an entity in a collection Return to top

<?php
    // ...
    $collection->set($key, $entity);
    // ...

This function returns the "FwsMailchimp\Collections\ArrayCollection" object

Get an entity from a collection by it's id Return to top

<?php
    // ...
    $entity = $collection->get($id);
    // ...

This function returns an entity implementing "FwsMailchimp\Entities\EntityInterface"

Removing an entity from a collection by it's key Return to top

<?php
    // ...
    $success = $collection->remove($key);
    // ...

This function returns true or false

Removing an entity from a collection Return to top

<?php
    // ...
    $success = $collection->removeElement($entity);
    // ...

This function returns true or false

Counting entities in a collection Return to top

<?php
    // ...
    $count = $collection->count();
    // ...

This function returns a integer

Determine if a collection is empty Return to top

<?php
    // ...
    $empty = $collection->isEmpty();
    // ...

This function returns a true or false

Return key of current collection element Return to top

<?php
    // ...
    $key = $collection->key();
    // ...

This function returns an integer

Increase key to next element in collection Return to top

<?php
    // ...
    $collection->next();
    // ...

This function does not return a value

Return current element in collection Return to top

<?php
    // ...
    $entity = $collection->current();
    // ...

This function returns an entity implementing "FwsMailchimp\Entities\EntityInterface"

Reset key in collection to first element Return to top

<?php
    // ...
    $collection->rewind();
    // ...

This function does not return a value

Check current element is a valid entity Return to top

<?php
    // ...
    $valid = $collection->valid();
    // ...

This function returns true or false

Return entities as an array Return to top

<?php
    // ...
    $entitiesArray = $collection->toArray();
    // ...

This function returns an array

Handling Errors Return to top

Handling errors in FwsMailchimp is fairly straight forward, this section applies to:

If an error occurs it is logged by "FwsMailchimp".

Determine if error(s) occurred Return to top

<?php
    // ...
    $errors = $fwsMailchimpObject->hasErrors();
    // ...

This function returns true or false

Retrieving the error log Return to top

<?php
    // ...
    $errorsArray = $fwsMailchimpObject->getErrors();
    // ...

This function returns an array

Clearing the error log Return to top

<?php
    // ...
    $fwsMailchimpObject->clearErrors();
    // ...

This function returns the calling object

Working Examples Return to top

Below are a few examples of how to use "FwsMailchimp"

Creating a new member Return to top

 <?php
    use FwsMailchimp\Members;
    use FwsMailchimp\Entities\Members as MemberEntity;
    use DateTime;
    // ...
    $membersClass = $serviceManager->get(Members::class); // ideally should be injected from your factory
    // ...
    $memberIpAddress = $membersClass->getClientIpAddress();

    $signupDate = new DateTime('now');

    $memberEntity = new MembersEntity();
    $memberEntity->setEmailAddress('member@emailaddress')
        ->setEmailType('html')
        ->setStatus('subscribed')
        ->setMergeFields(array(
                'FNAME' => 'Firstname',
                'LNAME' => 'Lastname',
        ))
        ->setInterested('interest 1 id')
        ->setInterested('interest 2 id')
        ->setIpSignup($memberIpAddress)
        ->setTimestampSignup($signupDate);
    $add = $membersClass->add($memberEntity);
    // ...

There are more setters in the "FwsMailchimp\Entities\Members" entity

Getting a members interest categories and interests Return to top

 <?php
    use FwsMailchimp\Members;
    // ...
    $membersClass = $serviceManager->get(Members::class); // ideally should be injected from your factory
    // ...
    $memberEntity = $membersClass->getMember('member@emailaddress');
    $interestCategories = $memberEntity->getInterests();
    if ($interestCategories->isEmpty() === false) {
        foreach ($interestCategories as $interestCategoryEntity) {
            // do something with the interest category entity
            $interests = $interestCategoryEntity->getInterests();
            if ($interests->isEmpty() === false) {
                foreach ($interests as $interestEntity) {
                    // do something with the interest entity
                }
            }
        }
    }

    // ...

Donate