Blog

It's been a while since we've had a major feature announcement here at Vae CMS, but this is a big one! We're proud to announce Version 2 of the Vae Data API, which is available and running on all Vae accounts as of today.  The new API is an object-oriented replacement for the current vae() and vae_find() functions in PHP, and is also used by any VaeML tag that accepts a path="" attribute.

The biggest feature of the new release is performance.  The old Vae Data API has long been a major bottleneck for Vae sites, especially on sites with large amounts of data or heavy use of associations.  With the new release, we have addressed both of these issues head-on, and have reduced page rendering times by as much as 90% for some pages.  The upgrade is included in all Vae plans for no additional charge.

Behind the scenes, the new API is powered by a new set of Vae Database servers running our new proprietary database server software, VaeDB.  VaeDB is a ground-up rewrite of Vae's data storage and query engine.  All data  (including associations) is now stored in RAM at all times to enable lightning-fast lookups without having to read from the disk. Additionally, VaeDB analyzes your query history to anticipate future queries and get your data ready before you even ask for it.

The other major feature of the new API is its object-oriented nature.  Since examples are worth 1000 words, here's a quick overview of how the new API works.  Non-coders might want to skip this part.

vae() and vae_find() are now the same function and may be used interchangeably.

They return a VaeContext or VaeQuery object that contains the results of your query.  VaeContext and VaeQuery present mostly the same interface.  Let's start up the example with a familiar looking query that retrieves an Artist by ID:

$artist = vae("artists/13421");

Child structures may be accessed by either the arrow operator or via array notation:

echo $artist->name;
echo $artist['name'];

If your query returned multiple contexts (for example if you asked for a collection), you may iterate over the object just like it was an array:

$artists = vae("artists");
foreach ($artists as $artist) {
  echo $artist->name;
}

You can get the ID, permalink, or type of any context easily, via the arrow operator or array notation:

$artist = vae("artists/13421");
echo $artist->id;           // 13421
echo $artist->permalink;    // artist/freefall
echo $artist->type;         // Collection
echo $artist->name->type;   // TextItem
echo $artist->albums->type; // Collection

You can also get info about the structure represented by the context:

$artist = vae("artists/13421");
echo $artist->structure->id;        // 1269
echo $artist->structure->name;      // Artists
echo $artist->structure->type;      // Collection
echo $artist->structure->permalink; // artist   (URL of page to render by default for permalinks)

You can still get the ID in the foreach block too:

$artists = vae("artists");
foreach ($artists as $id => $artist) {
  echo $artist->name;
}

Run scoped XPath queries via the get() method, which supports any valid VaeQL expression:

$artists = vae("artists");
foreach ($artists as $artist) {
  foreach ($artist->get("albums[type='CD']") as $album) {
    echo $album->name . " is a CD!";
  }
}

All query options that were previously supported are still supported.  We have also added query options for pagination. They get passed in as a parameter, after the query. Supported options include filter, groups, limit, order, paginate, page, and skip:

$artists = vae("artists", array('limit' => 10));
$artists = vae("artists", array('paginate' => 5, 'page' => 2));
$albums = $artists->get("albums", array('order' => 'name'));
$albums = $artists->albums(array('order' => 'name')); // same as above, shortcut syntax

Debugging functions like var_dump() (including serialize(), print_r(), var_export(), etc.) will not work directly on the new objects. However, we've wired up a special method that will allow you to debug your code like many of you have always done.  Just invoke the debug method on the object:

var_dump($artist->debug);

Note:  Internally the debug() method is the same as the data() method, which I'll tell you about in a second.

And for the really geeky, a few more implementation details: The $context variable passed into functions registered with vae_register_hook() will now be a VaeContext object. You may manipulate it in your hook functions just as if you had created it in PHP.  Additionally, you can create a VaeContext object out of your own vanilla PHP arrays by invoking the vae_context() function on that array.

You don't have to do anything at all to enjoy the speed boosts and object-oriented features provided by the new API. 

We've rolled it out onto your sites and you are up and rolling.  You may begin using the Object-Oriented features in your PHP code right away as well.  Over the next few months, we will use statistics gathered from the system to build in further optimizations for speed.

*** IMPORTANT ***

For the most part, this API is backwards-compatible with the old API. There is, however, a few things about the new API that may break your old code, though we checked and don't think they affect any websites currently live.

You may no longer directly iterate over the child structures of a context.  For example, this used to work, but will not work anymore:

foreach (vae("artists") as $artist) {
  foreach ($artist as $structure_name => $value) {
    echo $structure_name . ": " . $value . "\n";
  }
}

This change was necessary in order to combine the vae() and vae_find() functions into a single function.

This would work though:

foreach (vae("artists") as $artist) {
  echo "name:  " . $artist->name  . "\n";
  echo "genre: " . $artist->genre . "\n";
  echo "bio:   " . $artist->bio   . "\n";
}

That is, you want your code to explicitly state the name of the structure you wish to access.

If you need to access context data as an array (like before), just invoke the data() method on the object:

foreach (vae("artists") as $artist) {
  foreach ($artist->data as $structure_name => $value) {
    echo $structure_name . ": " . $value . "\n";
  }
}

Also, you need to be careful using objects in "if" statements, as the object will always return true.  For example, this will not work as expected:

if (vae("artists")) {
  echo "There are artists";
}

You can use the ->count() method to achieve what you want:

if (vae("artists")->count) {
  echo "There are artists";
}

Additionally, you should be careful when casting values to a numeric type.  This will not work as expected:

foreach (vae("artists") as $artist) {
  echo (int)$artist->age;
}

This is because objects may not be directly cast to numeric types.  If you need a numeric value, you'll need to first cast to a string.

foreach (vae("artists") as $artist) {
  echo strftime("%m-%d-%Y", (string)$artist->formed_on);
}

I think that covers most of the breaking changes and gotchas.

Thanks for reading this far.  I hope that this made your day.  I also hope that I explained everything fully and that there are no unforeseen complications or bugs.  If you have any questions or notice any issues, please email [email protected] and we'll get it  ironed out immediately.

I really appreciate your support of Vae Platform, and look forward to bringing you many new toys in the future!

Kevin Bombino
Founder
Vae Platform