title: How to build nested responses in an Apigility driven application with a ZfcBase-DbMapper based model?
body: <p>I'm developing a RESTful web application -- <a href="https://apigility.org/" rel="nofollow">Apigility</a> driven and based on the <a href="http://framework.zend.com/" rel="nofollow">Zend Framework 2</a>. For the model layer I'm using the <a href="https://github.com/ZF-Commons/ZfcBase" rel="nofollow"><code>ZfcBase</code></a> <a href="https://github.com/ZF-Commons/ZfcBase/blob/master/src/ZfcBase/Mapper/AbstractDbMapper.php" rel="nofollow"><code>DbMapper</code></a>. The model essentially consists of two entities: <code>Project</code> and <code>Image</code> (<code>1:n</code>) and is currently implemented like this:</p>
  
  <pre><code>ProjectCollection extends Paginator
  ProjectEntity
  ProjectMapper extends AbstractDbMapper
  ProjectService implements ServiceManagerAwareInterface
  ProjectServiceFactory implements FactoryInterface
  </code></pre>
  
  <p>The same structure for <code>Image</code>.</p>
  
  <p>When the resource (<code>/projects[/:id]</code>) is requested, the responsed project entity/entities should contain a list of its/their <code>Image</code> entities.</p>
  
  <p><strong>So, how can/should this <code>1:n</code> structure be implemented?</strong></p>
  
  <p>Subquestions:</p>
  
  <ol>
  <li><p>Does [<code>DbMapper</code>] provide some "magic" for retrieving such tree structures "automatically" without to write <code>JOIN</code>s (or use an ORM)?</p></li>
  <li><p>Does [<code>Apigility</code>] provide some "magic" for building nested responses?</p></li>
  </ol>
  
  <hr>
  
  <pre><code>{
      "_links": {
          "self": {
              "href": "http://myproject-api.misc.loc/projects?page=1"
          },
          "first": {
              "href": "http://myproject-api.misc.loc/projects"
          },
          "last": {
              "href": "http://myproject-api.misc.loc/projects?page=1"
          }
      },
      "_embedded": {
          "projects": [
              {
                  "id": "1",
                  "title": "project_1",
                  "images": [
                      {
                          "id": "1",
                          "title": "image_1"
                      },
                      {
                          "id": "2",
                          "title": "image_2"
                      }
                  ],
                  "_links": {
                      "self": {
                          "href": "http://myproject-api.misc.loc/projects/1"
                      }
                  }
              },
              {
                  "id": "2",
                  "title": "project_2",
                  "images": [
                      {
                          "id": "3",
                          "title": "image_3"
                      },
                      {
                          "id": "4",
                          "title": "image_4"
                      }
                  ],
                  "_links": {
                      "self": {
                          "href": "http://myproject-api.misc.loc/projects/1"
                      }
                  }
              }
          ]
      },
      "page_count": 1,
      "page_size": 25,
      "total_items": 1
  }
  </code></pre>
  
  <hr>
  
  <p><strong>EDIT</strong></p>
  
  <p>The output I'm currentliy getting is:</p>
  
  <p><strong><code>/projects/:id</code></strong></p>
  
  <pre><code>{
      "id": "1",
      "title": "...",
      ...
      "_embedded": {
          "images": [
              {
                  "id": "1",
                  "project_id": "1",
                  "title": "...",
                  ...
                  "_links": {
                      "self": {
                          "href": "http://myproject-api.misc.loc/images/1"
                      }
                  }
              },
              {
                  "id": "2",
                  "project_id": "1",
                  "title": "...",
                  ...
                  "_links": {
                      "self": {
                          "href": "http://myproject-api.misc.loc/images/2"
                      }
                  }
              },
              {
                  "id": "3",
                  "project_id": "1",
                  "title": "...",
                  ...
                  "_links": {
                      "self": {
                          "href": "http://myproject-api.misc.loc/images/3"
                      }
                  }
              }
          ]
      },
      "_links": {
          "self": {
              "href": "http://myproject-api.misc.loc/projects/1"
          }
      }
  }
  </code></pre>
  
  <p>So it works for one single object. But not for collections, where single items include futher collections:</p>
  
  <p><strong><code>/projects</code></strong></p>
  
  <pre><code>{
      "_links": {
          "self": {
              "href": "http://myproject-api.misc.loc/projects?page=1"
          },
          "first": {
              "href": "http://myproject-api.misc.loc/projects"
          },
          "last": {
              "href": "http://myproject-api.misc.loc/projects?page=24"
          },
          "next": {
              "href": "http://myproject-api.misc.loc/projects?page=2"
          }
      },
      "_embedded": {
          "projects": [
              {
                  "id": "1",
                  "title": "...",
                  ... &lt;-- HERE I WANT TO GET ["images": {...}, {...}, {...}]
                  "_links": {
                      "self": {
                          "href": "http://myproject-api.misc.loc/projects/1"
                      }
                  }
              },
              {
                  "id": "2",
                  "title": "...",
                  ... &lt;-- HERE I WANT TO GET ["images": {...}, {...}, {...}]
                  "_links": {
                      "self": {
                          "href": "http://myproject-api.misc.loc/projects/2"
                      }
                  }
              },
              {
                  "id": "3",
                  "title": "...",
                  ... &lt;-- HERE I WANT TO GET ["images": {...}, {...}, {...}]
                  "_links": {
                      "self": {
                          "href": "http://myproject-api.misc.loc/projects/3"
                      }
                  }
              }
          ]
      },
      "page_count": 24,
      "page_size": 3,
      "total_items": 72
  }
  </code></pre>
  
  <hr>
  
  <p><strong>EDIT</strong></p>
  
  <p>I edited my code and made a step to the goal.</p>
  
  <p>It could not work, since my <strong><code>ProjectService#getProjects()</code></strong> was just returning the projects' data from the database, not enriched with the images:</p>
  
  <pre><code>public function getProjects() {
      return $this-&gt;getMapper()-&gt;findAll();
  }
  </code></pre>
  
  <p>edited to:</p>
  
  <pre><code>public function getProjects() {
      $projects = $this-&gt;getMapper()-&gt;findAll();
      foreach ($projects as $key =&gt; $project) {
          $images = $this-&gt;getImageService()-&gt;getImagesForProject($project['id']);
          $projects[$key]['images'] = $images;
      }
      return $projects;
  }
  </code></pre>
  
  <p>and the <strong><code>ProjectMapper#findAll()</code></strong></p>
  
  <pre><code>public function findAll() {
      $select = $this-&gt;getSelect();
      $adapter = $this-&gt;getDbAdapter();
      $paginatorAdapter = new DbSelect($select, $adapter);
      $collection = new ProjectCollection($paginatorAdapter);
      return $collection;
  }
  </code></pre>
  
  <p>edited to:</p>
  
  <pre><code>public function findAll() {
      $select = $this-&gt;getSelect();
      $adapter = $this-&gt;getDbAdapter();
      $paginatorAdapter = new DbSelect($select, $adapter);
      // @todo Replace the constants with data from the config and request.
      $projects = $paginatorAdapter-&gt;getItems(0, 2);
      $projects = $projects-&gt;toArray();
      return $projects;
  }
  </code></pre>
  
  <p>Now I get the wished output:</p>
  
  <pre><code>{
      "_links": {
          "self": {
              "href": "http://myproject-api.misc.loc/projects"
          }
      },
      "_embedded": {
          "projects": [
              {
                  "id": "1",
                  "title": "...",
                  ...
                  "_embedded": {
                      "images": [
                          {
                              "id": "1",
                              "project_id": "1",
                              "title": "...",
                              ...
                              "_links": {
                                  "self": {
                                      "href": "http://myproject-api.misc.loc/images/1"
                                  }
                              }
                          },
                          {
                              ...
                          },
                          {
                              ...
                          }
                      ]
                  },
                  "_links": {
                      "self": {
                          "href": "http://myproject-api.misc.loc/projects/1"
                      }
                  }
              },
              {
                  "id": "2",
                  "title": "...",
                  ...
                  "_embedded": {
                      "images": [
                          ...
                      ]
                  },
                  ...
              }
          ]
      },
      "total_items": 2
  }
  </code></pre>
  
  <p>But it's a little bit crappy solution, isn't it? What I'm actually doing, is: I'm just replacing a part of the Apigility data retrieving functionality... Anyway, I don't like this solution and want to find a better one (an "Apigility conform solution").</p>