README

Parcelforce exrpessTransferAPI for Laravel to generate pre-advice electronic file that required by solution.

Features

Generating electronic file on the server
Submitting electronic file to Parcelforce
Single or multiply consignment's per file
UK Domestic collection request (Label and receipt provided by PFW driver)
UK Domestic services dispatches only (Label printed by customer)
Can be used as Laravel package or PHP standalone class

Requirements

Must be Parcelforce customer
PHP >= 5.3
MySQL
Laravel >= 4.1 if used as Laravel package

Installation

composer require alexpechkarev/parcelforce  dev-master

Configuration

Once installed, register Laravel service provider, in app/config/app.php:

'providers' => array(
	...
    'Parcelforce\ExpressTransfer\ParcelforceServiceProvider',
)

Publish configuration file:

php artisan config:publish parcelforce/expresstransfer --path vendor/alexpechkarev/parcelforce/src/config/

All generated file will be stored in app/config/packages/parcelforce/expresstransfer/files folder by default. Ensure this folder writable by the web server:

chmod o+w app/config/packages/parcelforce/expresstransfer/files

Name and location of this folder can be specified in the configuration file by editing filePath value, if changed ensure it's writable by we server.

    /**
     * Location consignment files
     */        
    'filePath'                        => __DIR__.'/files/',

In the configuration file app/config/packages/parcelforce/expresstransfer/config.php please ensure that following parameters are set. For more details on configuration options and required values please contact Parcelforce. By default these parameters preset with dummy values.

 'header_customer_account' 
 'header_generic_contract'
 'senderName'
 'senderAddress1'
 'senderPostTown'
 'senderPostcode'
 'dr_consignment_number' 
 'fileName' 
 'ftpUser' 
 'ftpPass'
 'ftpUploadPath'
 'ftpLocationPath'

Laravel Usage

Simply pass you data as array to Parcelforce::process() method. Electronic file will be generated for given data, stored at filePath location and submitted to Parcelforce.

        $senderData = array(
            array(
                "deliveryDetails"=>array(
                    'receiverName'      =>"MR CUSTOMER",
                    'receiverAddress1'  =>'100 CUSTOMER SOLUTIONS STREET',
                    'receiverPostTown'  =>'MILTON KEYNES',
                    'receiverPostcode'  =>'MK9 9AB'
                    )
            )           
        );

        Parcelforce::process($senderData);

        // generate file locally without submitting to Parcelforce
        Parcelforce::process($senderData, FALSE);

Multiply consignment data can be submitted in single request.

        $senderData = array(
            array(
                "deliveryDetails"=>array(
                    'receiverName'      =>"MR CUSTOMER",
                    'receiverAddress1'  =>'100 CUSTOMER SOLUTIONS STREET',
                    'receiverPostTown'  =>'MILTON KEYNES',
                    'receiverPostcode'  =>'MK9 9AB'
                    )
            ),
            array(
                "deliveryDetails"=>array(
                    'receiverName'      =>"MR CUSTOMER",
                    'receiverAddress1'  =>'202 CUSTOMER SOLUTIONS STREET',
                    'receiverPostTown'  =>'MILTON KEYNES',
                    'receiverPostcode'  =>'MK9 9AB'
                    )
            )
        );

        Parcelforce::process($senderData);

By default collection date is set for tomorrow's date and can be amended in the configuration file, see collectionDate. This value can also be specified at runtime using Parcelforce::setDate() method.

    Parcelforce::setDate("next Monday");
    Parcelforce::process($senderData);

Dates handled by:

Carbon in package for Laravel
DateTime in PHP standalone class

Following formats accepted by setDate() method:

Relative Formats

tomorrow
next wednesday
this thursday
....

Date Formats

2014-08-11
08/11/2014
20140811
....

PHP standalone class Usage

Location: 'Parcelforce\ExpressTransfer\PHP'

Standalone class have same methods as Laravel package and accepts consignment data in the same way. Before use please ensure that required parameters are set in configuration file 'Parcelforce/ExpressTransfer/PHP/config.php' and Parcelforce/ExpressTransfer/PHP/files folder is writable by web server.

       $pf = new \Parcelforce\ExpressTransfer\PHP\Parcelforce();
       $pf->process($senderData));
       
       // generate file locally without submitting to Parcelforce
       $pf->process($senderData));

setDate() method is also available in standalone version.

    ...
    $pf->setDate("next Monday");
    $pf->process($senderData);

Configuration testing

For testing and configuration purposes file can be generated without being submitted to Parcelforce. To generate file locally simply pass FALSE as second parameter to process() method.

    // In Laravel package
    Parcelforce::process($senderData, FALSE);

    // In PHP standalone class
    $pf->process($senderData, FALSE);

Once testing and configuration completed file and consignment numbers have to be reset to initial values. To initiate process call reset() method. Please note: reset() will reload database tables and all the data will be lost. See config.php for table details.

    // In Laravel package
    Parcelforce::reset();

    // In PHP standalone class
    $pf->reset();

PHPUnit Testing

PHPUnit testing require Mockery flexible PHP mock object framework. Run following command to install Mockery:

composer require mockery/mockery:dev-master@dev

In Laravel package test file needs copying from package folder into app/tests/ folder, use following to do so:

cp vendor/alexpechkarev/parcelforce/tests/ParcelforceLaravelTest.txt app/tests/ParcelforceTest.php

And then run test:

phpunit app/tests/ParcelforceTest.php

To test PHP standalone file ensure database credentials are set in the config file.

    phpunit vendor/alexpechkarev/parcelforce/tests/ParcelforcePHPTest.php

Main Methods

     /** 
     * @param array $data - array of data
     * @return string File content
     */
     public function process($data, $upload = TRUE)


    /**
     * Drop database tables
     */
    public function reset()



    /**
     * Get file content
     * @return string
     */
     public function getFileContent()


    /**
     * Get current instance config file
     * @return array
     */
    public function getConfig()

Support

Please open an issue on GitHub

License

Parcelforce expressTransfer API for Laravel 4 is released under the MIT License. See the bundled LICENSE file for details.

alexpechkarev / parcelforce

Maintainers

Details