diff --git a/README.md b/README.md index 09e66c7..b2f0a14 100644 --- a/README.md +++ b/README.md @@ -1,19 +1,26 @@ # Introduction + This is a CARFAX Vehicle History Reporting, QuickVIN, and Service History Check integration toolkit. It provides the interface to achieve the following results: + - Report your DMS/SMS vehicle repair ticket history - Perform a QuickVIN search - Perform a Search History Check As achieved through proprietary APIs and integration procedures. Using this PHP based toolkit is not possible without an existing CARFAX Service Data Transfer Facilitation Agreement, and it relies on API keys that are not publicly subscribable (You need to work with someone in the CARFAX Partner Development department). -P.S., -[GitHub Copilot](https://copilot.github.com/) was partially used for development, which is the reason for the unnecessarily long and descriptive comments. - # Usage + +## Install + +```bash +composer require amattu2/carfax-wrapper +``` + ## Configuration File + By default, all of the keys/passwords are pulled from a `config.ini` file. Here is the default file that you can choose to use: -``` +```ini CF_PARTNER= CF_LOCATIONID= CF_MANAGEMENT_SYSTEM= @@ -36,17 +43,21 @@ DB_NAME= ___ ## FTP + This is a helper class for reporting repair data to the CARFAX VHR system. It substantially eases the load required of a developer to implement CARFAX vehicle history reporting from a proprietary DMS/SMS system. ### constructor + #### Usage + Initialize the class component using the constructor ```PHP -$wrapper = new amattu\CARFAX\FTP(); +$wrapper = new CARFAX\FTP(); ``` #### PHPDoc + ```PHP /** * Class Constructor @@ -65,7 +76,9 @@ public function __construct(string $username, string $password, string $partner_ ___ ### write + #### Usage + Write a single record to the export file. Please Note: **This function DOES NOT validate field values. It only writes what was provided.** Your implementation of the class will need to validate Repair Order field values. **This ONLY ensures that the field is present in the array.** ```PHP @@ -75,6 +88,7 @@ $success = $wrapper->write([ ``` #### PHPDoc + ```PHP /** * Write a single Repair Order to the file @@ -91,7 +105,9 @@ public function write(array $data, $handle = null) : bool; ___ ### writeAll + #### Usage + Write an array of repair orders to the report file. This is an efficient wrapper to the `write()` method, and maintains a file handle at all times. If you are able to write a multitude of Repair Orders at a single time, use this. Please Note: **This function DOES NOT validate field values. It only writes what was provided.** Your implementation of the class will need to validate Repair Order field values. **This ONLY ensures that the field is present in the array.** ```PHP @@ -110,6 +126,7 @@ $successes = $wrapper->writeAll( ``` #### PHPDoc + ```PHP /** * Write all Repair Orders to the file @@ -125,7 +142,9 @@ public function writeAll(array $data) : int; ___ ### upload + #### Usage + Submit the generated record to the CARFAX FTP endpoint. ```PHP @@ -133,6 +152,7 @@ $wrapper->upload(); ``` #### PHPDoc + ```PHP /** * Connect to the FTP server and upload the file @@ -148,7 +168,9 @@ public function upload() : bool ___ ### cleanUp + #### Usage + This is an entirely optional function that will delete the Repair Order file. It should be called after `upload`. ```PHP @@ -156,6 +178,7 @@ $isCleaned = $wrapper->cleanUp(); ``` #### PHPDoc + ```PHP /** * Clean up the workspace by deleting the report file @@ -171,7 +194,9 @@ public function cleanUp() : bool ___ ### getTotalRecords + #### Usage + This returns the total number of repair orders written to the report file. Does not include the header line. ```PHP @@ -179,6 +204,7 @@ $numRecords = $wrapper->getTotalRecords(); ``` #### PHPDoc + ```PHP /** * Return the total Repair Orders written to the file @@ -192,10 +218,13 @@ public function getTotalRecords() : int ``` ### getFilePath + #### Usage + This returns the fully-qualified path to the report file if the file exists. #### PHPDoc + ```PHP /** * Return full path to report file @@ -206,10 +235,13 @@ public function getFilePath() : ?string ``` ### getFileName + #### Usage + This returns the filename of the report file if it exists. #### PHPDoc + ```PHP /** * Get report file name @@ -219,20 +251,25 @@ This returns the filename of the report file if it exists. */ public function getFileName() : ?string ``` + ___ ## ServiceHistory + This is a entirely static class used to fetch repair history data from CARFAX by a vehicle VIN. ### setLocationId + #### Usage + Update the Location ID for the current *instance* of the class. This is provided by CARFAX at the time of account setup. ```PHP -amattu\CARFAX\ServiceHistory::setLocationId("exampleLOC"); +CARFAX\ServiceHistory::setLocationId("exampleLOC"); ``` #### PHPDoc + ```PHP /** * A Static function to Update the Location ID @@ -247,14 +284,17 @@ public static function setLocationId(string $locationId) : void; ___ ### setProductDataId + #### Usage + Update the Product Data ID for the current *instance* of the class. It is the equivelent of a API key, and is CARFAX defined at the time of account setup. ```PHP -amattu\CARFAX\ServiceHistory::setProductDataId("exampleProductDataId"); +CARFAX\ServiceHistory::setProductDataId("exampleProductDataId"); ``` #### PHPDoc + ```PHP /** * A Static function to Update the Product Data ID @@ -269,18 +309,22 @@ public static function setProductDataId(string $productDataId) : void; ___ ### get + #### Usage + This is the actual function exposed for fetching the vehicle history by VIN number. If you do not have the locationId or productDataId set, errors will be thrown. Everything else is error safe, including CARFAX API failures. The function will always return an array or throw an error. If a record (Overview or History) does NOT have a valid: + - Odometer, it will be equal to `0` - Date, it will be equal to `NULL` ```PHP -$data = amattu\CARFAX\ServiceHistory::get("1G1GCCBX3JX001788"); +$data = CARFAX\ServiceHistory::get("1G1GCCBX3JX001788"); ``` #### PHPDoc + ```PHP /** * A Static function to use cURL to make a request to the Service History API @@ -299,6 +343,7 @@ public static function get(string $VIN) : array; ``` #### Expected Output + *Abbreviated substantially* ```JSON @@ -371,14 +416,17 @@ public static function get(string $VIN) : array; ``` # FTP Integration Demo + If you are in need of assistance in setting up the integration between your existing dealer/shop management system and the FTP helper class, see `sql-example.php`. This file is a general demonstration on how to integrate your system with the CARFAX vehicle history reporting FTP service. It was tested with 300,000 rows and completed (start to finish) in less than 6 seconds. PS, It's a demonstration file only. Do not implement it in an actual environment. It omits important validation and security practices for the sake of simplicity. -# Todo: +# Todo + - Merge `PARTNER_NAME` with `MANAGEMENT_SYSTEM` as they should be identical # Requirements & Dependencies + N/A