Library to build valid Auto-Lead Data Format ADF/XML leads.

0.2.0 2021-02-10 03:05 UTC

This package is auto-updated.

Last update: 2022-11-09 05:49:20 UTC


README

PHP library that builds valid Auto-Lead Data Format ADF/XML leads.

Supports

Features

  • Complete ADF implementation
  • Validate tags and attributes (optional)
  • Custom tags and attributes
  • Data entry via an associative array, object, or JSON
  • Attempts date conversion to ISO 8601:1988
  • Default attributes for name, phone, prospect, and vehicle

Install

Include SendADF in your project with Composer:

$ composer require carmelosantana/sendadf

Requirements:

Usage

Basic lead

This example lead represents the minimum data required to comply with ADF specifications.

$adf = ( new carmelosantana\SendADF\SendADF() )
    ->add_prospect( 'new' )
    ->add_requestdate( '2/9/2020 6:26PM' )
    ->add_vehicle( [
        'year' => 1999,
        'make' => 'Chevrolet',
        'model' => 'Blazer'
    ], 'buy', 'used' )
    ->add_customer()
        ->add_contact()
            ->add_name( 'John Doe' )
            ->add_phone( '393-999-3922' )
    ->add_vendor()
        ->add_contact()
            ->add_name( 'Acura of Bellevue' );

Output

Basic output with no tabs:

echo $adf->getXML();
<?xml version="1.0" encoding="UTF-8"?>
<?adf version="1.0"?>
<adf><prospect status="new"><requestdate>2020-02-09T18:26:00-05:00</requestdate><vehicle interest="buy" status="used"><year>1999</year><make>Chevrolet</make><model>Blazer</model></vehicle><customer><contact><name part="full" type="individual">John Doe</name><phone type="voice" time="nopreference">393-999-3922</phone></contact></customer><vendor><contact><name part="full" type="individual">Acura of Bellevue</name></contact></vendor></prospect></adf>

With tabs:

echo $adf->getPrettyPrintXML();
<?xml version="1.0" encoding="UTF-8"?>
<?adf version="1.0"?>
<adf>
  <prospect status="new">
    <requestdate>2020-02-09T18:26:00-05:00</requestdate>
    <vehicle interest="buy" status="used">
      <year>1999</year>
      <make>Chevrolet</make>
      <model>Blazer</model>
    </vehicle>
    <customer>
      <contact>
        <name part="full" type="individual">John Doe</name>
        <phone type="voice" time="nopreference">393-999-3922</phone>
      </contact>
    </customer>
    <vendor>
      <contact>
        <name part="full" type="individual">Acura of Bellevue</name>
      </contact>
    </vendor>
  </prospect>
</adf>

Default values

Default attribute values are added if none are supplied. This is to adhere to the ADF standard.

$adf = ( new carmelosantana\SendADF\SendADF() )
    ->add_requestdate()
    ->add_vehicle( [
        'year' => 2020,
        'make' => 'Chevrolet',
        'model' => 'Blazer'
    ] )
    ->add_customer()
        ->add_contact()
            ->add_name( 'John Doe' )
            ->add_phone( '393-999-3922' );

echo $adf->getPrettyPrintXML();
<?xml version="1.0" encoding="UTF-8"?>
<?adf version="1.0"?>
<adf>
  <prospect status="new">
    <requestdate>2021-02-09T19:32:16-05:00</requestdate>
    <vehicle interest="buy" status="new">
      <year>1999</year>
      <make>Chevrolet</make>
      <model>Blazer</model>
    </vehicle>
    <customer>
      <contact>
        <name part="full" type="individual">John Doe</name>
        <phone type="voice" time="nopreference">393-999-3922</phone>
      </contact>
    </customer>
  </prospect>
</adf>
  • prospect tag is opened with status new without calling add_prospect.
  • add_requestdate current server time is used as the default for requestdate when none is provided.
  • name part and type are provided.
  • phone type and time are provided.

