coreylib: A PHP repository from robowman

#What's a coreylib?

coreylib is a small PHP library for downloading, caching, and extracting data formatted as XML or JSON.

Basically, you give coreylib a URL, and you get back an object that you can use to extract data from the response.

$rss = coreylib('http://feeds.feedburner.com/github');
echo $rss->get('title');
// prints: The GitHub Blog

Did we mention you get to use jQuery-style CSS selectors to extract the content you want?

#Requirements

PHP 5.2+ with the Client URL (cURL) Library, SimpleXML and/or JSON extensions installed and enabled.

If you want coreylib to be able to cache, you need one of

Write access to the physical file system
MySQL
Memcached

Memcached is definitely the way to go, if you can swing it. Running Ubuntu?

apt-get install memcached php5-memcache

You can also write your own caching implementation, but only if you wanna.

#Getting started

##Step 1: Get the library

Download coreylib from the coreylib GitHub project page.

##Step 2: Add coreylib to your project

Adding coreylib to your PHP project is as easy as including the library into your code.

<?php
require_once('coreylib.php');
// your code goes here:

You only need one file: coreylib.php. You can dump everything else that ships with the download -- that stuff is only needed if you're going to be modifying and building coreylib.

If you're using coreylib with WordPress, you have a couple of options.

Drop it in your theme folder, and import it into your functions.php file.
Drop it in the plugins folder, and activate it from the plugins menu.

##Step 3: Get some data

The easiest place to start is with a familiar stream/schema of data, like RSS or Atom. The GitHub blog should be good for that.

$api = new clApi('http://feeds.feedburner.com/github');
if ($feed = $api->parse()) {
  // now we have data...
} else {
  // something went wrong
}

##Step 4: Inspect your data

With data in hand, you can use the handy-dandy javascript debugging console in your browser to explore the data's structure:

if ($feed = $api->parse()) {
  $feed->inspect();
}

In the console you'll see something like this. Essentially what you're looking at here is the result of json_encode($feed->toArray()), but calling $feed->inspect() inserts the <script></script> block for you, so it's easier.

The console output is structured like this:

feed ->
  attribs -> array(
    // key/value pairs, each an attribute on the <feed> tag:
    'xml:lang' -> 'en-US'
  ), 
  children -> 
    // all of the child tags appearing inside of <feed>
    entry -> array(
      // all of the <entry> tags appearing in <feed>
      0 ->
        children ->
          author ->
            children ->
              name ->
                // the textual content of the <name> tag
                text -> 'rtomayko'
      1 ->
        ...
    )
  )

This output illustrates the relationships between all of the pieces of information, and should help you to construct selectors, which is how you will tell coreylib what data you want to read/manipulate.

Alternative to $feed->inspect(), you can point your browser directly to the coreylib.php script, which will enable you to use the javascript console to run new coreylib queries. Just make sure first to set the COREYLIB_DEBUG constant to true (and don't forget to switch it off again before pushing into production).

Once the page has loaded, open the javascript console, and type this:

coreylib('http://feeds.feedburner.com/github');

You should see:

"Downloading..."
> Object

Pretty much the same result as before. Except now, you can run queries on other URLs quickly and easily, and filter them too:

coreylib('http://feeds.feedburner.com/github', 'entry:eq(2)');
"Downloading..."
> Object
  entry ->
    children ->
      ...

##Step 5: Do something with it!

Once you've figured out how to navigate the webs of your dataset, it's time to go back to PHP, and do something with the content!

<ul>
  <?php if ($feed = coreylib('http://feeds.feedburner.com/github')) { ?>
    <?php foreach($feed->get('entry') as $entry) { ?>
      <li><a href="<?php echo $entry->get('link@href') ?>"><?php echo $entry->get('title') ?></a></li>
    <?php } ?>
  <?php } ?>
</ul>

You may have noticed by now that I keep switching back and forth between some object class clApi and the function I used above, coreylib(). cliApi is what you want to use when you want more finely-grained control over error handling and such.

The complete coreylib API is documented in the wiki (coming soon!).

#The coreylib story

So, this dude coreyweb has a personal website. He coded it all by himself using PHP, and he was very proud. Then one day he got it in his head to make his page more dynamic, with streams from Twitter, and Flickr, and RSS from his favorite blogs.

"This will be easy," he thought to himself. "Why, with all these services providing their own clients, adding those feeds to my site will be a snap!" But soon, he discovered the truth: web service API wrappers suck.

Each service's feed is different, and each client has a unique author. Nobody is singing from the same sheet, and none of them do any sort of caching... usually.

So coreyweb reached out to this other dude named collegeman, and together they hatched a plan to make things easier. "Forget having to learn some crazy API wrapper for each new service," they proclaimed. "Let's write a universal web services client with caching built-in!"

Thus, with little fuss, coreylib was born. And now you can use it in your projects for free.

#Contributing to coreylib

Yes, please.

coreylib is an open source project licensed under the terms of the GNU GPL v2. You can use it in your own applications, modify it if you need to, but you must release your source code when you distribute coreylib as part of another application.

If you want to contribute directly to the coreylib project, you can find the project source code on GitHub.

Also, if you want us to accept your pull requests, you'll need to force conversion of line endings to LF.

robowman/coreylib