SWX PHP Archive - SWX: SWF Data Format

Sep 3, 2007 5

SWX PHP and SWX ActionScript Library Release Candidate 1 Released

I just released Release Candidate 1 (RC1) of SWX PHP and the SWX ActionScript Library. The SWX PHP MAMP Bundle has also been updated to RC1. Get them now from the download page.

There is a whole slew of changes in this update and you can find the whole list in the release notes for SWX PHP RC1.

One of the major changes is that SWX RPC calls can now return simple data types as opposed to the previous behavior which was to wrap simple data types in an array. This may break your existing applications, so please read these instructions for updating your SWX applications to SWX PHP RC1.

Among the highlights of the RC1 release is the release of the SWX Flickr API, which has been available on the Public SWX Gateway for a little while now. The SWX Flickr API implements the full Flickr API and has some additional utility methods that make it the easiest way to work with Flickr in Flash. Take a look at the miniflickr Flash Lite sample application that comes with this release to learn how to work with the new Flickr API as well as some of the advanced features of the SWX ActionScript Library like the ExternalAsset and LoadManager classes.

SWX PHP RC1 has two more new APIs: The Jaiku API and Numpa API (Numpa is the Netherlands version of Twitter), both by my dear friend Folkert Hielema. You can find Folkert's other SWX-related work, as well as the work of other community members, in the new SWX Showcase.

You can explore and test all of the SWX APIs online using the SWX Service Explorer.

The SWX Data Analyzer has also been updated and now supports the display of simple data types correctly. It also displays debug information in a clearer manner.

With the RC1 release, the SWX ActionScript Library is available as a separate download. This means that if you don't want to write your own server-side classes, you don't have to download the full SWX PHP package just to use the high-level ActionScript classes.

Unless there are any major issues discovered in the next few days, Release Candidate 1 is going to be very close to the final release version of SWX PHP and the SWX ActionScript Library. If you do notice any issues, please report them to me. SWX PHP is now in feature freeze and only critical bugs will be fixed at this point (no new feature requests, etc.) In the next few days, I'm going to be updating the documentation, making some aesthetic changes, and recording more screencasts to prepare SWX PHP for the Version 1.0 release next week.

We're very close to Version 1.0, and that's just the beginning!

Sep 2, 2007 0

Release notes for SWX PHP RC1

