Snuze

Snuze, a (fledgling) PHP client for the Reddit API

About Snuze

Snuze is a PHP client interface for Reddit's API.

Snuze is designed to help you quickly build bots or other applications that interact with the Reddit service, without having to learn much about how Reddit's API works. Some of Snuze's key features include:

You can use one installed copy of Snuze to power multiple bots or scripts that interact with Reddit under different accounts.

Preview Release Phase

Snuze is in a preview release phase with limited functionality. The current version supports some common read-only actions while the overall design is being stabilized. Use this release to spider Reddit data for analysis, scan your favorite subreddits for new links, or other tasks that don't involve posting/submitting data. See the feature roadmap for details about what's coming next.

Overview Contents:

Usage Overview

Snuze is object-oriented, and comes with a set of classes that encapsulate common Reddit entities. You configure and interact with a Snuze object, and it returns other objects for accessing the underlying data.

For example, when you fetch a subreddit, Snuze will give you a Subreddit object:

$sub = $snuze->fetchSubreddit('funny');
echo 'I got a subreddit called ' . $sub->getDisplayName() . PHP_EOL;
echo 'It has ' . $sub->getSubscribers() . ' subscribers!' . PHP_EOL;
I got a subreddit called funny
It has 25802523 subscribers!

When you fetch some links from a subreddit, Snuze returns an iterable collection of Link objects:

foreach ($snuze->fetchLinksHot('jokes', 3) as $link) {
   echo 'I found a joke: ' . $link->getTitle() . PHP_EOL;
}
I found a joke: Why don't blind people skydive?
I found a joke: How do you get Dick from Richard?
I found a joke: My doctor told me today that I was too sweet.

You can also get the raw JSON, if you want to. Snuze exposes it through a toJson() method:

PHP code

$userJson = $snuze->fetchUser('shaunc')->toJson();

See the Using Snuze page for a closer look at some common activities.

A complete class and method reference is available to see what each type of object can do.

Persistence Overview

If you want to save what you fetch, Snuze supports persisting some Reddit data. Two storage providers are built in:

The SQLite storage provider lets Snuze keep track of API authentication tokens in a small data file. This reduces requests to Reddit's servers, making you a more polite API user. The SQLite storage provider requires no setup and no database server, but is limited to storing auth tokens only. This is the default storage provider.

In addition to storing authentication tokens, the MySQL storage provider lets you persist certain objects (subreddits, links, comments etc.) from within your application. This can be useful if you want to perform some analysis on the Reddit data you retrieve. Using the MySQL persistence requires a MySQL server.

Each storage provider implements Mapper objects that let you save or load objects from storage. You get a Mapper of the desired type from the Snuze instance, and use it to store or retrieve an object. For example,

//Save the 100 newest posts from /r/pics to the database
foreach ($snuze->fetchLinksNew('pics', 100) as $link) {
   $snuze->getLinkMapper()->persist($link);
}

//Load /r/memphis from the database, if it exists there
if ($sub = $snuze->getSubredditMapper()->retrieve('memphis')) {
   echo "{$sub->getDisplayNamePrefixed()}: {$sub->getPublicDescription()}" . PHP_EOL;
}
r/memphis: The Reddit community of Memphis, TN.

Of course, you can ignore these storage providers altogether, and have your application save data on its own.

Requirements

Snuze has the following hard requirements:

While not absolutely necessary, it's also useful to have:

Installing Snuze

Snuze source code is available directly from GitHub and via Packagist.

It's strongly encouraged that you use Composer to install Snuze. This is the only supported installation method.

Create a directory where you want to develop your Reddit bot(s) or script(s), then run composer require --dev snuze/snuze to pull in Snuze:

[user@host ~]$ mkdir mybot && cd mybot
[user@host ~/mybot]$ composer require --dev snuze/snuze

The --dev is important, as the current release version is < 1.0. This will install Snuze inside of Composer's standard vendor directory structure. Now you're ready to create your first Snuze script! Visit the Getting Started page to get a basic script up and running in just a few minutes.

Configuration

All configuration for Snuze is controlled by an array you pass into the SnuzeFactory.

To see an example, check out the Getting Started page.

For a complete list of options, see the Configuration page.

Feature Roadmap

Snuze is being actively developed, but the current "zero branch" is a preview release and has limited functionality. It can handle the following types of objects:

Future releases will adhere to the following milestones, give or take:

There's no particular time frame for any given milestone.

Reporting Bugs and Getting Help

If you find a bug in Snuze and you have a GitHub account, the best way to report it is to open a new GitHub issue. Describe what happened, and if Snuze threw an exception, please include it in your report. If the bug can be intentionally reproduced, try to add a snippet of code that will trigger it.

To report a bug without a GitHub account, or for general questions, suggestions, and other discussions, check out /r/snuze on Reddit.