Default values can be avoided by using add_parent_node and add_node as seen in example 3.

Sending empty values as shown in example 1 can disable these attributes as well.

Examples

Example 1

  • Bare minimum to get started

Example 2

  • Full document with all elements and attribute examples

Example 3

  • Avoid default values
  • Manually open and close nodes

Example 4

  • Disable validation
  • Custom tags and attributes

Example 5

  • Data entry via arrays, objects and JSON

Methods

Name Description
__construct Start XML object
add_address Starts an address node in current working element.
add_contact Starts a contact node in current working element.
add_customer Add customer node to prospect element.
add_email Add an email node to current working element.
add_name Add name to current working element.
add_node Add a user defined node to current working node.
add_parent_node Add a user defined parent node to the current working element becoming the new current working node.
add_phone Add phone to current working element.
add_prospect Add primary prospect node to adf element.
add_provider Add provider to prospect element.
add_requestdate Converts time to ISO 8601. Defaults to current time() if none provided.
add_vehicle Add a vehicle node to prospect element.
add_vendor Add vendor to prospect element.
close_node Closes current working element.
date Formats date to ISO 8601. Defaults to current time() if none provided.
getPrettyPrintXML Format XML and make it pretty!
getXML Returns complete ADF/XML.
is_json Checks if string is JSON.
prepare_data Converts JSON and objects to an array. Integers are converted into strings.
validate_attribute Validates attribute, if validation is enabled.
validate_element Validates tag, if validation is enabled.
validation Disabling validation allows for use of custom ADF tags.
version SendADF version

SendADF::__construct

Description

public __construct (string $charset, string|int $document_version)

Start XML object

Parameters

  • (string) $charset : Character encoding
  • (string|int) $document_version : Document version

Return Values

void

SendADF::add_address

Description

public add_address (string $type)

Starts an address node in current working element.

Parameters

  • (string) $type : Type of address

Return Values

object

This instance (current working document)

SendADF::add_contact

Description

public add_contact (int $primarycontact)

Starts a contact node in current working element.

Parameters

  • (int) $primarycontact : Identifies if primary contact

Return Values

object

This instance (current working document)

SendADF::add_customer

Description

public add_customer (void)

Add customer node to prospect element.

Parameters

This function has no parameters.

Return Values

object

This instance (current working document)

SendADF::add_email

Description

public add_email (string $data, int $preferredcontact)

Add an email node to current working element.

Parameters

  • (string) $data : Email address of contact
  • (int) $preferredcontact : Indicates this as the preferred contact method (attribute)

Return Values

object

This instance (current working document)

SendADF::add_name

Description

public add_name (string $data, string $part, string $type)

Add name to current working element.

Parameters

  • (string) $data : Name of contact
  • (string) $part : Part of name (attribute)
  • (string) $type : Type of name (attribute)

Return Values

object

This instance (current working document)

SendADF::add_node

Description

public add_node (string $name, mixed $data, array $attributes)

Add a user defined node to current working node.

Parameters

  • (string) $name : Name of node
  • (mixed) $data : Data for node
  • (array) $attributes : Attributes array [ attribute_key => attribute_value ]

Return Values

object

This instance (current working document)

SendADF::add_parent_node

Description

public add_parent_node (string $name, mixed $data, array $attributes, bool $close_node)

Add a user defined parent node to the current working element becoming the new current working node.

Parameters

  • (string) $name : Name of new parent node
  • (mixed) $data : Data for node
  • (array) $attributes : Attributes array [ attribute_key => attribute_value ]
  • (bool) $close_node : If enabled will open and close node

Return Values

object

This instance (current working document)

SendADF::add_phone

Description

public add_phone (string $data, string $type, string $time, int $preferredcontact)

Add phone to current working element.

Parameters

  • (string) $data : Phone number of contact
  • (string) $type : Type of phone number (attribute)
  • (string) $time : Best time for this number (attribute)
  • (int) $preferredcontact : Indicates this as the preferred contact method (attribute)