SWX RPC: MAY BREAK EXISTING APPS, read these instructions for updating your applications to SWX PHP RC1! Root data type can be any supported data type (bool, int, float, string, associative array/object, array)
SWX PHP: Flash 6 support. SWX PHP created SWX files work with Flash 6+.
SWX PHP: E_NOTICE errors are no longer returned to Flash but ignored. (Thanks to Alex Tur for reporting this.)
SWX PHP: Start page simplified with links to swxformat.org and online documentation.
SWX PHP: Added SWX RPC data type tests to the start page.
SWX PHP: The SWX RPC data type tests on the start page now automatically detect the gateway URL and display the gateway URL on successful completion.
SWX ActionScript Library: Changed event constant values to lowercase on ExternalAsset class.
SWX ActionScript Library: LoadManager broadcasts PROGRESS events when a new item in the queue starts to load.
SWX ActionScript Library: Updated to compile under Flash 6.
Flickr API: Implemented the full official Flickr API.
Flickr API: getUserPhotos() no longer makes unnecessary API call to urls_getUserPhotos. Uses the NSID instead.
Flickr API: getUserPhotos() renamed to swxGetUserPhotos(). All SWX Flickr API extensions now start with "swx" to separate them from the official Flickr API methods.
Flickr API: Added file upload script.
Flickr API: swxGetUserPhotos and swxPhotosGetRecent now return info on total number of pages.
Twitter API: addFriends() returns correct response code. Patch courtesy of Folkert.
Twitter API: Updated all methods to the latest official Twitter API.
Twitter API: Deprecated addFriend, removeFriend in favor of new friendship methods in official Twitter API.
Twitter API: Added getFans() alias for followersWhoAreNotFriends() method.
Twitter API: Updated leaveFriend() and followFriend() methods. They now return the correct status with the latest Twitter screens.
Twitter API: Added notifications() method for turning notifications for a friend on or off.
Data Analyzer: Details and history panel widths now grow when horizontal divider is moved.
Data Analyzer: Added web site links for documentation, etc.
Data Analyzer: Now displays all supported root data types correctly.
Data Analyzer: Resumes following data streams after the history is cleared even if user was viewing historic data previously.
Data analyzer: The open/close tree controls are now enabled/disabled according to the root data type.
Service Explorer: The method tree now has focus by default and the method dropdown does not lose focus on selection. Keyboard navigation of app should be much easier.
Service Explorer: The methods drop-down no longer scrolls up with the parameters.
Service Explorer: Added web site links for documentation, etc.
Sample applications: Updated simple_flickr.fla to use the new Flickr API methods.
Sample applications: Updated all sample applications to RC1 and tested.
Sample applications: All sample applications now use the public SWX gateway by default to ensure that they work regardless of whether there is a properly configured local SWX PHP instance.
Sample applications: Added miniflickr Flash Lite application.
MiniFlickr: Users can no longer go to a non-existing page.
MiniFlickr: Existing thumbnail overlay from previous screen does not display on new screens.
MiniFlickr: Focusrect is now correctly aligned.
MiniFlickr: Pages are correctly centered horizontally.
MiniFlickr: Controls display properly on details screen.
MiniFlickr: Main page load indicator now displays while quickly scrolling pages.

Sep 2, 2007 1

Release notes for SWX PHP Beta 1.3 and earlier

Beta 1.3 (released July 18, 2007)

SWX gateway: Errors are now returned as Objects with error (boolean), errorNumber, and errorNumber properties.
SWX Full API: Added fault handler support. You add a fault handler just like result, progress, and timeout handlers. e.g., fault: [this, faultHandler] in the call parameters object you pass the swx call() method.
BaseService no longer shows up in the methods drop-down in Explorer for any of the APIs.
Added checks for safe mode and open basedir (CURL followlocation will fail in both these situations), and mod_security (cross-domain data access fails with default ruleset) that alert user potential problems instead of failing silently .
PHP 5: Fixed strict mode errors causing calls to fail (e.g. Flickr.getUserPhotos).
MAMP Bundle: Now defaults to the correct default directory on start up.
Flash examples: Saved all files in Flash 8 format.
Flash examples: Added .. to the classpath of all example FLAs so they compile out of the box.
Flash examples: Set mobile examples to FL 2.0 not 2.1 to be F8 compatible.
Flash examples: Removed old example files.

Beta 1.2.2 (released July 9, 2007)

Very minor point release: The SWX image on the start page was missing from previous Beta 1.2.x releases. If your aesthetic sensibilities can live with that, you don't need to upgrade from 1.2.1!

Beta 1.2.1 (released July 9, 2007)

(Many thanks once again to Folkert for reporting the issues that were fixed in this release).

Explorer: Fixed name of Explorer SWF so it doesn't break on case-sensitive systems.
Explorer: Explorer: The results panel now hides when changing methods.

Beta 1.2 (released July 6, 2007)

See this blog post for release notes.

Beta 1.1 (released June 17, 2007)

Please read the list of changes in SWX Beta 1.1 from on blog.

Beta 1.0 (released 2007-5-25)

For a summary of changes in SWX Beta 1, please see this overview of SWX Beta 1 on my blog.

This is a major release, taking SWX from Alpha to Beta stage.

