---
title: "PHP Cookbook"
description: "Master PHP development with this Gitana PHP Driver guide, featuring installation tips, code samples, and advanced querying techniques. (Gitana 4.0)"
product: "Gitana"
version: "4.0"
url: "/documentation/gitana/4.0/developers/cookbooks/php"
---

# PHP Cookbook

## Getting Started

To get started with the PHP driver, visit [Gitana PHP Driver Page](https://gitana.io/documentation/gitana/4.0/developers/drivers/php.html "Gitana PHP Driver Page") or the [Github Page](https://github.com/gitana/cloudcms-php-driver "Github Page"). It can be used in any composer php project.

To install with composer from the command line:

```
composer require cloudcms/cloudcms
```

## Connecting to Gitana

You can connect to Gitana with the php driver by providing a config array containing your keys, which can be obtained from a `gitana.json` file. It should look something like:

```
{
    "clientKey": "{your client key}",
    "clientSecret": "{your client secret}",
    "username": "{your username or auth grant key}",
    "password": "{your password or auth grant secret}",
    "baseURL": "{the url to the Cloud CMS API endpoint}"
}
```

Here is an example of how to load your `gitana.json` file from your project directory and use it to connect:

```php
use CloudCMS\CloudCMS;

// Load configuration from gitana.json file
$config_string = file_get_contents("gitana.json");
$config = json_decode($config_string, true);

// Connect to CloudCMS
$client = new CloudCMS();
$platform = $client->connect($config);
```

## Code Samples

Here are some code samples to help you get started. In these scenarios, we assume that you already have a predefined `$config` variable containing data derived from your `gitana.json` file.

In Cloud CMS, you can have as many repositories as you'd like. And each repository can have multiple branches (similar to Git). The first thing you should do is connect and get the branch that you want to work on.

For the purpose of most of these examples, we'll assume the repository ID is `1234567890abcdef1234` and the branch is `master`.

## Get your Repository

Use the `read_repository` method to fetch a specific repository. The user you've logged in as must have `READ` permissions to the repository. If they do not have read rights, a null response is expected.

```php
use CloudCMS\CloudCMS;

$client = new CloudCMS();
$platform = $client->connect($config);

$repository = $platform->readRepository("1234567890abcdef1234");
if ($repository == null)
{
    throw new Exception("Unable to read repository: 1234567890abcdef1234");
}
```

## Get the Master Branch

Use the `read_branch` method to fetch a specific branch. The user you've logged in as must have `READ` permissions to the branch. If they do not have read rights, a null response is expected.

```php
use CloudCMS\CloudCMS;

$client = new CloudCMS();
$platform = $client->connect($config);

$repository = $platform->readRepository("1234567890abcdef1234");
if ($repository == null)
{
    throw new Exception("Unable to read repository: 1234567890abcdef1234");
}

$branch = $repository->readBranch("master");
if ($branch == null)
{
    throw new Exception("Unable to read master branch");
}
```

## Node Creation

### Create a Node

```
{
    "title": "Custom Article",
    "_qname": "custom:article",
    "type": "object",
    "properties": {
        "title": {
            "type": "string"
        },
        "body": {
            "type": "string"
        },
        "categories": {
            "type": "array",
            "items": {
                "type": "string"
            }
        },
        "rating": {
            "type": "number"
        }
    }
}
```

Create a content instance of this type like this:

```php
use CloudCMS\CloudCMS;

$client = new CloudCMS();
$platform = $client->connect($config);

$repository = $platform->readRepository("1234567890abcdef1234");
if ($repository == null)
{
    throw new Exception("Unable to read repository: 1234567890abcdef1234");
}

$branch = $repository->readBranch("master");
if ($branch == null)
{
    throw new Exception("Unable to read master branch");
}

$obj = array(
    "_type" => "custom:article",
    "title" => "Article #1",
    "body" => "A still more glorious dawn awaits",
    "categories" => array(
        "category1",
        "category2",
        "category3"
    ),
    "rating" => 5
);

$node = $branch->createNode($obj);
```

### Create a Folder

In Gitana, folders are just nodes with the `f:container` feature on them. It must be associated to the root node to be considered part of file folder tree.

```php
use CloudCMS\CloudCMS;
use CloudCMS\Directionality;

$client = new CloudCMS();
$platform = $client->connect($config);

$repository = $platform->readRepository("1234567890abcdef1234");
if ($repository == null)
{
    throw new Exception("Unable to read repository: 1234567890abcdef1234");
}

$branch = $repository->readBranch("master");
if ($branch == null)
{
    throw new Exception("Unable to read master branch");
}

$obj = array(
    "title" => "My Folder",
);

$root = $branch->rootNode();

$folder = $branch->createNode($obj);
$folder->addFeature("f:container", array());

$root->associate($node, "a:child", Directionality::DIRECTED);
```

An easier way to do this is to use the following special properties when the node is created:

- `_parentFolderPath` - the path to the parent folder where the created node should be linked. The folder must exist. If it does not exist, the operation will fail.
- `_fileName` - the `f:filename` to be assigned to the node once it is created.

Alternatively, you can use:

- `_filePath` - an absolute path where the file should be created. This allows you to specify the parent folder path and the file name at the same time.

You can also adjust the association type (between the discovered parent folder and your newly created item).

- `_associationTypeString` - the QName for the newly created association. The default is `a:child`.

Thus, you could do:

```php
use CloudCMS\CloudCMS;

$client = new CloudCMS();
$platform = $client->connect($config);

$repository = $platform->readRepository("1234567890abcdef1234");
if ($repository == null)
{
    throw new Exception("Unable to read repository: 1234567890abcdef1234");
}

$branch = $repository->readBranch("master");
if ($branch == null)
{
    throw new Exception("Unable to read master branch");
}

$obj = array(
    "title" => "My Folder",
    "_parentFolderPath" => "/",
    "fileName" => "my_folder"
);

$folder = $branch->createNode($obj);
```

or:

```php
use CloudCMS\CloudCMS;

$client = new CloudCMS();
$platform = $client->connect($config);

$repository = $platform->readRepository("1234567890abcdef1234");
if ($repository == null)
{
    throw new Exception("Unable to read repository: 1234567890abcdef1234");
}

$branch = $repository->readBranch("master");
if ($branch == null)
{
    throw new Exception("Unable to read master branch");
}

$obj = array(
    "title" => "My Folder",
    "_filePath" => "/my_folder"
);

$folder = $branch->createNode($obj);
```

## Associations

In Gitana, any two nodes can be connected via an association. You can use an out-of-the-box association type, such as `a:linked` or `a:owned` or you can create your own.

Let's imagine that we have two articles that look like this:

- Article #1

```
{
    "_doc": "1234567890abcdef1111",
    "_type": "custom:article",
    "title": "Article #1",
    "body": "a mote of dust suspended in a sunbeam",
    "categories": ["category1", "category2"],
    "rating": 1
}
```

- Article #2

```
{
    "_doc": "1234567890abcdef2222",
    "_doc": "",
    "_type": "custom:article",
    "title": "Article #2",
    "body": "harvesting star light",
    "categories": ["category2", "category3"],
    "rating": 2
}
```

Let's create an association that points from the first article (`1234567890abcdef1111`) to the second article (`1234567890abcdef2222`), like this:

```php
use CloudCMS\CloudCMS;

$client = new CloudCMS();
$platform = $client->connect($config);

$repository = $platform->readRepository("1234567890abcdef1234");
if ($repository == null)
{
    throw new Exception("Unable to read repository: 1234567890abcdef1234");
}

$branch = $repository->readBranch("master");
if ($branch == null)
{
    throw new Exception("Unable to read master branch");
}

$article1 = $branch->readNode("1234567890abcdef1111");
$article2 = $branch->readNode("1234567890abcdef2222");

$association = $article1->associate($article2, "a:linked");
```

You can also find all associations around `article1`. This will include associations that are `INCOMING`, `OUTGOING` and `MUTUAL`.

```php
$associations = $article1->listAssociations();
```

Or find only the `INCOMING` associations:

```php
use CloudCMS\Direction;

$associations = $article1->listAssociations(array(), Direction::INCOMING);
```

Or find only the `OUTGOING` associations of type `a:linked`:

```php
use CloudCMS\Direction;

$associations = $article1->listAssociations(array(), Direction::OUTGOING, "a:linked");
```

## Query

Let's now look at querying for content. This makes use of MongoDB's query language to express some pretty powerful queries. We recommend further reading on [Query Strings](https://gitana.io/documentation/gitana/4.0/engine/query.html "Query Strings").

Let's assume that we have the following:

- Article #1

```
{
    "_type": "custom:article",
    "title": "Article #1",
    "body": "a mote of dust suspended in a sunbeam",
    "categories": ["category1", "category2"],
    "rating": 1
}
```

- Article #2

```
{
    "_type": "custom:article",
    "title": "Article #2",
    "body": "harvesting star light",
    "categories": ["category2", "category3"],
    "rating": 2
}
```

- Article 3

```
{
    "_type": "custom:article",
    "title": "Article #3",
    "body": "we are star stuff",
    "categories": ["category3", "category1"],
    "rating": 3
}
```

### Basic Querying

Find all of the nodes that have a `category` with the value `category1`.

```php
use CloudCMS\CloudCMS;

$client = new CloudCMS();
$platform = $client->connect($config);

$repository = $platform->readRepository("1234567890abcdef1234");
if ($repository == null)
{
    throw new Exception("Unable to read repository: 1234567890abcdef1234");
}

$branch = $repository->readBranch("master");
if ($branch == null)
{
    throw new Exception("Unable to read master branch");
}

$query = array(
    "_type" => "custom:article",
    "category" => "category1"
);

$results = $branch->queryNodes($query);
echo "The size was: " . sizeof($results);

foreach ($results as $node)
{
    echo "Found a result, title: " . $node->data["title"] . ", rating: " . $node->data["rating"];
}
```

### Pagination

If you have a lot of potential query hits, you'll want to paginate. Here is an example where we return results starting at index 2 and hand back at most 5 results.

```php
use CloudCMS\CloudCMS;

$client = new CloudCMS();
$platform = $client->connect($config);

$repository = $platform->readRepository("1234567890abcdef1234");
if ($repository == null)
{
    throw new Exception("Unable to read repository: 1234567890abcdef1234");
}

$branch = $repository->readBranch("master");
if ($branch == null)
{
    throw new Exception("Unable to read master branch");
}

$query = array(
    "_type" => "custom:article",
    "category" => "category1"
);

$pagination = array(
    "skip" => 2,
    "limit" => 5  
);

$results = $branch->queryNodes($query, $pagination);
echo "The size was: " . sizeof($results);

foreach ($results as $node)
{
    echo "Found a result, title: " . $node->data["title"] . ", rating: " . $node->data["rating"];
}
```

### Sorting

Use the pagination option to sort the results as you see fit. Here we sort descending on `rating`.

```php
use CloudCMS\CloudCMS;

$client = new CloudCMS();
$platform = $client->connect($config);

$repository = $platform->readRepository("1234567890abcdef1234");
if ($repository == null)
{
    throw new Exception("Unable to read repository: 1234567890abcdef1234");
}

$branch = $repository->readBranch("master");
if ($branch == null)
{
    throw new Exception("Unable to read master branch");
}

$query = array(
    "_type" => "custom:article",
    "category" => "category1"
);

$pagination = array(
    "sort" => array(
        "rating" => -1
    );
);

$results = $branch->queryNodes($query, $pagination);
echo "The size was: " . sizeof($results);

foreach ($results as $node)
{
    echo "Found a result, title: " . $node->data["title"] . ", rating: " . $node->data["rating"];
}
```

### Query for values in a range

Find all of the articles where the rating is greater than or equal to 2.  
This demonstrates the power of MongoDB's query language. You'll note that since this is php, we have to escape the `$` symbol.

```php
use CloudCMS\CloudCMS;

$client = new CloudCMS();
$platform = $client->connect($config);

$repository = $platform->readRepository("1234567890abcdef1234");
if ($repository == null)
{
    throw new Exception("Unable to read repository: 1234567890abcdef1234");
}

$branch = $repository->readBranch("master");
if ($branch == null)
{
    throw new Exception("Unable to read master branch");
}

$query = array(
    "_type" => "custom:article",
    "rating" => array(
        "\$gte" => 2
    )
);

$results = $branch->queryNodes($query);
```

## Search for Nodes

Let's now look at searching for content. This makes use of ElasticSearch's DSL to express some very powerful full text and structured searches. We recommend further reading on [Search within Gitana](/documentation/gitana/4.0/engine/search.md).

We also suggest reading up on [Query Strings](/documentation/gitana/4.0/engine/query.md) to understand how you can write searches textually (in addition to structuring them as JSON objects):

Let's assume that we have the following:

- Article #1

```
{
    "_type": "custom:article",
    "title": "Article #1",
    "body": "a mote of dust suspended in a sunbeam",
    "categories": ["category1", "category2"],
    "rating": 1
}
```

- Article #2

```
{
    "_type": "custom:article",
    "title": "Article #2",
    "body": "harvesting star light",
    "categories": ["category2", "category3"],
    "rating": 2
}
```

- Article 3

```
{
    "_type": "custom:article",
    "title": "Article #3",
    "body": "we are star stuff",
    "categories": ["category3", "category1"],
    "rating": 3
}
```

### Full Text Search

Find all of the nodes with the word `star`. Simple enough!

```php
use CloudCMS\CloudCMS;

$client = new CloudCMS();
$platform = $client->connect($config);

$repository = $platform->readRepository("1234567890abcdef1234");
if ($repository == null)
{
    throw new Exception("Unable to read repository: 1234567890abcdef1234");
}

$branch = $repository->readBranch("master");
if ($branch == null)
{
    throw new Exception("Unable to read master branch");
}

$results = $branch->searchNodes("star");
```