Major name refactoring

[bachpedersen]

First draft:
RiakBucket -> Riak\Bucket
RiakBucketProperties -> Riak\BucketProperties
RiakClient -> Riak\Client
RiakExceptions -> Riak\Exceptions ..
RiakKeyStreamer -> Riak\KeyStreamer
RiakLink -> Riak\Link
RiakMapreduce -> Riak\Mapreduce
RiakMrErlangFunction -> Riak\Mapreduce\ErlangFunction
RiakMrFunction.php -> Riak\Mapreduce\Function
RiakMrInput.php -> Riak\Mapreduce\Input\Input
RiakMrInputBucket -> Riak\Mapreduce\Input\Bucket
RiakMrInputKeyDataList -> Riak\Mapreduce\Input\KeyDataList
RiakMrInputKeyList -> Riak\Mapreduce\Input\KeyList
RiakMrJavascriptFunction -> Riak\Mapreduce\JavascriptFunction
RiakMrPhase -> Riak\Mapreduce\Phase
RiakMrResult -> Riak\Mapreduce\Response
RiakMrStreamer -> Riak\Mapreduce\Streamer
RiakObject -> Riak\Object
RiakPutRequestConfiguration -> Riak\Request\PutConfiguration
RiakRequestConfiguration -> Riak\Request\Configuration
RiakGetRequestConfiguration -> Riak\Request\GetConfiguration
RiakStats -> Riak\Stats

[bachpedersen]

Is this breaking too much?

[guilhermeblanco]

Hi,

First of all, let me quote a very known phrase which is completely relevant to this subject:

There are only two hard things in Computer Science: cache invalidation and naming things.

-- Phil Karlton

I think we're a great shape here, huh? =)

Anyway, PHP has a group that is meant to help with some standards. I'm one of the voting members, representing Doctrine umbrella project (Annotations, Cache, DBAL, ORM, MongoODM, CouchODM, etc - around 45 projects). Right now, we're discussing about a Cache interface, but it's still very immature, so I wouldn't bother mentioning as an option. But previous approved PSRs (PHP Standards Recommendation) can easily benefit us. PSR-0, PSR-1 and PSR-2 are all about namespacing, autoloading and naming conventions.
Stripping the PHP code specific part, we could extract a list of naming conventions we could follow. I did some exercise here and selected the relevant list for us:

• A fully-qualified namespace and class must have the following structure ()*
• Each namespace must have a top-level namespace ("Vendor Name").
• Each namespace can have as many sub-namespaces as it wishes.
• Alphabetic characters in vendor names, namespaces, and class names may be of any combination of lower case and upper case.
• Class names MUST be declared in StudlyCaps.
• Class constants MUST be declared in all upper case with underscore separators.
• Method names MUST be declared in camelCase.

PHP itself has some internal rules, like not prefixing or suffixing. Examples:

• Do not use Interface (ie: Countable)
• Do not use Abstract
• Suffix exceptions with Exception
• Non-OOP functions uses underscores for word separation (not being used here)

Next comment I'll cover some basic names.

[guilhermeblanco]

According to previous comment, we can cover one easy already:

• RiakXxxException => Riak\Exception\RiakXxxException
  Example: RiakConnectionException => Riak\Exception\ConnectionException

Now it comes with a decision point. Do you EVER imagine supporting HTTP API also?
If positive, then we should prefix by PBC, otherwise, ignore this. But if positive, then Riak\PBC\ is the new root namespace. I'm gonna assume only PBC, so Riak will be the root namespace.

[bachpedersen]

Thanks a lot, and great work on the standards, this is very good for the future of PHP

Would a vendor root namespace of Riak be ok or should I choose something like this instead:
RiakClient -> Trifork\Riak\Client

As for the PBC vs HTTP I don't think I will do HTTP support, however if someone did I don't think it should change the user facing API.

[bachpedersen]

