camel

A library designed to help facilitate SharePoint CAML query construction

Build Status

• master:

Install

"require" : {
    "dcarbone/camel" : "@stable"
},

Initialization

To begin, simply create a new Camel.

use \DCarbone\Camel\Camel;

$camel = new Camel();

Humps

Once you have created your Camel, you start adding humps!

There are 3 types of humps:

• Where
• OrderBy
• GroupBy

You may add them to your Camel in one of two ways:

// Returns a \DCarbone\Camel\Hump\Where instance that is attached to $camel
$camel->where();

// Alternatively...
$where = new \DCarbone\Camel\Hump\Where();
$camel->setWhere($where);

The same applies for all humps, and both are perfectly acceptable ways of going about it.

Nodes

There are 3 primary types of nodes:

• ComparisonOperator
• LogicalJoin
• ValueNode

Here is a quick breakdown of each:

ComparisonOperator

These will probably be the most commonly used nodes in your Camel. I believe I have implemented every possible Comparison Operator supported by the SharePoint CAML query system. If I missed one, let me know!

LogicalJoin

There are only two of these:

• AndNode
• OrNode

To keep things DRY, I have most of the logic necessary for these nodes in their base class:

• AbstractLogicalJoinNode

ValueNode

These nodes are typically only used inside of the aforementioned ComparisonOperator nodes, and allow you to compare an input value to a column / etc. in your list.

Each ComparisonOperator has a distinct list of allowable ValueNodes, so check their class definition to see what they are.

Simple Example

Lets say you have a SharePoint list that looks somewhat like this:

Title	Age	Gender	Profession
Daniel	28	Male	Software Developer
Elizabeth	25	Female	Project Manager
David	59	Male	Oncologist
Beatrice	22	Female	Med Student
Anna	20	Female	Retail

And you want to get all the females back. You could do something like this:

$camel->where()
    ->eq()
        ->fieldRef()->attribute('name', 'Gender')->end()
        ->value()->attribute('type', 'Text')->nodeValue('female');

$queryXML = (string)$camel;

The above would produce the following:

<Query xmlns="">
  <Where>
    <Eq>
      <FieldRef Name="Gender" />
      <Value Type="Text">female</Value>
    </Eq>
  </Where>
</Query>

You can also do logical joins.

$camel->where()
    ->orNode()
        ->eq()
            ->fieldRef()->attribute('name', 'Title')->end()
            ->value()->attribute('type', 'Text')->nodeValue('Daniel')->end()
        ->end()
        ->eq()
            ->fieldRef()->attribute('name', 'Title')->end()
            ->value()->attribute('type', 'Text')->nodeValue('David')->end();

The above will produce:

<Query xmlns="">
  <Where>
    <Or>
      <Eq>
        <FieldRef Name="Title" />
        <Value Type="Text">Daniel</Value>
      </Eq>
      <Eq>
        <FieldRef Name="Title" />
        <Value Type="Text">David</Value>
      </Eq>
    </Or>
  </Where>
</Query>

You may also nest to your heart's content.

$camel->where()
    ->orNode()
        ->eq()
            ->fieldRef()->attribute('name', 'Title')->end()
            ->value()->attribute('type', 'Text')->nodeValue('Daniel')->end()
        ->end()
        ->orNode()
            ->eq()
                ->fieldRef()->attribute('name', 'Title')->end()
                ->value()->attribute('type', 'Text')->nodeValue('Elizabeth')->end()
            ->end()
            ->orNode()
                ->eq()
                    ->fieldRef()->attribute('name', 'Title')->end()
                    ->value()->attribute('type', 'Text')->nodeValue('Beatrice')->end()
                ->end()
                ->orNode()
                    ->eq()
                        ->fieldRef()->attribute('name', 'Title')->end()
                        ->value()->attribute('type', 'Text')->nodeValue('Anna')->end()
                    ->end()
                    ->eq()
                        ->fieldRef()->attribute('name', 'Title')->end()
                        ->value()->attribute('type', 'Text')->nodeValue('David');

Which produces:

<Query xmlns="">
  <Where>
    <Or>
      <Eq>
        <FieldRef Name="Title" />
        <Value Type="Text">Daniel</Value>
      </Eq>
      <Or>
        <Eq>
          <FieldRef Name="Title" />
          <Value Type="Text">Elizabeth</Value>
        </Eq>
        <Or>
          <Eq>
            <FieldRef Name="Title" />
            <Value Type="Text">Beatrice</Value>
          </Eq>
          <Or>
            <Eq>
              <FieldRef Name="Title" />
              <Value Type="Text">Anna</Value>
            </Eq>
            <Eq>
              <FieldRef Name="Title" />
              <Value Type="Text">David</Value>
            </Eq>
          </Or>
        </Or>
      </Or>
    </Or>
  </Where>
</Query>

Conclusion and Future Development

At the moment, this library serves my needs. If you find this library useful and would like to see something added or changed, please let me know!