Fast setup for zf2 users.

If your project is using the zf2 mvc, you'll want to use the ShardModule which integrates Shard with the standard DoctrineMongoODMModule and DoctrineModule. It also means you can ignore the manual config below.

Hook Shard into the Doctrine configuration process.

Create a Manifest

The first thing to do is create a Manifest. The Manifest constructor takes a configuration array. Configuration keys are:

models

Specifies any document namespaces you want the DocumentManager to use

'models' => [
    'My\Document\Namespace' => 'my/document/directory/'
]

extension_configs

Specifies the extensions you want to enable. The keys are extension names. The values are extension config arrays. If you don't want to pass any config, just set the value to true.

You must always include extension.odmcore

Eg:

'extension_configs' => [
    'extension.odmcore',
    'extension.accesscontrol' => true,
]

service_manager_config

Shard makes extensive use of Zend/ServiceManager/ServiceManager. You don't need to know all the ins and outs of this class, it's just a container for holding services. The config tells the container where to get those services from, and then you can get them by calling $serviceManager->get('serviceName')

'service_manager_config' => [
    'invokables' => [...],
    'factories' => [...],
    'abstract_factories => [...]
]

Putting it all together

You can create a Manifest like this:

$manifest = new Zoop\Shard\Manifest([
    'models' => [
        'My\Document\Namespace' => 'my/document/directory/' //Specify the location of any documents you want to use.
    ],
    'extension_configs' => [
        'extension.accesscontrol' => true //List any extensions you want to enable
    ],
]);

Manifest resources

Once created, the manifest can be used to retrieve all the resources used by all the extensions for the configuration of a DocumentManager. Eg:

$manifest->getModels(); //Array of all the document namespaces required

$manifest->getSubscribers(); //Array of all the event subscribers required

DocumentManager Factory

By default, Shard configures a document manager for development use. It has default useful whilst creating your app, but is not tuned for production performance.

To configure your own document manager to your taste, override the modelmanager service with your own factory.

'service_manager_config' => [
    'factories' => [
        'modelmanager' => 'My\DocumentManager\Factory'
    ]
]

Take a look at Zoop\Shard\ODMCore\DevDocumentManagerFactory for inspiration on creating your own factory.

Using it

With a configured Manifest and DocumentManager factory, you can get the DocumentManger with:

$manifest = new Manifest([...]);
$documentManager = $manifest->getModelManager();

Then just use the DocumentManager, and the extensions will do all their work for you.

Extensions may also provide other services which are available through the ServiceManager. For example, the Serializer extension provides a Serializer:

$serializer = $manifest->getServiceManager()->get('serializer');

Tell Shard who is using documents.

Several Shard extensions need to know who the current authenticated user is and what their roles are be. If the Shard extensions you are using don't need a configured user, then you can skip this bit. The documentation for each extension will note if a user is required.

If you need a configured user, first you need to create a user class.

Creating a simple user class

A simple user should implement the Zoop\Common\User\UserInterface, and may use the Zoop\Shard\User\DataModel\UserTrait. Eg:

use Zoop\Common\User\UserInterface;
use Zoop\Shard\User\DataModel\UserTrait;

//Annotation imports
use Doctrine\ODM\MongoDB\Mapping\Annotations as ODM;
use Zoop\Shard\Annotation\Annotations as Shard;

class User implements UserInterface {

    use UserTrait;
}

Creating a role aware user class

A role aware user is a further requirement of some extensions. It must also implement the Zoop\Common\User\RoleAwareUserInterface, and may use the Zoop\Shard\User\DataModel\RoleAwareUserTrait. Eg:

use Zoop\Common\User\UserInterface;
use Zoop\Common\User\RoleAwareUserInterface;
use Zoop\Shard\User\DataModel\UserTrait;
use Zoop\Shard\User\DataModel\RoleAwareUserTrait;

//Annotation imports
use Doctrine\ODM\MongoDB\Mapping\Annotations as ODM;
use Zoop\Shard\Annotation\Annotations as Shard;

class RoleAwareUser implements UserInterface, RoleAwareUserInterface {

    use UserTrait;
    use RoleAwareUserTrait;
}

Configure the user service

The user service must be configured to return an instance of your user class.

For example you can configure your service as a closure factory:

$manifest = new Zoop\Shard\Manifest([
    ...
    'service_manager_config' => [
        'factories' => [
            ...
            'user' => function(){
                $user = new RoleAwareUser();
                $user->setUsername('toby'); //set the username
                $user->addRole('admin');    //add any roles the user has
                return $user;
            }
        ]
    ]
]);

For example you can configure your service with a factory class:

$manifest = new Zoop\Shard\Manifest([
    ...
    'service_manager_config' => [
        'factories' => [
            ...
            'user' => 'My\Active\User\Factory'
            }
        ]
    ]
]);

Or, you may wish to set the user service directly:

$user = new RoleAwareUser();
$user->setUsername('toby'); //set the username
$user->addRole('admin');    //add any roles the user has

$manifest = new Zoop\Shard\Manifest([...]);
$manifest->getServiceManager()->setService('user', $user);