[Request] Fluent OOP objects

[Garbee]

The current API is pretty difficult to have complete accuracy. It would benefit developers greatly if we could build an address object and using fluent setters provide data. For example:

$from_address = [
   'object_purpose' => 'QUOTE',
    'name' => 'Mr Hippo',
    'company' => 'Shippo',
    'street1' => '215 Clayton St.',
    'city' => 'San Francisco',
    'state' => 'CA',
    'zip' => '94117',
    'country' => 'US',
    'phone' => '+1 555 341 9393',
    'email' => '[email protected]',
];

becomes:

$address = new Shippo\Address();
$address
    ->purpose('QUOTE')
    ->name('Mr Hippo')
    ->company('Shippo')
    ->streetOne('215 Clayton St.')
    ->city('San Francisco')
    ->state('CA')
    ->zip('94117')
    ->country('US')
    ->phone('+1 555 341 9393')
    ->email('[email protected]');

This style improves overall accuracy by removing the need on developers to maintain accurate keys since the object's setter methods do that for us. Reducing the surface area for programmer-error. Further methods could be provided on these to help developers know before sending them over the wire if they are capable of having tasks carried out. For example $address->canBeVerified(); will check the data in-memory against a known list of required attributes. If you're missing zip/state/streetOne then you know it can't be verified before it even goes out if that is the developers intention.

[Garbee]

The example object could even be cleaned up a little bit more. Like $address->purpose('QUOTE') could be, the object is defaulted to PURCHASE and you call $address->forQuote() to toggle the purpose. Thereby making the code more readable to others in the future.

To expand on say sending to the server for storage. What you'd do is call $address->store() once everything is prepared. That would then do the server-request and get the response back, which would be used to hydrate the shippo id for the developer to retrieve $address->shippoID() in their application.