Return Values

object

This instance (current working document)

SendADF::add_prospect

Description

public add_prospect (string $status)

Add primary prospect node to adf element.

Parameters

  • (string) $status : Identify leads that are being resent (attribute)

Return Values

object

SendADF::add_provider

Description

public add_provider (void)

Add provider to prospect element.

Parameters

This function has no parameters.

Return Values

object

This instance (current working document)

SendADF::add_requestdate

Description

public add_requestdate (mixed $time)

Converts time to ISO 8601. Defaults to current time() if none provided.

Parameters

  • (mixed) $time : Can be unix time stamp or date as a string

Return Values

object

This instance (current working document)

SendADF::add_vehicle

Description

public add_vehicle (mixed $data, string $interest, string $status)

Add a vehicle node to prospect element.

Parameters

  • (mixed) $data : Data associative array of vehicle data
  • (string) $interest : Identifies intended purpose of this vehicle (attribute)
  • (string) $status : Identifies new or used vehicle (attribute)

Return Values

object

This instance (current working document)

SendADF::add_vendor

Description

public add_vendor (void)

Add vendor to prospect element.

Parameters

This function has no parameters.

Return Values

object

This instance (current working document)

SendADF::close_node

Description

public close_node (void)

Closes current working element.

Parameters

This function has no parameters.

Return Values

object

This instance (current working document)

SendADF::date

Description

public static date (mixed $time)

Formats date to ISO 8601. Defaults to current time() if none provided.

Parameters

  • (mixed) $time : Time to convert

Return Values

string

Formatted date

SendADF::getPrettyPrintXML

Description

public getPrettyPrintXML (void)

Format XML and make it pretty!

Parameters

This function has no parameters.

Return Values

string

Human readable XML

SendADF::getXML

Description

public getXML (void)

Returns complete ADF/XML.

Parameters

This function has no parameters.

Return Values

string

ADF/XML

SendADF::is_json

Description

public static is_json (mixed $data)

Checks if string is JSON.

Parameters

  • (mixed) $data : Data to check

Return Values

bool

Is this JSON?

SendADF::prepare_data

Description

public static prepare_data (mixed $data)

Converts JSON and objects to an array. Integers are converted into strings.

Parameters

  • (mixed) $data : Data to prepare for input into a node

Return Values

mixed

Prepared data

SendADF::validate_attribute

Description

public static validate_attribute (object $parent, object $node, bool $validation)

Validates attribute, if validation is enabled.

Parameters

  • (object) $parent : Element attribute is being applied to
  • (object) $node : Attribute being checked
  • (bool) $validation : $this->validation value

Return Values

bool

Validation response

SendADF::validate_element

Description

public static validate_element (object $parent, object $node, bool $validation)

Validates tag, if validation is enabled.

Parameters

  • (object) $parent : Element tag is being applied to
  • (object) $node : Tag being checked
  • (bool) $validation : $this->validation value

Return Values

bool

Validation response

SendADF::validation

Description

public validation (bool $validate)

Disabling validation allows for use of custom ADF tags.

Parameters

  • (bool) $validate : Validation enabled by default, false to disable

Return Values

object

This instance (current working document)

SendADF::version

Description

public version (void)

SendADF version

Parameters

This function has no parameters.

Return Values

string

Support

Contact to discuss commercial support.

Funding

If you find SendADF useful or use it in a commercial environment please consider donating today with one of the following options.

  • PayPal
  • Bitcoin bc1qhxu9yf9g5jkazy6h4ux6c2apakfr90g2rkwu45
  • Ethereum 0x9f5D6dd018758891668BF2AC547D38515140460f
  • Tron TFw3D8UwduZJvx8J4FPPgPVZ2PPJfyXs3k

License

The code is licensed MIT and the documentation is licensed CC BY-SA 4.0.