This is what I got for exceptions:
RiakException -> Riak\Exception\RiakException
RiakBadArgumentsException -> Riak\Exception\BadArgumentsException
RiakConnectionException -> Riak\Exception\ConnectionException
RiakCommunicationException -> Riak\Exception\CommunicationException
RiakResponseException -> Riak\Exception\UnexpectedResponseException
RiakNotFoundException -> Riak\Exception\NotFoundException
RiakNotFoundException -> Riak\Exception\ConflictedObjectException

Then I think Mapreduce should be MapReduce instead, beside that I think first post is still ok?
Unless you have better ideas of cause.

[guilhermeblanco]

@TriKaspar I'm still digesting possibilities, will probably comment later today... =)

[guilhermeblanco]

As of Trifork vs. Riak, Riak is fine... none coded a Riak native implementation, so yours is first and it's already in PECL. =)

[guilhermeblanco]

Root level classes

• RiakClient -> Riak\Client
• RiakBucket -> Riak\Bucket
• RiakObject -> Riak\Object
• RiakLink -> Riak\Link

Support classes

• RiakBucketProperties -> Riak\BucketPropertyList
• RiakStats -> Riak\ServerInfo
• RiakStats -> Riak\PoolInfo

Input configuration (old Request configuration)

• RiakPutRequestConfiguration -> Riak\Input\PutInput
• RiakRequestConfiguration -> Riak\Input\Input
• RiakGetRequestConfiguration -> Riak\Input\GetInput

Output

• RiakKeyStreamer -> Riak\Output\KeyStreamOutput
• RiakGetResponse -> Riak\Output\GetOutput

MapReduce

• RiakMapreduce -> Riak\MapReduce\MapReduce

Phase

• RiakMrPhase -> Riak\MapReduce\Phase\Phase
• RiakMrPhaseLink -> Riak\MapReduce\Phase\LinkPhase
• RiakMrPhaseMap -> Riak\MapReduce\Phase\MapPhase
• RiakMrPhaseReduce -> Riak\MapReduce\Phase\ReducePhase

Input

• RiakMrInput.php -> Riak\MapReduce\Input\Input
• RiakMrInputBucket -> Riak\MapReduce\Input\BucketInput
• RiakMrInputKeyDataList -> Riak\MapReduce\Input\KeyDataListInput
• RiakMrInputKeyList -> Riak\MapReduce\Input\KeyListInput

Output

• RiakMrResult -> Riak\MapReduce\Output\Output
• RiakMrStreamer -> Riak\MapReduce\Output\StreamOutput

Functions

• RiakMrFunction.php -> Riak\MapReduce\Function\Function
• RiakMrErlangFunction -> Riak\MapReduce\Function\LinkFunction
• RiakMrErlangFunction -> Riak\MapReduce\Function\ErlangFunction
• RiakMrJavascriptFunction -> Riak\MapReduce\Function\JavascriptFunction

[guilhermeblanco]

Give me a few more time and I'll provide a more elaborated information.

[bachpedersen]

Great names I must say 👍 I have a couple of questions to a couple of them, but maybe I should wait untill you posted some more info.
I am working on Riak search at the moment so no hurry. :)

[guilhermeblanco]

@TriKaspar I'm thinking over and over on RiakStats and the method names make no sense in the context.
What is a Connection? Maybe either we should rename Client to Connection (Riak\Connection) or rename RiakStats methods to Client.
I'm creating a simple diagram that should expose some of my explanations.

[bachpedersen]

I don't like renaming Client to Connection since it contains parameters for w, dw etc. so its more than a connection.
Changing method names from connections to clients is best imo. (and just as correct)

[guilhermeblanco]

@TriKaspar sure... another option is make w, dw, etc part of *Input, and the only missing Input was Delete.
That could clear Client from attributions it doesn't need to contain, following "S" (Single Responsibility Principle) from SOLID.

[bachpedersen]

Hmm that does sounds like a better option.
Thanks again for helping, this is going to end out being the best designed riak client ;)