Coming up: Mock data support and better default argument handling in the SWX Service Explorer

I'm currently working on a stealthy little pet project of mine that involves creating a PayPal Website Payments Pro API in SWX. A couple of the methods in the API require quite a few arguments (all the billing-related fields for processing a credit card transaction, for example) and I quickly got sick of having to enter mock data manually in the SWX Service Explorer to test and debug methods calls. (This is one scenario where Transfer Object support would be helpful but adding that right now would complicate things too much.) So, to make things easier for myself (and hopefully some of you as well), I've added mock data support (both static and dynamic) to SWX PHP and the SWX Service Explorer.

Using mock data

In the SWX Service Explorer, methods that have mock data will have a "Use mock data" button enabled.

Clicking the button will fill the arguments with the mock data, as the following screenshot demonstrates.

Creating static mock data

The first way to create mock data is to include it in the JavaDoc-style comments in your service classes. Place mock data at the end of the comment and surround it in square brackets. 

/**
   * Do a direct credit card payment.
   *
   * @param (str) A unique order id [12345-12345]
   * @param (str) Credit card number [5105105105105100]
   * @param (str) Card type (Visa, American Express, Mastercard, etc.) [Mastercard]
   * @param (str) 3 or 4 character Credit Security Code [123]
   * @param (number, 4 digits MMYY) Expiry date [1209]
   * @param (number) Amount to charge [2.50]

This is a quick and easy way of adding mock data to a method. The recommended practice here, when possible, is to place enough mock data in a method to allow the user to make a successful call via the SWX Service Explorer. This is in keeping with the SWX philosophy of making things Just Work and Show, Don't Tell.

Generating mock data

The new mock data feature does not limit you to static mock data. You can also generate dynamic mock data with a little bit of PHP.

To generate mock data for a method called doDirectPayment(), for example, you can include a private method called _doDirectPaymentMock() in your service class. This method gets called (and passed an array of any static mock data for the method, which you can either add to or ignore) by the service explorer. It expects an array of mock data (one for each argument) to be returned as per the following example. 

function _doDirectPaymentMock($mockData)
{
    // Generate a random order number
    $orderNum = '"'.date('ymd-H').rand(1000,9999).'"';
    $mockData[0] = $orderNum;

    return $mockData;
}

In the above example, the order number needs to be unique so it's generated by code but all the other default values are statically obtained from the comments.

Update: In the latest version of the SWX Service Explorer in SVN, the dynamic mock data now updates every time you press the Use mock data button.

Default values for optional arguments

I've also modified how default parameters are handled in the SWX Service Explorer. Previously, they were handled Really Badly (tm). i.e., they were basically ignored. Now, if your method has a default value defined, it is displayed in the SWX Service Explorer by default. This is true even if you define the default value as a constant (in PHP4, you must stick to the CONSTANT_NAMING_CONVENTIONS for constant resolution to work correctly.)

(Note that in PHP5, you must place all optional arguments at the end of your method signature. This is a best practice to follow in any case.)

The following screenshot shows how default values for arguments are handled in the new service explorer:

Currently, the changes outlined in this post are only available from the trunk of the SWX Subversion repository. I'd appreciate it if you guys can test it out. After further testing, it will be included in the next SWX PHP release.

Comments