README

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

👁 Build Status

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.