https://github.com/webreinvent/laravel-usps
USPS API wrapper for Laravel projects.
https://github.com/webreinvent/laravel-usps
laravel laravel-7 laravel-7-package laravel-framework usps-packages
Last synced: 6 months ago
JSON representation
USPS API wrapper for Laravel projects.
- Host: GitHub
- URL: https://github.com/webreinvent/laravel-usps
- Owner: webreinvent
- License: mit
- Created: 2020-06-09T09:34:55.000Z (almost 5 years ago)
- Default Branch: master
- Last Pushed: 2023-06-30T06:10:05.000Z (almost 2 years ago)
- Last Synced: 2024-11-15T08:04:41.049Z (6 months ago)
- Topics: laravel, laravel-7, laravel-7-package, laravel-framework, usps-packages
- Language: PHP
- Homepage: https://webreinvent.com
- Size: 749 KB
- Stars: 1
- Watchers: 2
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE.md
Awesome Lists containing this project
README
# Laravel-Usps
This package provides a very simple wrapper for the United States Postal Service API. Currently, this package only provides address validation features, but will soon comprise all features offered by the USPS API.
### Prerequisites
Be sure to register at [www.usps.com/webtools/](www.usps.com/webtools/) to receive your unique user ID
from the United States Postal Service. This user ID is required to use this package.
### Installation
```
composer require webreinvent/laravel-usps
```
## Configuration
There are three important configurations.
1. Your USPS user ID:
- If you have not received your USPS user ID, follow the link in the [prerequisites](#Prerequisites) section to register with the
United States Postal Service. It is required to use this package.
2. Whether you want SSL verification enabled for API requests:
- This setting is set to `true` by default for security reasons. You can override this behavior by setting the `verrifyssl` config setting to `false`. Do this at your own risk.
3. Which environment you are working in:
- The options are `'local' and 'production'` which tell the package which API url to use, testing or production respectively. If no configuration is found for `env`, it will default to the environment recognized by laravel. This setting takes precedence over `APP_ENV` from your `.env` file.
We recommend placing all configuration settings in your `.env` file and use Laravel's `env()` helper function to access these values.
In `config/services.php` add these three settings.
```php
'usps' => [
'userid' => env('USPS_USER_ID'), // string
'verifyssl' => env('USPS_VERIFY_SSL'), // bool
'env' => env('USPS_ENV') //string
];
```
## Usage
The current features offered by this package are:
- [Address Validation](#Address-Validation)
## Address Validation
The `Address` class handles creating and formatting address data. Pass the constructor an associative array of address details. Array keys are case-sensitive.
Below is an example of creating an address and making an api request for validation.
```php
use WebReinvent\Usps\Address;
$address = new Address([
'Address2' => '6406 Ivy Lane',
'City' => 'Greenbelt',
'State' => 'MD',
'Zip5' => 20770
]);
$response = $address->validate();
```
The USPS api supports up to 5 address validations per request. If you need to validate more than one address at a time, pass an array of addresses to the `Address` constructor.
```php
use WebReinvent\Usps\Address;
$address1 = [
'Address2' => '6406 Ivy Lane',
'City' => 'Greenbelt',
'State' => 'MD',
'Zip5' => 20770
];
$address2 = [
'Address2' => '2185 Sandy Drive',
'City' => 'Franklin',
'State' => 'VA',
'Zip5' => 32050
];
$addresses = new Address([$address1, $address2]);
$response = $addresses->validate();
```
The response will contain the [corrected address](https://www.usps.com/business/web-tools-apis/address-information-api.pdf), or an error if not enough information was given or the address does not exists.
## Response Formatting
You can specify the format of the response by passing an optional, case-insensitive parameter to the validate method. The default format is an associative array.
```php
$address = new Address([/* address info */ ]);
$json = $address->validate('json');
$object = $address->validate('object');
$string = $address->validate('string');
```