CiviCRM Community Forums (archive)

In the discussion of using Doctrine annotations with Civi, we've had some question of how we might add our own annotations. This commit provides an example:

https://github.com/totten/civicrm-core/commit/99bd914ffca7dab7002179967ea6b8f15be48917

For this commit, I'm experimenting with defining a REST interface backed by Doctrine entities. Each Doctrine entity needs a URL based on a URL-friendly name (a "slug" -- eg entity "WorldRegion" corresponds to path "/civicrm/rest/world-region", and the slug is "world-region"). The commit allows one to specify the slug with an extra annotation, "@CiviAPI\Entity", e.g.

<?php
use Doctrine\ORM\Mapping as ORM;
use Civi\API\Annotation as CiviAPI;

/**
 * @CiviAPI\Entity("UberWidget", slug="uber-widget")
 * @ORM\Table(name="civicrm_uber_widget")
 * @ORM\Entity
 */
class UberWidget {
}

Key things to note:

1. In Civi/API/Annotation/Entity.php, it defines the fields of the annotation.
2. In Civi\Core\Container::createAnnotationReader(), it registers the annotation with (roughly):

<?php
use Doctrine\Common\Annotations\AnnotationRegistry;
...
AnnotationRegistry::registerAutoloadNamespace('Civi', $civicrm_base_path);

3. In Civi/API/Registry.php, it builds and stores a cacheable mapping between slugs and class-names. This requires scanning all the entity classes for annotations. Note the calls to getAllClassNames() and getClassAnnotation().

There's more general discussion of creating annotations at http://docs.doctrine-project.org/projects/doctrine-common/en/latest/reference/annotations.html .