Added Full API. This API gives you an abstract interface (you don't have to do movie clip loading by hand), callbacks and timeouts and queued calls.
Added LoadManager and ExternalAsset classes (part of the Full API). You can use these to load any external asset in queue.
Refactored gateway and compiler code.
SWX gateway now performs error checking and returns errors.
Removed error reporting code from SWX Twitter API as this is now handled by the gateway.
API Change: The arguments property is now args to be consistent with the Full API.
Added Full API and No API versions of most Flash samples.
Updated the SWX start page with the latest code example from my blog.
Added cancelAllCalls() method to the SWX class and cancelAllLoads() method to the LoadManager class. These clear out the queue of waiting SWX calls and movie loads, respectively.
Added an additional method of allowing cross-domain data exchanges that doesn't require the main SWF to grant access to the SWX data SWF.

Alpha release notes

What's new in Alpha 0.2.2 (released 2007-04-28)

This is a minor release before 0.3.

The SWX Twitter API now supports all methods in the official Twitter API (except the featured users call as there's potentially a bug with the Twitter API on that call) as well as several additional custom methods. You can test out the Twitter API calls online using the Flex-based PHP Service Browser interface on the SWX web site. (If prompted, enter http://swxformat.org/php/amf.php as the gateway URL.)
Deployed the SWX PHP gateway on swxformat.org (you'll get a SWF if you hit that URL in the browser) and modified all samples to hit this gateway instead of the older one on aralbalkan.com. This will be the main public SWX gateway, going forward. Please feel free to use the Twitter API from this gateway for your own mashups, etc., if you want to.
Added a second small Flash Lite Twitter sample that uses the new LoadManager and ExternalAsset classes to standardize and control loading of SWX and other media in Flash Lite applications.
The SWX class has the new API code in there but this has not been tested and none of the examples use it. It won't be supported until Alpha 0.3 but you can peek at it if you're curious. Don't blame me if it breaks though!

What's new in Alpha 0.2.1 (released 2007-04-28)

The big feature in this release is compression!

Compression. You can now set a compression level from 0 (no compression; fastest) to 9 (maximum compression; slowest) in the SWX configuration file (php/swx_config.php).
Added a very simple Flash Lite 2.1 example. Note that POST appears to be broken in loadMovie() in Flash Lite 2.1, so use GET instead. I am going to work with the Adobe folks to make sure that this gets fixed in future versions of Flash Lite.

Older releases

What's new in Alpha 0.2.0 (released 2007-04-16)

SWX 0.2.0 is another huge release and brings with it an API change. Please read the release notes carefully!

API change: Prepare.forPhp() has been replaced with SWX.prepare(). See the updated introductory blog post on SWX for usage examples.
You can now do cross-domain data exchanges with SWX. If you want to disallow cross-domain access to your data, set the allowDomain paramater to false in the swx_config.php file (php/swx_config.php).
Added PowerPC support. Should now work on older (bi-endian) Macs.
The SWX analyzer now also works across domains. This means that once open, it will display data loading from any domain, local or remote.
GET support was broken on SWX gateway. This has now been fixed.
SWX now uses JSON instead of PHON when serializing arguments sent from the client to the server.
Fixed setVariable (bytecode) bug and removed respective workaround in SWFCompiler class.

What's new in Alpha 0.1.9 (released 2007-04-10, updated 2007-04-12 at 10:05 GMT).

Added Amfphp to the build.
SWX now works with Amfphp services (except those that return RecordSets). Fixed include path mismatch with Amfphp in service class includes, which was the only remaining issue.
Added interim workaround for object support (they are converted to associate arrays).
Added History Panel to SWX Analyzer.
Added SWX Twitter Badge sample app
Added SWX Twitter Stream sample app
Updated SWX gateway path for Flash examples. They now use http://localhost:8888/php/swx.php. This is in preparation for the MAMP bundles in 0.2.1).
Added config file SWX to allow custom services folder.
Integrated SWX config file with globals.php in Amfphp.
Renamed Amf gateway to amf.php (from gateway.php) to be consistent with other gateway naming conventions.
Changed include_once statements to include statements to decrease load.
Changed Analyzer and service browser to use UFO
License information added to build and start page
Started the move to friendlier end-user documentation (very early stages)
Added basic error checking to SWX Analyzer.
Tested with MAMP 1.4.1
Updated to work on (and tested with) PHP 4.4.4

What's new in Alpha 0.1h (released on 2007-04-02 at 18:22 GMT):

Alpha 0.1g had old versions of the SwfCompiler and SWX gateway. This release fixes that. It should now function as per the docs.

What's new in Alpha 0.1g:

API Change. The className property is now "serviceClass".
API Change. The data property is now "arguments".
How service methods are called has changed. Previously, the data property was sent as the first (and only) argument to the server-side method. Now, the data property has been replaced with the arguments property. You still pass an array as the arguments property but each top-level element in the arguments array is passed as a separate argument to your server-side method. This is going to allow you to use SWX with any existing service class(for example, Amfphp service classes.)
Deployment: Removed some .svn folders that were somehow checked in.
SVN: Added tags to repository.
Deployment: Renamed text folder to "docs" to make it clearer.
Docs: Updated docs to reflect API changes in 0.1g

What's new in Alpha 0.1f:

Previous releases had the php/lib folder missing.

What's new in Alpha 0.1e:

Broken build, please download 0.1f

Added manual PHON serializer.
Modified echo sample application to use the manual PHON serializer.
Renamed the automatic serializer AutoPhpSerializer. It's still there but you can choose whether you want to use it. I may remove this in future iterations.
Modified the SWX gateway to handle null values. The auto serializer was sending them over as undefined.

What's new in Alpha 0.1d:

Fixed bug with the SWX gateway that threw script errors for incorrectly formed requests. This bug was introduced with the addition of GET functionality in 0.1b.

What's new in Alpha 0.1c:

The example FLA is now saved in a format that can be read by Flash 8 (oops, sorry + thanks Paddy for alerting me to this!)

What's new in Alpha 0.1b:

PHP 4 and PHP 5 support. Tested with PHP 4.4.2 and PHP 5.1.4
Added GET support to the gateway. You can now call the gateway with both POST and GET

Sep 2, 2007 2

Instructions for updating your applications to SWX PHP RC1

I am updating the SWX public gateway to RC1, ahead of today's release of SWX PHP RC1. As I mentioned earlier, this will break some existing applications that use the SWX public gateway. Here are some instructions on updating your applications for RC1:

If your service method returns a simple datatype (number, string, boolean, null):

Change your client-side code to reference result instead of result[0].

If your service method returns a complex datatype (array or object), you do not need to change your code.

This change is because simple data types are no longer returned wrapped in an array.

Example

Pre-RC1:

function resultHandler(event:Object)
{
	// Simple data type is wrapped in an array
	myTextField.text = event.result[0];
}

Becomes, in RC1:

function resultHandler(event:Object)
{
	// The returned simple data type is simply the result itself
	myTextField.text = event.result;
}

I do apologize for making such a radical change this late in the beta program but it was one that simply had to be made.

Note: The SWX Data Analyzer has also been updated to display simple data types correctly.

Aug 25, 2007 4

SWX instance: how to set a fault handler

The SWX class also provides a fault handler that you can use to handler errors during SWX RPC calls. To test it out, modify your code so that it matches the listing below:

import org.swxformat.SWX;
 
var swx:SWX = new SWX();
swx.gateway = "http://localhost:8888/php/swx.php";
swx.encoding = "GET";
swx.debug = true;
swx.timeout = 2; // seconds
 
var callParameters:Object =
{
    serviceClass: "Calculator",
    method: "addNumbers",
    args: [35, 7],
    result: [this, resultHandler],
    timeout: [this, timeoutHandler],
    fault: [this, faultHandler]
}
 
swx.call(callParameters);
 
function resultHandler(event:Object)
{
    status.text = event.result;
}
 
function timeoutHandler()
{
    status.text = "Call timed out!";
}
 
function faultHandler(event:Object)
{
    status.text = event.fault.message;
}

And modify your class so that it generates an error:

<?php
    class Calculator
    {
        function addNumbers($n1, $n2)
        {
            return $n3; // $n3 does not exist!
        }
    }
?>

Test your FLA and you should get something along the lines of Error 8: Undefined variable: n3 in /htdocs/swx/trunk/php/services/Calculator.php, line 7 in the status text field in Flash.

The fault handler also returns API-specific fault codes (e.g., Flickr API error codes) back to Flash.

Aug 25, 2007 0

SWX instance: how to set a timeout handler

You can also specify a timeout handler for your SWX instance to handle calls that take too long to return a result.

Modify the listing so that it matches the one below:

import org.swxformat.SWX;
 
var swx:SWX = new SWX();
swx.gateway = "http://localhost:8888/php/swx.php";
swx.encoding = "GET";
swx.debug = true;
swx.timeout = 2; // seconds
 
var callParameters:Object =
{
    serviceClass: "Calculator",
    method: "addNumbers",
    args: [35, 7],
    result: [this, resultHandler],
    timeout: [this, timeoutHandler]
}
 
swx.call(callParameters);
 
function resultHandler(event:Object)
{
    status.text = event.result;
}
 
function timeoutHandler()
{
    status.text = "Call timed out!";
}

The default timeout duration is 30 seconds but you can override that, as shown here.

In order to make the call actually time out, modify the Calculator class in PHP too to make it sleep for 10 seconds before returning the result. The Calculator class should match the one in the listing below:

<?php
class Calculator
{
    function addNumbers($n1, $n2)
    {
        sleep(10); // Make the call time out!
        return $n1 + $n2;
    }
}
?>

Now test your Flash movie and, after two seconds, you should see the SWX call time out. Timed-out calls are cancelled and will not trigger the result handler at any point in the future.

Aug 25, 2007 2

Instantiating the SWX class

Ideally, you should not have to manually create movie clips and work with low-level native constructs like loadMovie() when working with SWX RPC on a daily basis. The SWX ActionScript Library gives you an abstract, high-level interface for working with SWX RPC.

To use this high-level interface, you need to instantiate the SWX class.

Modify the code listing so that it matches the one below:

import org.swxformat.SWX;
 
var swx:SWX = new SWX();
swx.gateway = "http://localhost:8888/php/swx.php";
swx.encoding = "GET";
swx.debug = true;
 
var callParameters:Object =
{
    serviceClass: "Calculator",
    method: "addNumbers",
    args: [35, 7],
    result: [this, resultHandler]
}
 
swx.call(callParameters);
 
function resultHandler(event:Object)
{
    status.text = event.result;
}

When you run the above example, you should again see 42 in the status text field. Let's look at what has changed.

The biggest change is that you are actually instantiating the SWX class and setting certain properties there (such as the gateway URL, encoding method and whether you want debug information for calls).

Instead of putting call-related parameters directly into a movie clip (you can delete the dataHolder movie clip now as you aren't using it any more), you create a callParameters object and specify the serviceClass, method, and args properties there. But you can do more, you can also specify a result handler that will get called once the data has loaded.

The result handler receives an event object as an argument. That event object has a result property that points to the loaded data.

Aug 25, 2007 0

SWX ActionScript Library: using the prepare() method of the SWX class

When working with SWX RPC, you don't want to continuously serialize complex arguments by hand when call server-side methods. And you don't have to, if you use the prepare() method of the SWX class in the SWX ActionScript Library that comes with SWX PHP.

Save your FLA in the flash/ folder (the one that has the org and com folders) before continuing. (Or add that folder to your ActionScript classpath in the Flash IDE and save your FLA anywhere.)

Modify the code sample so that it matches the listing below:

import org.swxformat.SWX;
 
dataHolder.serviceClass = "Calculator";
dataHolder.method = "addNumbers";
dataHolder.args = [35, 7];
dataHolder.debug = true;
 
SWX.prepare(dataHolder);
 
dataHolder.loadMovie("http://localhost:8888/php/swx.php", "GET");
 
function onEnterFrame()
{
    status.text = dataHolder.result;
}

The prepare() static method of the SWX class simply serializes your arguments into JSON format for you. Notice that the args property in your dataHolder is no longer a string but an ActionScript array with two numbers inside it.

This is definitely far better than manually serializing your arguments by hand but it's still not ideal, is it? For one thing, that onEnterFrame function we're using is not a good practice. It would be really nice if we could have an event handler called when the data arrives instead of polling for it. The SWX ActionScript Library provides that functionality for you too.

Aug 25, 2007 0

Accessing the result property

Using the SWX Data Analyzer to confirm that your SWX data is loading correctly into Flash is great, but what you really want to do is display that data in Flash. You're going to implement a quick hack to get it working and we can evolve the application later to improve it.

Add a TextField instance to the Stage and give it the instance name status.

Next, create an onEnterFrame handler that prints out the value of the result property of the dataHolder movie clip into the status text field.

The complete script at this point is shown below:

dataHolder.serviceClass = "Calculator";
dataHolder.method = "addNumbers";
dataHolder.args = "[35, 7]";
dataHolder.debug = true;
 
dataHolder.loadMovie("http://localhost:8888/php/swx.php", "GET");
 
function onEnterFrame()
{
    status.text = dataHolder.result;
}

Test the movie and you should see the number 42 appear in the status text field.

Now stop for a moment and take a deep breath: You now know exactly how SWX RPC works!

You didn't import any classes, you aren't using an API, you didn't include any external code whatsoever. SWX is completely native to the Flash platform and, if you want to, you can make use of it by using only built-in Flash features like you did here.

Compare this to other technologies like Flash Remoting. Do you actually know exactly how Flash Remoting works? There are numerous classes, lots of code, etc. There's some magic involved that you don't really understand. Not so with SWX RPC. With SWX RPC, your data arrives in native Flash format.

It's important for a technology to be so simple that you can actually conceptualize it completely. However, that doesn't mean that the above method is the way you'd want to use SWX PHP on a daily basis.

For one thing, take a look at how you set the arguments. You placed them in a string. In fact, what you did was serialize the arguments you're sending in JSON format. It's not confusing or difficult to this by hand if you are sending simple arguments like two numbers but what if you wanted to send an array of complex objects to the server? It would get tiresome and impractical very quickly.

The example you just created uses the No API method. In other words, you used pure Flash. No additional classes.

However, to make your life easier, you may want to use just a little API. Specifically, a method to serialize your arguments into JSON format for you would be nice. The SWX ActionScript Library, which comes with SWX PHP, provides just such a method for you (and much, much more!)

Aug 25, 2007 0

SWX Data Analyzer

Before testing the movie, open the SWX Data Analyzer in a separate browser window.

SWX Data Analyzer is a debugging tool that shows you the SWX data that arrives inside your Flash movie.

To make SWX data that loads into the Flash player appear in Analyzer, you turn debug mode on. That's what the line dataHolder.debug = true does.

Now, test your movie and then look in the Analyzer. If all went well, you should see the number 42.

SWX: SWF Data Format

SWX PHP and SWX ActionScript Library Release Candidate 1 Released

Release notes for SWX PHP RC1

Release notes for SWX PHP Beta 1.3 and earlier

Alpha release notes

Instructions for updating your applications to SWX PHP RC1

Example

SWX instance: how to set a fault handler

SWX instance: how to set a timeout handler

Instantiating the SWX class

SWX ActionScript Library: using the prepare() method of the SWX class

Accessing the result property

SWX Data Analyzer

About SWX

SWX on Twitter

Pages

Categories