carmelosantana/sendadf

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

0.2.0 2021-02-10 03:05 UTC

Requires

• php: >=7.2

Requires (Dev)

• clean/phpdoc-md: ^0.19.1
• phpunit/phpunit: 6.*

MIT

• Carmelo Santana

• xml
• crm
• vehicle
• leads
• adf
• automotive
• auto-lead

README

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

Supports

• ADF 1.0

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

• SendADF
  • Install
  • Usage
    • Basic lead
    • Output
    • Default values
  • Examples
  • Methods
    • SendADF::__construct
    • SendADF::add_address
    • SendADF::add_contact
    • SendADF::add_customer
    • SendADF::add_email
    • SendADF::add_name
    • SendADF::add_node
    • SendADF::add_parent_node
    • SendADF::add_phone
    • SendADF::add_prospect
    • SendADF::add_provider
    • SendADF::add_requestdate
    • SendADF::add_vehicle
    • SendADF::add_vendor
    • SendADF::close_node
    • SendADF::date
    • SendADF::getPrettyPrintXML
    • SendADF::getXML
    • SendADF::is_json
    • SendADF::prepare_data
    • SendADF::validate_attribute
    • SendADF::validate_element
    • SendADF::validation
    • SendADF::version
  • Support
  • Funding
  • License

Install

Include SendADF in your project with Composer:

$ composer require carmelosantana/sendadf

Requirements:

• PHP 7.3 or above
• Composer

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.

• https://stackoverflow.com/a/6041773/1007492 License CC BY-SA 3.0

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.