Skeleton Application¶
This section describes how to build a Doctrine in Apigility application from the Apigility Skeleton.
First clone the Apigility Skeleton module:
git clone git@github.com:zfcampus/zf-apigility-skeleton
cd into the zf-apigility-skeleton and require these repositories:
composer require zfcampus/zf-apigility-doctrine
composer require doctrine/doctrine-orm-module
composer require zendframework/zend-mvc-console
When prompted select the config/modules.config.php
file to add the new module with the exception of the ZF\Apigility\Doctrine\Admin
which should be added to the config/development.config.php.dist
.
The direction to include zend-mvc-console
is debatable. This module will no longer be maintained in the future but the discussion of
how to replace it is outside the scope of this book.
Db Module¶
For the entities in my application I create a module called simply ‘Db’. Your mileage may vary as this is often given the namespace of the application or company name. At any rate this will be the module where your XML annotations and entity classes are stored.
You will be using the command line to create your entities. It should be rare to create a custom function inside an entity as these
usually belong in the
Repository
for the entity instead. Following this rule your entities can be managed by the command line tool orm:generate-entities
. This command
takes an argument of the path to create the entities. If you give it the path module/Db/src
it will create the entities in the
``module/Db/src/Db/Entity directory based on the namespace of the entities. This shows that we need the subdir Db under src. In
recent Zend Framework work the autoloading of modules has been moved to the composer.json file and you can still use that but you must be
sure to have the correct directory structure for the code generation.
Inside the Db module create a config
directory and inside that directory create an orm
directory. This is where you will export
your entity metadata to from Skipper.
config/autoload/local.php¶
You’ll need to create a configuration for Doctrine in your local.php. This file is used so each deployment can have independent configuration. Here is an example file
<?php
return array(
'doctrine' => array(
'connection' => array(
'orm_default' => array(
'driverClass' => 'Doctrine\\DBAL\\Driver\\PDOMySql\\Driver',
'params' => array(
'user' => 'root',
'password' => '123',
'host' => 'mysql',
'dbname' => 'etreedb',
'port' => '3306',
'charset' => 'utf8',
'collate' => 'utf8_general_ci',
),
),
),
),
);
Export Metadata and Create Entities¶
For a brand new ERD export the XML to the module/Db/config/orm
directory and add the driver config to
your module.config.php file:
'doctrine' => [
'driver' => [
'db_driver' => [
'class' => 'Doctrine\\ORM\\Mapping\\Driver\\XmlDriver',
'paths' => [
__DIR__ . '/orm',
],
],
'orm_default' => [
'class' => 'Doctrine\\ORM\\Mapping\\Driver\\DriverChain',
'drivers' => [
'Db\\Entity' => 'db_driver',
],
],
],
],
then run:
php public/index.php orm:generate-entities module/Db/src
and your PHP skeleton code will be done.
Recommended Extension Repositories¶
Migrations and Fixtures¶
This is a new topic to many developers so I’m including this special note to you, reader, to become familiar with them. migrations and fixtures
Doctrine QueryBuilder¶
Implementing the repository zfcampus/zf-doctrine-querybuilder
is the most important extension for Doctrine in Apigility. This repository allows your clients to create complex queries and sorting
on individual resources. For instance if you give a user access to an Performance
resource and that resources returns performances
then zf-doctrine-querybuilder
will allow a client to return only a subset of the data they have access to, for instance just
performances from a given state. Implementation is covered in Doctrine QueryBuilder.
Doctrine Repository Plugins¶
API-Skeletons/zf-doctrine-repository
provides a method to override the default Repository
factory for Doctrine and implements a plugin architecture which can be used
in lieu of dependency injection into repositories. This repository provides a clean method for interacting with external resources from
within a repository and its use is strongly encouraged.
Doctrine Hydrators¶
Covered also in hydrators is API-Skeletons/zf-doctrine-hydrator. This repository includes three hydrator plugins which are used to create a fluent HATEOAS HAL API response.
OAuth2 for Doctrine in Apigility¶
OAuth2 is implemented with several repositories, each building on the last. The first is API-Skeletons/zf-oauth2-doctrine which provies the metadata to attach OAuth2 entities to your existing schema via a dynamic hook to your User entity.
API-Skeletons/zf-oauth2-doctrine-console provies console routes for
managing zf-oauth2-doctrine
resources.
API-Skeletons/zf-oauth2-doctrine-identity should have been a part of
zf-oauth2-doctrine
from the beginning. That being said, this repository replaces the AuthenticatedIdentity
of
zfcampus/zf-mvc-auth
with an identity which contains access to the AccessToken
, User
, Client
, and AuthorizationService
. This allows you to inject the AuthenticationService
into your classes then access the identity via
$authorizationService->getIdentity()
then get the User class via ->getUser()
. The result of all this is a cleaner way to work
with ORM objects only throughout your application.
API-Skeletons/zf-oauth2-doctrine-permissions-acl uses the
identity from zf-oauth2-doctrine-identity
to create ACL permissions on your resources. This module cleanly provides integration
with zfcampus/zf-mvc-auth
and is covered in authorization.
Note
Authored by API Skeletons. All rights reserved.