Skip to end of metadata
Go to start of metadata

<ac:macro ac:name="unmigrated-inline-wiki-markup"><ac:plain-text-body><![CDATA[

<ac:macro ac:name="unmigrated-inline-wiki-markup"><ac:plain-text-body><![CDATA[

Zend Framework: Zend_Service_Akismet Component Proposal

Proposed Component Name Zend_Service_Akismet
Developer Notes http://framework.zend.com/wiki/display/ZFDEV/Zend_Service_Akismet
Proposers Matthew Weier O'Phinney
Revision 1.0 - 10 January 2007: First draft. (wiki revision: 9)

Table of Contents

1. Overview

Zend_Service_Akismet provides a simple interface for interacting with the Akismet API. Akismet provides a REST-based service for checking comment spam and reporting spam and ham (non-spam) comments.

2. References

3. Component Requirements, Constraints, and Acceptance Criteria

  • Implements verify-key method
  • Implements comment-check method
  • Implements submit-spam method
  • Implements submit-ham method
  • Allows resetting blog URL and API key at will

4. Dependencies on Other Framework Components

  • Zend_Service_Abstract
  • Zend_Service_Exception
  • Zend_Http_Client

5. Theory of Operation

A Zend_Service_Akismet object is instantiated with a location URL and an API key. After that, the developer need only call one of the API methods, each of which returns a boolean.

6. Milestones / Tasks

  • Milestone 1: Proposal published
  • Milestone 2: Proposal acceptance
  • Milestone 3: Working, tested code checked into incubator
  • Milestone 4: Documentation checked into incubator

7. Class Index

  • Zend_Service_Akismet

8. Use Cases

UC-01
UC-02
UC-03
UC-04
UC-05

9. Class Skeletons

]]></ac:plain-text-body></ac:macro>

]]></ac:plain-text-body></ac:macro>

Labels:
None
Enter labels to add to this page:
Please wait 
Looking for a label? Just start typing.
  1. Jan 22, 2007

    <p>Three comments:</p>

    <p>1. I know you're mirroring the Akismet API, but isSpam() would be a better method name than commentCheck() given the return value. Even checkComment() would be better. Most people using this class probably won't even look at the official Akismet API documentation.</p>

    <p>2. To match other Zend Framework parameter arrays, camelCase names would be preferable. A simple method could convert for posting.</p>

    <p>3. I believe you meant to use $path in _makeApiCall().</p>

    <p>Otherwise, looks good!</p>

    1. Feb 02, 2007

      <p>Regarding (1) and (2), I feel following the Akismet API makes sense here. People coming from using it directly or coming to ZF looking to see if we implemented it will feel comfortable and not need to change their code drastically to utilize it. Adding in translation layers on incoming parameters is more code overhead that isn't truly necessary as well.</p>

      <p>Regarding (3) – thanks for the catch!</p>

  2. Jan 22, 2007

    <p>I agree with Matthew above.  I think that most people would rather have logistical method names for instance:</p>
    <ul>
    <li>commentCheck => isSpam</li>
    </ul>

    <ul>
    <li>submitHam => Ham doesn't really tell us what it should do... something like NotSpam or FalsePositive<br />
    Just a thought about the API Key... one would always have to have a valid api key, so why not add the connection into the constructor to check the api key and throw an exception if it fails? </li>
    </ul>

    1. Jan 22, 2007

      <p>Well, submitHam() is probably okay because that's a usage coined by Akismet to define all non-spam messages. Also, it shouldn't check the API key automatically because that's an extra call, and unnecessary for anything other than testing.</p>

      <p>However, you might swap the parameter order of the constructor to match that of other Zend_Service classes (Amazon, Flickr, Yahoo!, etc.), where API key or application ID comes first.</p>

      1. Jan 23, 2007

        <p>The API key you are probably correct.</p>

        <p>However the submitHam is still harder... Most people when using the Akismet service really aren't going to be looking into the definitions of it but more so what the functions are actually doing. For instance: most users know what Akismet does but aren't aware of the functionality because it has mostly been implemented for them (ex: wordpress). </p>

    2. Feb 02, 2007

      <p>I like the idea of checking the API key on construct (or rather, when setApiKey() is called) – this will notify the developer early if the key is invalid. I'm thinking that it should set a property that we can check to determine if the key is invalid. Then, if an API call other than verifyKey is made when the API key is invalid, an exception will be thrown.</p>

      1. Feb 02, 2007

        <p>But is it necessary to check the API on every submitted comment? Generally, once you have an API key you have one forever, unless you abuse it. Most of the time, there's not even a reason to check it once, since you have to go through the process to register. What I mean by that is that you don't have a key and then need to "enable" it or something.</p>

        <p>Also, the developer is going to know pretty quickly if the key is invalid because commentCheck() is going to throw an exception, most likely with an error message saying just that.</p>

        <p>About naming, it's not a huge deal, but from the name "commentCheck" can you guess what it returns? It could be anything.</p>

  3. Feb 05, 2007

    <ac:macro ac:name="note"><ac:parameter ac:name="title">Zend Comments</ac:parameter><ac:rich-text-body>
    <p>The proposal is approved for incubator development, provided that the following items are addressed:</p>
    <ul>
    <li>Move the API key to the first argument of the constructor</li>
    <li>Provide reasonable notification (e.g., through a property or exception) of failures, such as when a service call is made with an invalid key.</li>
    <li>In the docs, note any differences between the ZF component and the Akismet API (e.g. naming differences), if any, so that those familiar with one can easily see the differences of the other.</li>
    </ul>
    </ac:rich-text-body></ac:macro>

    1. Feb 06, 2007

      <p>The initial revision has been checked into the incubator in revision 3234. commentCheck has been replaced with isSpam(), the API key is now the first argument to the constructor, the HTTP adapter class accessor has been removed (the proper way to to do this is with setHttpClient(), inherited from Zend_Service_Abstract), and isSpam() and submitSpam() check for a return value of 'invalid' and throw an exception if found.</p>

      <p>All unit tests have been committed.</p>

      1. Feb 06, 2007

        <p>Looks good, Matthew.</p>