Alphred: new PHP library

[rice.shawn]

What is Alphred?

Alphred is a PHP library to aid in the creation of workflows for Alfred. Most of Alphred should work with PHP 5.3+ (OS X 10.6+), but some features need PHP 5.4+ (OS X 10.9+). Alphred generally needs Alfred v2.5+ to run.

It's not quite complete because it needs some testing and a bit more documentation. Please help with the former.

 

Features

• Simple AlfredXML generation for script filters, including extended XML attributes
• Create and manage configuration files in ini, json, or sqlite3 from a few lines of code
• Easy http requests with get or post, including data caching
• Use the system keychain to store and retrieve passwords
• Simple logging to single or multiple files as well as the console with variable log levels
• Filter results easily to match a query
• Make your script filters faster by using the cli-server (PHP 5.4+) with almost no change to your existing code
• Easily change dates into strings, exact (1 day, 3 hours, and 23 minutes ago) or fuzzy (yesterday)
• Use title case without any extra work
• fork php scripts to have them run in the background (and they know that they're in the background)
• send asynchonrous notifications with no external library
• know if the user's theme is light or dark (to set different icons)
• write complex workflows in 50-60 lines of code

 

Example

An example workflow (download) that takes your Github Username and Password and grabs a list of your repos and filters them by query is in the example folder. It uses the cli-server. You can see the well-documented code for the script filter and the action script. Without the comments, they reduce to about 60 lines of code together.

-----

 

Mostly Original Post:

 

It seems mostly complete now for a v1 release. It features easy script filter XML generation (with extended XML), an easy way to make http requests, easy results filtering (taken almost verbatim from Deanishe's Python library: thanks, Dean!), keychain interaction, AppleScript, text filters, and more.

 

 

I've squashed all the bugs that I can find, but I still need to write up some tutorials on how to use it, but I figure that I'd make a pre-release available if people want to start playing with it. Do remember that I might change the API a bit before v1.0.0, and I might do that because I'd love to get some feedback on how the library feels or what doesn't work.

 

For now, find v0.9.3-alpha on the Github release page. Just download the attached Alphred.phar file because that's all you need.

To find automagically generated API docs, check out this page. There are links to both PHPDocumentor and Apigen generated docs. Let me know which ones you like better.

There are also a few markdown files, for now, in the repository under the tutorial section, and there is also a very simple example workflow (or the script filter and action files) under the example directory.

 

I'll update this post with more information as we go along, but, for now, that's what I got.

 

Shawn

Edited February 23, 2015 by Shawn Rice

[rice.shawn]

Updated to v0.9.1, fixing a few bugs (need further testing to ensure this entirely).

 

If you have the library already, then, from a terminal, you can do:

php Alphred.phar update-self-master

to get update Alphred.phar to the newest `master` (dev) version.

 

If you were playing around with the CLI-server scripts, then you should re-create them with

php Alphred.phar create-server-scripts

after you update. It produces a fourth file now (alphred_urlencode.sed), which helps with urlencoding to the cli-server. The usage for the cli-server should still be the same:

bash server.sh script-filter.php "{query}"

everything should still be taken care of by `server.php` (make sure that you include that). And `{query}` becomes `$argv[1]` in the script-filter.php (or whatever it is).

[deanishe]

Glad to hear you've fixed lots of bugs, but what does Alphred actually *do*?

IMO, you should consider replacing the OP with a list of Alphred's features, especially those not found in other (PHP) libraries

[rice.shawn]

Glad to hear you've fixed lots of bugs, but what does Alphred actually *do*?

IMO, you should consider replacing the OP with a list of Alphred's features, especially those not found in other (PHP) libraries

 

Will do. Still writing all of that up.

[rice.shawn]

There is a rough draft of some docs on Github (gh-pages) now, including a tutorial that takes you through writing a workflow with Alphred that queries Github for your own repositories, and filters them according to a query. It includes a quick bit on how to use the config utility (to set the username) as well as the Keychain utility (to store the password) and a nice little method to create a secure input box to type in the password. It also takes you through setting different icons for dark and light themes as well as using some date/text filters to let you know when things were last updated, but in easy to digest words. The whole workflow can reduce to about to about 60-70 lines of code if you nix the comments.

 

The docs are still a bit rough, but they should be helpful. I'd love to get some feedback on how coding something with the library feels. It's fairly powerful, but I've tried to keep it simple at the same time. Also, I'd like to know if it seems like anything is missing, i.e. aspects that you would want the library to do that it currently does not.